Managing the SocketTools Library Edition License Key

By /

Managing the Library Edition License Key

This article explains how SocketTools Library Edition uses a runtime license key in applications, how the key is stored, and the recommended practices for managing it in source control and automated build environments. This is primarily oriented towards C/C++ developers, however the same general concepts apply to other languages using the SocketTools libraries.

Overview

SocketTools uses a runtime license key to enable licensed functionality in your application. Developers who have purchased a license receive a unique key derived from their serial number. Evaluation users can simply pass an empty string or NULL, and the libraries will operate in evaluation mode.

For C/C++ developers, the runtime key is provided through a small header file that is automatically included by the main SocketTools header. This design keeps integration simple and avoids external configuration files or registry dependencies.

In addition to C and C++, the same general approach to managing the runtime license key applies to any language that can call functions exported from a Windows DLL. SocketTools Library Edition includes language‑specific include files for environments such as Visual Basic 6, PowerBASIC, FreeBasic, and other languages that support external function declarations. In these cases, the license key is still provided as a simple string value passed to the initialization functions in the library. The mechanism is identical: if the key is NULL or an empty string, the library operates in evaluation mode; if a valid key is provided, the library enables licensed functionality.

Because the key is just a string literal, developers using these languages can follow the same best practices recommended for C/C++ projects. The personalized key generated during installation should not be committed to source control, and teams should rely on each developer’s local installation, or a CI system installation, to provide the correct key at build time. Whether the key is stored in a small include file, a module, or a constant declaration depends on the language, but the principle remains the same: treat the key as a build‑time artifact rather than shared project source. This keeps the workflow consistent across languages and avoids exposing license information in public or shared repositories.

How the Default License Header Works

SocketTools ships with a default header named csrtkey11.h (for version 11). This file contains no license key and instructs the libraries to operate in evaluation mode:

#ifndef _INCLUDE_CSRTKEY11_H
#define _INCLUDE_CSRTKEY11_H

#ifndef UNICODE
#define CSTOOLS11_LICENSE_KEY ((LPCSTR)NULL)
#else
#define CSTOOLS11_LICENSE_KEY ((LPCWSTR)NULL)
#endif

#endif // _INCLUDE_CSRTKEY11_H

This header is automatically included by cstools11.h, so no additional steps are required in your project.

Developers who are less familiar with C or C++ may notice that the CSTOOLS11_LICENSE_KEY macro appears to be defined twice in the default header file. This is a common pattern in Windows development that uses the C/C++ preprocessor to select between two different definitions depending on whether the application is being compiled for ANSI (narrow‑character) or Unicode (wide‑character) builds. The UNICODE symbol is defined automatically by most modern Windows project templates, and when it is present, the wide‑character version of the macro is used. If UNICODE is not defined, the ANSI version is selected instead.

The two types used in the macro, LPCSTR and LPCWSTR, are standard Windows data types. LPCSTR means “Long Pointer to a Constant String of CHARs,” where each character is an 8‑bit value. LPCWSTR means “Long Pointer to a Constant String of Wide CHARs,” where each character is a 16‑bit UTF‑16 value. Both types represent pointers to constant, null‑terminated strings in memory. The only difference is the width of the characters they point to. By defining the macro differently for ANSI and Unicode builds, the header ensures that CSTOOLS11_LICENSE_KEY always has the correct type for the project’s character encoding.

It is also important to note that these are C‑style null‑terminated strings. Many other languages distinguish between C‑style strings and their own native string types. For example, Visual Basic uses BSTR values, which include a length prefix and may contain embedded null characters, while languages like PowerBASIC or FreeBasic may use their own managed string formats. When calling functions exported from a DLL, these languages typically convert their native string type into a null‑terminated ANSI or Unicode string as required by the function declaration. Because the SocketTools runtime license key is simply a null‑terminated string literal, it integrates cleanly with these languages as long as the function prototypes are declared correctly.

In both the ANSI and Unicode cases, the default value of the macro is NULL, which tells the SocketTools libraries to operate in evaluation mode until a personalized header is installed. Once the developer installs SocketTools with a valid serial number, the installer replaces this header with one that defines the macro as a literal string containing the runtime license key in the appropriate character format.

How the License Key Is Installed

When you install SocketTools and enter your serial number:

  • The installer generates a runtime license key based on your serial number.
  • The default csrtkey11.h is replaced with a personalized version.
  • The macro CSTOOLS11_LICENSE_KEY expands to a literal string containing your key.

Your application code does not need to change. Including cstools11.h is sufficient.

Best Practices for Source Control

The personalized csrtkey11.h contains your runtime key and should not be stored in source control. We recommend:

  • Adding csrtkey11.h to .gitignore (or your VCS equivalent)
  • Keeping a placeholder file such as csrtkey11.h.default for reference
  • Allowing each developer’s local installation to generate their own personalized header

This prevents accidental disclosure of your runtime key in public or shared repositories. If you publish sample code or open-source projects, make sure you include the default header with the NULL key. This allows anyone to build the project in evaluation mode without exposing your license.

Initializing the SocketTools Libraries

Each SocketTools API includes an initialization function that must be called before using any other functions in that specific library. For example, the FTP API uses FtpInitialize, the HTTP API uses HttpInitialize, the SMTP API uses SmtpInitialize, and so on. These functions perform more than just license validation, they also initialize the Windows Sockets subsystem, security libraries, and other internal components required for the API to function correctly.

Because of this, it is important that the initialization function is called once at the start of your program, before any other API functions are used. A typical C or C++ application will look similar to the following:

if (!FtpInitialize(CSTOOLS11_LICENSE_KEY, NULL))
{
    // handle initialization failure
}

The first parameter is the runtime license key (or NULL for evaluation mode), and the second parameter is reserved for backwards compatibility and should be NULL or 0. After successful initialization, the application can safely call any other functions in the API.

The primary exception to this rule is when using the SocketTools C++ classes. Each class automatically calls its corresponding initialization function as part of the class constructor. This means that developers using the C++ interface do not need to call the initialization functions manually; the required setup is performed automatically when an object is created.

Regardless of whether you are using the procedural APIs or the C++ classes, the initialization step ensures that the underlying networking and security components are ready before any network operations are performed. This helps prevent subtle runtime errors and ensures consistent behavior across all supported Windows versions.

Uninitializing the SocketTools Libraries

Each SocketTools API also provides a corresponding cleanup function, such as FtpUninitialize, HttpUninitialize, SmtpUninitialize, and so on. These functions release internal resources allocated during initialization, including network handles, security contexts, and other subsystem state. Calling the cleanup function is optional; Windows will automatically release these resources when the process terminates but it can be useful if your application needs to explicitly free memory or unload components before shutdown.

The initialization and cleanup functions are reference counted. This means that if your application calls an initialization function multiple times, the corresponding cleanup function must be called the same number of times before the library is fully uninitialized. For example, if FtpInitialize is called three times, then FtpUninitialize must also be called three times to complete the cleanup process. This ensures predictable behavior in applications that dynamically load and unload components or use multiple modules that independently initialize the same API.

For most applications, initialization is performed once at startup and uninitialization once at shutdown. However, the reference counting mechanism provides flexibility for more complex scenarios without requiring developers to track global state manually.

Using SocketTools in CI/CD Environments

Many development teams use automated build systems such as Azure DevOps, GitHub Actions, Jenkins, or TeamCity. SocketTools supports these workflows without requiring you to store secrets in your repository. Install SocketTools on your build server using the same serial number used by the developer responsible for the build configuration. The installer will generate the correct csrtkey11.h on that system, just as it does on a workstation.

This approach provides several benefits:

  • No license keys stored in source control
  • No environment variables or config files required
  • Builds behave identically to local developer builds
  • No risk of leaking keys in CI logs
Regenerating the License Header

If you need to recreate your personalized csrtkey11.h file, SocketTools includes a utility called the License Manager as part of the SDK installation. This tool allows you to generate a header file containing your runtime license key and save it to a location of your choosing.

To create the header file:

  1. Launch the License Manager utility (cdlicmgr.exe)
  2. Check License > Product from the menu bar, ensuring the Library Edition is selected
  3. From the menu bar, select License > Header File
  4. Choose the destination folder where you want the header file to be saved

The default installation path for the License Manager is:

C:\Program Files (x86)\SocketTools 11.0 Library Edition\Bin\cdlicmgr.exe

This utility is especially useful in CI/CD environments or when setting up a new development system. It ensures that your runtime license key is properly embedded in the header file without requiring manual editing or copying from another machine.

License Terms for CI/CD Installations

Your SocketTools license permits multiple installations for a single developer. This includes:

  • A desktop workstation
  • A laptop
  • A dedicated build server or CI agent

If multiple developers use SocketTools, each developer should have their own license. However, a single developer may install the SDK on all systems they personally use, including automated build environments.

Summary
  • The runtime license key is provided through the csrtkey11.h header.
  • The default header enables evaluation mode; installing SocketTools replaces it with your personalized key.
  • Do not commit the personalized header to source control; regenerate it per‑machine as needed.
  • The License Manager can recreate the header, and a command‑line option supports automated builds.
  • Each API requires an initialization call (e.g., FtpInitialize) before use.
  • Cleanup functions (FtpUninitialize, etc.) are optional but available; both are reference counted.
  • The C++ classes handle initialization and cleanup automatically.
  • Other languages (VB6, PowerBASIC, FreeBasic, etc.) follow the same pattern using null‑terminated strings.

See Also

SocketTools Library Redistribution
SocketTools Installer Packages
Creating a Runtime License Key

Shopping Cart
Scroll to Top