BCL easyPDF SDK
easyPDF SDK Usermanual
PDF Creator Programming API  |  Download Free Trial  |  Contact Us to Purchase

Native C API

In addition to the standard COM API, easyPDF SDK is also available as a native C API.

Note: there is no native C API for the PDFDocument SDK yet.

Rationale

Almost every language has a way of calling C functions, therefore the C API is our most universal interface. We provide both 32-bit and 64-bit DLLs.

The native C API works by launching an external worker process (also known as a sandbox). This external process is completely isolated. Named pipes are used for communication in between the customer's code and the sandbox.

There are numerous advantages to using this new native C API, instead of the older COM objects:

There are no known disadvantages to using the native C API versus the COM interop API.

Files

The native C API consists of the following files:

c:\Program Files\Common Files\BCL Technologies\easyPDF 8\include\easyPDFPrinter.h
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\include\easyPDFProcessor.h
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\include\easyPDFConverter.h
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easyPDFPrinter.dll
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easyPDFProcessor.dll
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easyPDFConverter.dll
c:\Program Files (x86)\Common Files\BCL Technologies\easyPDF 8\easyPDFPrinter.dll
c:\Program Files (x86)\Common Files\BCL Technologies\easyPDF 8\easyPDFProcessor.dll
c:\Program Files (x86)\Common Files\BCL Technologies\easyPDF 8\easyPDFConverter.dll

32-bit applications on 64-bit Windows must use the following DLLs:

c:\Program Files (x86)\Common Files\BCL Technologies\easyPDF 8\easyPDFPrinter.dll
c:\Program Files (x86)\Common Files\BCL Technologies\easyPDF 8\easyPDFProcessor.dll
c:\Program Files (x86)\Common Files\BCL Technologies\easyPDF 8\easyPDFConverter.dll

In all other cases, the following DLLs must be used:

c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easyPDFPrinter.dll
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easyPDFProcessor.dll
c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easyPDFConverter.dll

Locating the DLLs

We are not providing LIB files. Instead, the functionality is implemented in DLLs, which must be loaded dynamically.

The first step is to locate the DLLs on your system. Although you could hard-code the physical path, that is considered bad practice. We are going to show you how to find the DLLs dynamically, regardless of where easyPDF is installed. This requires quite a bit of code, but this is the most robust solution.

You are not required to understand this code. For now, please just accept that the following code is the best way of locating the DLLs. In the next section, we are going to show you how to use these functions.

// Gets a string value from the registry
static BOOL GetStringFromRegistry(HKEY hKey, LPCTSTR subKey, LPCTSTR name, LPTSTR value, unsigned valueSize)
{
   HKEY key;
   LONG error;
   BOOL result = FALSE;

   if(!subKey || !name || !value || valueSize == 0)
      return FALSE;

   error = RegOpenKeyEx(hKey, subKey, 0, KEY_READ, &key);
   if(error == ERROR_SUCCESS)
   {
      DWORD type = 0;
      DWORD size = 0;

      error = RegQueryValueEx(key, name, 0, &type, 0, &size);
      if(error == ERROR_SUCCESS && (type == REG_SZ || type == REG_EXPAND_SZ) && size > 0)
      {
         memset(value, 0, valueSize * sizeof(TCHAR));
         size = valueSize * sizeof(TCHAR);

         error = RegQueryValueEx(key, name, 0, &type, (LPBYTE)value, &size);

         if(error == ERROR_SUCCESS)
            result = TRUE;
      }

      RegCloseKey(key);
   }

   return result;
}

// Detects if a particular process is running under Wow64 (32-bit process on Win64)
static BOOL IsWow64Proc(HANDLE hProcess)
{
   typedef BOOL (WINAPI * PtrIsWow64Process)(HANDLE, PBOOL);
   BOOL is64 = FALSE;
   PtrIsWow64Process fnIsWow64Process = reinterpret_cast(
      GetProcAddress(GetModuleHandleW(L"kernel32"), "IsWow64Process"));
   return fnIsWow64Process && fnIsWow64Process(hProcess, &is64) && is64;
}

static BOOL GetEasyPDFPath(wchar_t* path)
{
   const wchar_t* keyName;
   if(IsWow64Proc(GetCurrentProcess())) // 32-bit process on 64-bit Windows
      keyName = L"ProgramPath32";
   else if(sizeof(void*) == 8) // 64-bit process on 64-bit Windows
      keyName = L"ProgramPath64";
   else // 32-bit process on 32-bit Windows
      keyName = L"ProgramPath";
   return GetStringFromRegistry(HKEY_LOCAL_MACHINE, L"SOFTWARE\\BCL Technologies\\easyPDF 8", keyName, path, MAX_PATH);
}

static BOOL GetEasyPDFPrinterDLL(wchar_t* path)
{
   if(!GetEasyPDFPath(path))
      return FALSE;
   wcsncat_s(path, MAX_PATH, L"easyPDFPrinter.dll", MAX_PATH);
   path[MAX_PATH - 1] = 0;
   return TRUE;
}

static BOOL GetEasyPDFProcessorDLL(wchar_t* path)
{
   if(!GetEasyPDFPath(path))
      return FALSE;
   wcsncat_s(path, MAX_PATH, L"easyPDFProcessor.dll", MAX_PATH);
   path[MAX_PATH - 1] = 0;
   return TRUE;
}

static BOOL GetEasyPDFConverterDLL(wchar_t* path)
{
   if(!GetEasyPDFPath(path))
      return FALSE;
   wcsncat_s(path, MAX_PATH, L"easyPDFConverter.dll", MAX_PATH);
   path[MAX_PATH - 1] = 0;
   return TRUE;
}

Loading the DLLs

Depending on which SDK you are planning to use, call GetEasyPDFPrinterDLL, GetEasyPDFProcessorDLL or GetEasyPDFConverterDLL:

wchar_t dllFileName[MAX_PATH] = { 0 };
if(!GetEasyPDFProcessorDLL(dllFileName))
   return;

Now that you know the full path to the DLL, you can load it:

HMODULE hDll = LoadLibraryW(dllFileName);

You must hold on to this hDll variable all the way until you no longer need to use easyPDF SDK, at which point you should unload the DLL:

if(hDll)
   FreeLibrary(hDll);

Note that Windows automatically unloads all DLLs when your application exits. However, it is still preferred to manually unload easyPDF.

It is critical that you dispose all SDK objects before unloading the DLL.

You may choose to load easyPDF when your application starts, and keep it loaded for the entire time. Alternatively, you could load and unload easyPDF on-demand. It depends how often you are going to call easyPDF functions.

We have three separate DLLs: Printer, PDFProcessor and PDFConverter. You may load more than one of them at the same time, just make sure to name your variables accordingly. For example: hPrinterDll, hProcessorDll, hConverterDll.

In the next few topics, we are going to discuss each individual SDK separately.