Getting Started with the C++ API

As of 2019 SP2 U2, the C++ API pre-release is considered deprecated and will be discontinued in a future version.

HOOPS Exchange is now available in a new C++ API. The main goal of this API is to provide user applications with code and binary compatibility throughout the evolution of Exchange. When a new version of Exchange is available, the C and C++ API dynamic libraries can simply be dropped into the execution environment without the need to recompile against them.

This page will help you build and use the C++ API for your project.

Building with the C++ API

Package overview

The API is an implicitly shared library, which means that a user application must be linked against the DLL or shared object at build time. As a comparison, the C API provides a library file which must be programmatically loaded at runtime.

Below are the contents of the C++ API package:

  • <hoops_exchange root directory>
    • bin
      • <platform> (DLLs for Windows and .so for Linux)
    • cpp
      • include
    • documentation
      • documentation.exchange
      • documentation.publish
    • lib
      • <platform> (.lib files for Windows)
    • samples
      • data (sample models, sample code, images)
      • exchange (sample applications for HOOPS Exchange)
      • publish (sample applications for HOOPS Publish)

The include folder contains all the necessary header files. It also embeds some headers from the C API in order to share the most common types.

The C++ API is contained in one dynamic library:

  • For Microsoft Visual Studio 2015 either A3DLIBSCpp.dll for release builds or A3DLIBCppd.dll for debug builds
  • For Linux and Android, libA3DLIBSCpp.so
  • For Mac OS, libA3DLIBSCpp.dylib

The only exception is for iOS where the C++ API is actually contained in one static library.

These library files can be found for all available architectures in each corresponding subdirectory in bin.

Finally, for Microsoft Visual Studio only, the linker file A3DLIBSCpp.lib (or A3DLIBCppd.lib for debug builds) can be found in the lib folder.

Building for Microsoft Visual Studio 2015

Open the project properties from the Visual Studio IDE. Then:

  • In Configuration Properties -> General, make sure Character Set is set to Use Unicode Character Set
  • In Configuration Properties -> C/C++
    • In General, add the path to cpp/include to Additional Include Directories
  • In Configuration Properties -> Linker
    • In General, add the path to lib/{ARCH} to Additional Library Directories where {ARCH} is either win32 or win64
    • In Input, add either A3DLIBSCpp.lib for release mode or A3DLIBSCppd.lib for debug mode.

The project is now ready to compile.

To be able to run properly, the execution environment must have access to the correct DLL file: either A3DLIBSCpp.dll or A3DLIBSCppd.dll. There are several ways to do this:

  • Copy the DLL in the output folder of the project.
  • Or add the DLL folder to the PATH environment.
  • Or change the working directory to the DLL folder.

The last two alternatives can be configured from Visual Studio. In the project properties, the PATH and working directory can be set in Configuration Properties -> Debugging.

Building with GCC or Clang

For Linux, Mac OS, and Android environments, the compiler is either GCC or CLang. In both cases, the following options are required in order to build with the C++ API:

  • -I{PATH} where {PATH} is the include folder (cpp)