win_lm_login
Log in and return a unique token
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
|
|
int WINAPI win_lm_login(char *producer, char *app_code, int check, int seat, int *token, int *syserr)
Arguments
producer
The producer code for your company. This is a null-terminated 8-bit ANSI string. (This code was assigned to your company by Synergex when you requested the License Key Generator.)
app_code
The code that you created to refer to the application or application component. This is a null-terminated 8-bit ANSI string and can be up to six characters long.
check
An int32 set to one of the following values:
0 = Log in the license if it is available.
1 = Check whether the license is available.
2 = Check whether the license is installed.
3 = Log in the license if it is installed.
Passing anything other than 0, 1, 2, or 3 is the same as passing 1.
An available license indicates either that the license is installed or that the 14-day grace period is in effect. When check is 1 or 2, License Manager only checks on the license; it does not request a license log-in, and so a slot is not taken and the concurrent number of users is not incremented. See the Discussion for details.
seat
An int32 set to 0 (zero) or the value designated to represent the seat.
token
An int32 pointer returned with the log-in token, which is a key that is maintained in License Manager.
syserr
An int32 pointer returned with a system error code when the return status is other than 0.
Discussion
The win_lm_login function requests that License Manager either log in a license “slot” for the specified application code or perform a license “check.”
When check is 0, if the license is installed and a slot is available, win_lm_login returns a token. If the license is not installed, but the 14-day grace period is in effect, win_lm_login returns success (0) and a token of 0. In this case, no license slot is consumed, and so a log-out is not required. If the 14-day grace period has expired (and the license has not been installed), win_lm_login returns failure (1).
When check is 1, if the license is installed or if the 14-day grace period is in effect, win_lm_login returns success (0) and a token of 0. If the 14-day grace period has expired (and the license has not been installed), win_lm_login returns failure (1).
When check is 2, if the license is installed, win_lm_login returns success (0) and a token of 0. Any other condition returns failure (1).
When check is 3, if the license is installed and a slot is available, win_lm_login returns success (0) and a token. If the 14-day grace period is in effect, win_lm_login returns failure (1).
The token returned by win_lm_login should be saved by your application and used in the call to win_lm_logout. License Manager will only recognize log-outs with a matching token. You need to retain the token only while the license is logged in because a token has meaning only for the log-in for which it was obtained.
When using the seat argument, the value you should pass depends on the type of application:
- For a stand-alone application, where the user is running the application interactively from the same workstation that the user is logged in to, pass 0 for seat.
- In a server environment, where there are multiple users (such as an xfNetLink – xfServerPlus application), you will need to decide how a “seat” should be represented within your application. Seat can be any 32-bit integer. The seat should be unique among seats, but the same for each instance of a particular seat. For example, you may want to use the client’s IP address. In a server environment, you must include the seat to log out the correct license.
Do not attempt to call the win_lm_login function from the load event of a DLL because a thread cannot be created within a load event. |
The win_lm_login function returns a status value. The most common values are listed below; see Licensing Toolkit error messages for additional values that can be returned.
0 = Operation was successful.
1 = Product is not licensed.
2 = Concurrent user maximum reached.
7 = Product demo has expired.
These values are for checking success or providing application-related license error messages; they have no effect on your application. You must write code to handle the returned status. For example, if win_lm_login returns 2 (concurrent user maximum reached), you may want to deny the user access to your application and present an error message stating the problem.
Examples
See lmdltest.c in Licensing_TK_Examples.zip, available from Synergy CodeExchange in the Resource Center on the Synergex website.