≡

LESDK::Logon function

The Logon function attempts to log on a user to the console session of the local computer. You specify the user with a user name and domain and authenticate the user with a plain text password or PIN. If the function succeeds, the system creates a new console session logged on by the specified user. The thread running this function must have administrative privileges. See Remarks for function behavior details.

Syntax

int LESDK::Logon(
  [in]           const wchar_t* username,
  [in]           const wchar_t* password,
  [in, optional] const wchar_t* domain,
  [in]           const unsigned int* license
);

int LESDK::Logon(
  [In]           string username,
  [In]           string password,
  [In, Optional] string domain,
  [In]           uint[] license
);

Parameters

[in] const wchar_t* username [In] string username

A pointer to a null-terminated string that specifies the user name. This is the name of the user account to log on to. The user principal name (UPN) format can be used only with Azure and Microsoft accounts. Cannot be NULL null.

[in] const wchar_t* password [In] string password

A pointer to a null-terminated string that specifies the plaintext password or PIN for the user account specified by username.

[in, optional] const wchar_t* domain [In, Optional] string domain

A pointer to a null-terminated string that specifies the name of the domain or the server, whose account database contains the username account. If this parameter is NULLnull, the user will be logged on to the local computer. For Azure Active Directory accounts, domain must be AzureAD.

[in] const unsigned int* license [In] uint[] license

A pointer to the license key provided after the purchase or the start of the trial.

Return values

If the function succeeds, the return value is zero. If the function fails, it returns one of the following error codes:

Code Description Possible remedy
1 License cannot be validated Check whether the license parameter is correct
2 License trial period has expired You need to use the permanent license received upon purchase
3 This SDK version is not covered by your maintenance plan Roll back to a previous SDK version or acquire a new license
4 Another instance of the LESDK::Logon function is running on another thread Wait for the other function to complete and do not try to log on users in parallel
14 Logon could not be finished in the allotted time (120 seconds). Something is blocking the logon process Check visually the console session during the logon to see what is happening
17 Logon failed because the credentials are not valid Double check the user name, password and domain
18 Logon failed because the user account is disabled Check the user account
19 Logon failed because of problems related to some other user account Make sure you can log on the user manually
2x Cannot read or write to the system registry Make sure the thread has administrative privileges
3x Credentials are not valid Check that the username, domain and password variables are valid and null-terminated
6x Error while working with the existing LogonExpert installation Make sure the running thread has administrative privileges
77 Unlock could not be finished in the time allotted (120 seconds) System may be overloaded. Try adding a delay between operations
81 Processor architecture is not supported LESDK does not support CPU architectures other than x86 and AMD64
82-8 Cannot write system files Make sure the thread has administrative privileges and the file system is accessible

Remarks

The LESDK::Logon function logs on to the console session only. This is a session to which a physical keyboard and display are connected. You cannot create or log on remote sessions with LogonExpert SDK.

If before a function call the user is logged on to the console session and the session is unlocked, the function returns a zero immediately.

If before a function call the user is logged on to the console session but the session is locked, the session will be unlocked.

If before a function call the user is logged on to another (remote or disconnected) session, the other session will be switched to console and unlocked.

If any other user is already logged on to the console session, the session will be disconnected and then logged on by the user from the function parameters.

The function can be called from outside of a user context (for example by a system service), if necessary.

The execution of the function takes significant time and, as the function runs synchronously, the thread does not respond until it finishes. If asynchronous execution is required, consider running the function in a separate thread.