Initializing and Terminating a Session

HOOPS Publish uses two different libraries that need to be initialized separately: the A3DLIBS library shares the code for the whole HOOPS Publish and HOOPS Exchange APIs while the PDF library is used internally to implement PDF functionalities.

Loading the A3DLIBS Library and Accessing Functions

A3DLIBS uses explicit linking to access the functions in the API. With explicit linking, the executable using the DLL must make function calls to explicitly load and unload the DLL, and to access the DLL-exported functions through a function pointer. HOOPS Publish is delivered with a unique top-level header file A3DSDKIncludes.h to help access the API. This is the only header that needs to be included in your application. Depending on the level of the product license purchased, certain macros must be defined before including this header:

  • HOOPS_PRODUCT_PUBLISH_STANDARD or HOOPS_PRODUCT_PUBLISH_ADVANCED (depending on the license type you’ve purchased) for HOOPS Publish level.

  • HOOPS_PRODUCT_PUBLISHPLUSEXCHANGE (for mixed use of HOOPS Publish and HOOPS Exchange). This macro is used in addition to HOOPS_PRODUCT_PUBLISH_STANDARD or HOOPS_PRODUCT_PUBLISH_ADVANCED and applies to customers who are using the full version of Exchange or just one reader for integration purposes.

  • If none of the above #DEFINE directives are supplied, then the API defaults to a HOOPS Exchange level.

This top-level header defines two functions to initialize and terminate a session with the A3DLIBS DLL, as well as a macro that automates the definitions of function pointers for the whole API:

  • bool A3DSDKLoadLibrary(const TCHAR *pSDKDirectory = NULL);: The argument specifies the path where the A3DLIBS DLL is located. An empty string specifies that the library is loaded in the current directory, or with any other path search strategy used with the Windows API function LoadLibraryEx.

  • void A3DSDKUnloadLibrary();: The function to call on the end of the process to unload the library.

  • A3D_API: This macro defines function pointers accordingly to the platform used. Its use should be transparent to customers.

In your main code segment, define INITIALIZE_A3D_API before including A3DSDKIncludes.h, then a call to A3DSDKLoadLibrary will automatically load the DLL (A3DLIBS.DLL) and call GetProcAddress on each function. At the end of your program, call A3DSDKUnloadLibrary to unload this library.

#define INITIALIZE_A3D_API
#define HOOPS_PRODUCT_PUBLISH_STANDARD
#include "A3DSDKIncludes.h"
if (!A3DSDKLoadLibrary(_T("")))
{
    printf("Cannot load library\n");
    exit(-1);
}

Initializing the A3DLIBS DLL

Verify that your application is compatible with a particular A3DLIBS library by comparing the version of the A3DLIBS DLL against which you compiled and the version of the A3DLIBS DLL available to your. Obtain the version identifiers for the currently installed A3DLIBS Library by invoking the A3DDllGetVersion function. Evaluate the returned values as follows:

  • Ensure that the value of the piMajorVersion argument matches the A3D_DLL_MAJORVERSION enumeration.

  • Ensure that the value of the piMinorVersion argument is equal to or greater than the A3D_DLL_MINORVERSION enumeration. A3DLIBS provides backward compatibility for earlier releases of the API that have the same major version identifier.

Initialize the A3DLIBS DLL using these version identifiers.

A3DInt32 iMajorVersion = 0, iMinorVersion = 0;
A3DInt32 iRet;
iRet = A3DDllGetVersion(&iMajorVersion, &iMinorVersion);
if(iRet == A3D_SUCCESS) { ... };
iRet = A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MINORVERSION);
if(iRet == A3D_SUCCESS) { ... };

Initializing the PDF Library and Resources

HOOPS Publish uses the Adobe native PDF library. This library must be initialized.

In addition, the directory where specific resources for font management are defined must be initialized. This is all done using the A3DPDFInitializePDFLibAndResourceDirectory function:

iRet=A3DPDFInitializePDFLibAndResourceDirectory(_T("Hoops_Publish_path/bin/resource"));
if(iRet == A3D_SUCCESS) { ... };

When installing HOOPS Publish, the resource directory is provided in the bin directory.

Terminating the PDF Library and A3dlibs DLL

Terminate the PDF library by invoking the A3DPDFTerminatePDFLib function:

iRet = A3DPDFTerminatePDFLib();

Then, terminate HOOPS Publish by calling:

iRet = A3DDllTerminate();
A3DSDKUnloadLibrary();

This last step should not be performed if you’ve used automatic initialization with the HOOPS Exchange Loader.

Handling Errors

Most of the HOOPS Publish API functions return an integer that indicates success or failure. A return value of A3D_SUCCESS indicates success, and any negative return value indicates failure. The following example shows one approach for evaluating this returned result:

A3DInt32 iRet = A3D_SUCCESS;
iRet = A3DPDFDocumentCreateFromPDFFile(in_pdftemplatefile, &pDoc);
if(iRet == A3D_SUCCESS) { ... };

Error codes are detailed in the A3DSDKErrorCodes.h file.