win_lm_login

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, available from Synergy CodeExchange in the Synergex Resource Center.