The vendor file lmx_server_conf.c customizes the behavior of the LM-X license server at build time. The file's settings and callbacks cannot be changed after the vendor library has been compiled.
Implement only the callbacks that your vendor library needs. Rather than changing the supplied template directly, save your production implementation to a separate file that will be compiled and linked with the vendor library.
Custom HostID callbacks
The custom HostID callbacks are described below.
GetCustomHostid
The GetCustomHostid callback returns the custom HostIDs used by the license server. The server uses this callback only when licenses are generated with LMX_SERVER_HOSTID and LMX_HOSTID_CUSTOM.
For example:
LMX_STATUS LMX_CALLBACK GetCustomHostid(LMX_HOSTID *pHostid, int *npHostids);
Parameters
pHostid[out] Array to populate with one or more LMX_HOSTID values. For each value, set both the binary value/length (sValue, nLength) and the string representation (szValue) as required by the custom HostID format.
npHostids[out] Number of entries written to pHostid.
Return values
Returns LMX_SUCCESS after populating the output array. Returns an appropriate LM-X error status if the custom HostIDs cannot be obtained.
GetHostidContinuousCheckValues
The GetHostidContinuousCheckValues callback returns the schedule for periodic HostID validation. The server uses this callback when LMX_HOSTID_TYPE is LMX_HOSTID_CUSTOM or LMX_HOSTID_DONGLE_HASPHL.
For example:
LMX_HOSTID_CONTINUOUS_CHECK_VALUES GetHostidContinuousCheckValues(void);
Return value
Returns an LMX_HOSTID_CONTINUOUS_CHECK_VALUES structure with the following fields:
Field | Description | Supplied configuration setting |
|---|---|---|
| Minimum number of seconds before the next validation | Random interval from 120 (2 minutes) to 240 (4 minutes) |
tIntervalTo | Maximum number of seconds before the next validation | Random interval from 120 (2 minutes) to 240 (4 minutes) |
| Number of seconds a previously read HostID may be reused | 120 (2 minutes) |
| Number of failed validations allowed before the server shuts down | 3 |
CustomHostidCompare
The CustomHostidCompare callback compares the HostIDs embedded in a license with those discovered on the server. The server uses this callback for licenses generated with LMX_SERVER_HOSTID or LMX_CLIENT_HOSTID.
For example:
LMX_STATUS LMX_CALLBACK CustomHostidCompare(LMX_KEY_HOSTID_TYPE eKeyHostidType, const LMX_HOSTID pLicenseHostid[], int nLicenseHostids, const LMX_HOSTID pSystemHostid[], int nSystemHostids);
Parameters
eKeyHostidType[in] HostID type specified by the license.
pLicenseHostid, nLicenseHostids[in] HostID values embedded in the license and their count.
pSystemHostid, nSystemHostids[in] HostID values obtained from the server environment and their count.
Return values
Returns LMX_SUCCESS when the values match. Returns an LM-X error status when the values do not match or cannot be compared. Returning the status LMX_NOT_IMPLEMENTED lets LM-X apply its default comparison behavior; the supplied configuration uses this status by default.
Server settings
Server setting callbacks are described below.
IsReportingMissingFeaturesEnabled
The IsReportingMissingFeaturesEnabled callback controls whether the server will report attempts to check out features that are unavailable.
For example:
int IsReportingMissingFeaturesEnabled(void);
Return value
Returns 1 to enable missing-feature reporting or 0 to disable it. The supplied configuration returns 0.
GetClientTimeout
The GetClientTimeout callback sets the heartbeat timeout for connected clients. If the server receives no heartbeat within this period, it disconnects the client and returns its licenses to the free pool.
For example:
int GetClientTimeout(void);
Return value
Returns the timeout in seconds. The default is 5 minutes; the supplied configuration returns 5 * 60.
IsLockFileEnabled
The IsLockFileEnabled callback controls use of the license-server lock file, which prevents multiple server instances from running on one machine.
For example:
int IsLockFileEnabled(void);
Return value
Returns 1 to enable the lock file or 0 to disable it. The supplied configuration returns 0; however, production vendor libraries normally enable this setting.
GetMinimumRemoveTime
The GetMinimumRemoveTime callback sets the minimum duration a client must remain connected before lmxendutil -removeuser can remove it.
For example:
int GetMinimumRemoveTime(void);
Return value
Returns the minimum time in seconds. The end user may override this in lmx-serv.cfg, but cannot choose a lower value. The default is two minutes. The supplied configuration returns 0.
GetMaximumServerVersion
The GetMaximumServerVersion callback limits the highest LM-X License Server version with which this vendor library may run. Use this to require a server version that has been tested and is supported by the vendor.
For example:
int GetMaximumServerVersion(void);
Return value
Returns the version as (major)(minor)(patch), with each minor component represented by one digit. For example, 441 permits server versions through 4.4.1, and 1021 represents 10.2.1. Return LMX_NO_VERSION_RESTRICTION to allow all server versions. The supplied configuration has no version restriction.
Logging and lifecycle
Logging and lifecycle callbacks are described below.
SetLmxLogprintf
The SetLmxLogprintf callback is an internal initialization hook that receives the server logging function. It assigns the function pointer used by vendor callbacks to write messages to the server console and/or log file.
For example:
void SetLmxLogprintf(void (*pLmxLogprintf)(const char *szFormat, ...));
Parameters
pLmxLogprintf[in] printf-compatible server logging function.
Return value
This function does not return a value.
After initialization, callbacks can call LmxLogprintf("message: %s", value). Do not call LmxLogprintf before this hook has supplied a non-NULL function pointer.
LmxServerStartup
The LmxServerStartup callback runs when the license server starts. Use it to initialize vendor resources, validate the license information presented by the server, or start vendor-owned background work.
For example:
LMX_STATUS LmxServerStartup(const LMX_LICENSE_INFO *pLI);
Parameters
pLI[in] License information available at startup. The supplied configuration reads the feature and, when present, uses information from this object.
Return values
Returns LMX_SUCCESS when initialization succeeds. Returns LMX_UNKNOWN_ERROR (or another appropriate LM-X status) to make server startup fail.
The supplied configuration also obtains and saves the registered vendor-store callbacks, then performs a save/load round trip solely to exercise the callback bridge in acceptance tests.
LmxServerShutdown
Runs when the license server is stopping or restarting. Use it to release vendor resources and stop work started by LmxServerStartup.
For example:
void LmxServerShutdown(LMX_SHUTDOWN_MODE eMode);
Parameters
eMode[in] Reason for shutdown: SERVER_SHUTDOWN for a normal stop or SERVER_RESTART for a restart.
Return value
This function does not return a value.
The supplied configuration performs a vendor-store save/load round trip for acceptance-test coverage.
Client-to-server vendor functions
LmxServerFunction
The LmxServerFunction function runs when a client calls LMX_ServerFunction(). The input message is provided in szMessage; overwrite the same buffer with the response that should be returned to the client.
For example:
void LmxServerFunction(char *szMessage);
Parameters
szMessage[in,out] Null-terminated request and response buffer. Both the request and response may contain up to LMX_MAX_LONG_STRING_LENGTH bytes. The callback must not write beyond that limit.
Return value
This function does not return a value. Its response is the replacement text in szMessage.
The supplied configuration recognizes the following test commands:
| Command | Description |
|---|---|
| Saves a vendor-store value and returns |
vendor_store_load:<virtual filename> | Returns the stored value or LMX_STATUS=<status> |
vendor_store_clear:<virtual filename> | Removes the stored value and returns LMX_STATUS=<status> |
| Restores or removes registered vendor-store callbacks for bridge testing |
long_response | Returns a response filled with x characters |
| Changes the test result used by CustomHostidCompare |
These messages are acceptance-test protocol, not a recommended production protocol.
LmxOldServerFunction
The LmxOldServerFunction function is the legacy form of the server-function callback. Use LmxServerFunction for new code; retain this callback only when compatibility with older integrations requires it.
For example:
void LmxOldServerFunction(unsigned char *sMessage, int *npLength);
Parameters
sMessage[in,out] Request/response byte buffer.
npLength[in,out] Pointer to the response length. Set *npLength to the number of bytes written to sMessage, or to 0 when no response is returned.
Return value
This function does not return a value.
The supplied configuration copies the current test response into sMessage and sets its length from g_szMessageCallback.
Checkout, checkin, borrow, and reservation hooks
All the checkout, checkin, borrow, and reservation hook callbacks (described below) receive an LMX_SERVERSIDE_REQUEST, which describes checkout, checkin, borrow, borrow-return, reservation, and reservation-return transactions through eEventType.
The request includes:
- Client ID (
nClientUID) - Persistent borrow ID (
nBorrowUID) - Feature name and license version
- Requested/used/available license counts
- Client identity (
szIP,szUsername,szHostname) - Client request string (
szClientReq) - Project (
szProject) - Reservation data (
szReservationToken,tReservationExpireTime)
Only LmxServerSideCheckoutTry and LmxServerSideCheckin may modify a request. In those callbacks, LM-X honors changes only to nReqLicCount and szShareCustom; all other changes are ignored. LmxServerSideCheckout receives a const request and is read-only.
LmxServerSideCheckoutTry
The LmxServerSideCheckoutTry function runs before the server processes a checkout or reservation request. Use it to audit, adjust the requested count/share string, or deny the request before a license is granted.
For example:
LMX_STATUS LmxServerSideCheckoutTry(LMX_SERVERSIDE_REQUEST *pSR);
Parameters
pSR[in,out] Request details. Only nReqLicCount and szShareCustom may be changed.
Return values
Returns LMX_SUCCESS to allow the request. Returns LMX_VENDOR_DENY to deny the request. Returns another LM-X error status if the callback cannot process the request.
The supplied configuration verifies selected request values for acceptance tests and returns LMX_VENDOR_DENY for feature vendor_deny when the client request string differs from the feature comment.
LmxServerSideCheckout
The LmxServerSideCheckout function runs after a checkout or reservation request has been processed. Use it for read-only auditing or follow-up work after a successful request.
For example:
void LmxServerSideCheckout(const LMX_SERVERSIDE_REQUEST *pSR, LMX_STATUS LmxStat);
Parameters
pSR[in] Read-only request details. For this callback, the version fields are the version in the license.
LmxStat[in] Result of the request. LMX_SUCCESS indicates that the checkout or reservation succeeded.
Return value
This function does not return a value.
The supplied configuration logs successful requests, logs reservation information, and records borrow data needed by its acceptance tests.
LmxServerSideCheckin
The LmxServerSideCheckin function runs when a checkin, borrow return, or reservation-return request takes place. Use it to audit the event or modify the outgoing nReqLicCount or szShareCustom value when needed.
For example:
void LmxServerSideCheckin(LMX_SERVERSIDE_REQUEST *pSR);
Parameters
pSR[in,out] Request details. Only nReqLicCount and szShareCustom may be changed.
Return value
This function does not return a value.
The supplied configuration logs requests and reservation details, verifies test-only client request values, and returns borrow-related values through its server-function callback.
LmxGetLockFile
The LmxGetLockFile function supplies the path to the lock file used when lock-file support is enabled.
For example:
void LmxGetLockFile(char *szLockFile);
Parameters
szLockFile[out] Buffer to receive the null-terminated path. Its maximum length is LMX_MAX_LONG_STRING_LENGTH.
Return value
This function does not return a value.
The supplied configuration returns C:\\temp\\ss.lock on Windows and /var/tmp/ss.lock on other platforms. Ensure the chosen directory exists and the server process can create and remove the file there.
Vendor secure-store functions used by the supplied configuration
VendorStoreSave
The VendorStoreSave function saves vendor-specific text data in the server secure store. Passing NULL or an empty string as szString removes the stored value.
For example:
LMX_STATUS VendorStoreSave(const char *szVirtualFilename, const char *szString);
Parameters
szVirtualFilename[in] Virtual filename/key under which to store the value. It must not be NULL.
szString[in] Value to store, or NULL/an empty string to remove the existing value.
Return values
Returns LMX_SUCCESS on success; returns LMX_INVALID_PARAMETER when the virtual filename is NULL; returns LMX_NOT_IMPLEMENTED when no save callback is registered; or returns the status returned by the registered implementation.
VendorStoreLoad
The VendorStoreLoad function loads vendor-specific text data from the server secure store.
For example:
LMX_STATUS VendorStoreLoad(const char *szVirtualFilename, char *szString);
Parameters
szVirtualFilename[in] Virtual filename/key to load. It must not be NULL.
szString[out] Buffer that receives the stored value. Pass NULL to check only whether the value can be read; no text is returned in that case.
Return values
Returns LMX_SUCCESS on success; returns LMX_INVALID_PARAMETER when the virtual filename is NULL; returns LMX_NOT_IMPLEMENTED when no load callback is registered; or returns the status returned by the registered implementation.