How to integrate the licensing support in my application?

The following article uses options that are available starting with the Enterprise edition and project type.

The Advanced Licensing Support can be easily integrated with your application. In what follows it will be described how to achieve this by using C code.

Step 1 - Loading and initializing the Licensing library.

The licensing support resource file consists of a DLL. So in order to use it the DLL file must be loaded first.

This code should be added in your application.

// trial function signature
typedef UINT (__stdcall * TrialFcn)(LPCSTR, HWND);

// register function signature
typedef UINT (__stdcall * RegisterFcn)(LPCSTR, LPCWSTR);

int InitLicensingSupport(LPCSTR aKeyCode, HWND aHWnd)
{
  HMODULE hModule = ::LoadLibrary("Trial.dll");
  if(hModule == NULL)
    return -1; // Missing Trial DLL;

  TrialFcn readSettingsProc = reinterpret_cast<TrialFcn>(
    ::GetProcAddress(hModule, "ReadSettingsStr"));

  if(readSettingsProc == NULL)
    return -1; // Missing Trial DLL;

  // Return values:
  // "0" - the application is registered (a valid license key was found);
  // "2" - the application is in trial mode;
  // If the application trial period has expired and the user will NOT enter
  // a valid license key, the process will be killed by the function
  // instead of returning one of the codes above.
  int ret = readSettingsProc(aKeyCode, aHWnd);

  return ret;
}

int DisplayRegistrationDlg(LPCSTR aKeyCode, HWND aHWnd)
{
  HMODULE hModule = ::LoadLibrary("Trial.dll");
  if(hModule == NULL)
    return -1; // Missing Trial DLL;

  TrialFcn displayRegProc = reinterpret_cast<TrialFcn>(
    ::GetProcAddress(hModule, "DisplayRegistrationStr"));

  if(displayRegProc == NULL)
    return -1; // Missing Trial DLL;

  // Return values:
  // "0" - the application is registered (a valid license key was found/entered);
  // "2" - the application is in trial mode;
  int ret = displayRegProc(aKeyCode, aHWnd);

  ::FreeLibrary(hModule);

  return ret;
}

int RegisterLicense(LPCSTR aKeyCode, LPCWSTR aLicense)
{
  HMODULE hModule = ::LoadLibrary("Trial.dll");
  if(hModule == NULL)
    return -1; // Missing Trial DLL;

  RegisterFcn registerLicense = reinterpret_cast<RegisterFcn>(
    ::GetProcAddress(hModule, "RegisterStr"));

  if(registerLicense == NULL)
    return -1; // Missing Trial DLL;

  // Return values:
  // "0" - the license was successfully saved on local machine; notice that the license validation is not done when using the "RegisterStr" function
  // "different than 0" - the license couldn't be saved on local machine
  int ret = registerLicense(aKeyCode, aLicense);

  ::FreeLibrary(hModule);

  return ret;
}

Licensing library exported functions:

ReadSettingsStr - the DLL entry function that does the initialization of the licensing support.
ReadSettingsRetStr - the DLL entry function that does the initialization of the licensing support but will NOT kill the application when trial expired and unlicensed, instead will return a value greater or equal with 4.
DisplayRegistrationStr - the DLL entry function that displays (if necessary) the registration dialog.
RegisterStr - the DLL entry function that you can explicitly call from your application to register the license - it can be used as an alternative to the "DisplayRegistrationStr" function to silently register the license without displaying our registration dialog.

Step 2 - Using the licensing support.


#define kLibraryKey "ECEB5E5E3409A8BCAD544A344B4EA883BD782E7870AC4E8C60B1105FCE02F898BAA30905D069"

// Immediately after the main application is launched initialize licensing support
void OnInit(...)
{
  // Optionally, you can specify a parent window for the licensing messages
  HWND parentWnd = m_hWnd; // can be NULL

  int ret = InitLicensingSupport(kLibraryKey, parentWnd);

  // Trial DLL is missing exit to protect the application
  // (you might choose to handle this differently -  exit application nicely)
  if(ret == -1)
    exit(0);

  // You can save and use the return code (ret) to display the application registration state

  // Continue loading your application...
  // ...

}

// When the client wants to register your application, this is how you should handle it
LRESULT OnRegister(WORD /*wNotifyCode*/, WORD /*wID*/, HWND /*hWndCtl*/, BOOL & /*bHandled*/)
{
  // Display the trial dialog.
  int ret = DisplayRegistrationDlg(kLibraryKey, m_hWnd);

  // You can save and use the return code (ret) to update the application registration state

  return 0;
}

........

Immediately after the main application window is displayed you should initialize licensing support. The InitLicensingSupport method must be executed which will actually display the trial messages.

Options like "Display Frequency Percent", "Show the trial message at first run" may cause a silent switch to trial mode.

The kLibraryKey string needed to start the trial is defined in the Registration Tab, “Library Key” field, in Advanced Installer.

Sample Project

You can find a small sample Advanced Installer project implementing the above functionality here.