IServerClient::OpenSession method

---

Establishes connection and initializes a new session with the IM server. All subsequent calls of other methods (except Initialize method) of the IServerClient interface must be made after successful call of this function.

HRESULT OpenSession(
    BYTE iAuthenticationMode,
    LPSTR lpszAccountName,
    LPSTR lpszPassword,
    LPSTR lpszDomain,
    LPSTR lpszBrandLogoFileName,
    LPSTR lpszBrandLinkUrl,
    LPSTR lpszBrandName,
    LPSTR lpszConfigIniFileName,
    LPDWORD lpdwExtendedCode
);

Parameters

iAuthenticationMode

[in] Specifies the authentication mode used to establish connection with the IM server. This parameter can be one of the following values:

AUTHENTICATION_MODE_SIMPLE

Indicates a Simple authentication mode which only matches Windows user's login with the account name on the IM server. No any other authentication is performed.

AUTHENTICATION_MODE_SSPI

Uses Windows Authentication that is based on built-in functionality in Windows.

AUTHENTICATION_MODE_PASSWORD

Indicates authentication using private login and password.

lpszAccountName

[in] Pointer to a null-terminated text buffer that contains user's account name. Size of the buffer must not exceed 64 symbols of length. This parameter cannot be NULL.

lpszPassword

[in] Pointer to a null-terminated text buffer that contains user's password. Size of the buffer must not exceed 64 symbols of length. This parameter must be used if the iAuthenticationMode variable is set to AUTHENTICATION_MODE_PASSWORD value, can be also used if iAuthenticationMode is set to AUTHENTICATION_MODE_SSPI (see Remarks) and must be NULL in all other cases.

lpszDomain

[in] Pointer to a null-terminated text buffer that contains name of Windows domain. Size of the buffer must not exceed 64 symbols of length. This parameter must be NULL except some cases if the IM client does not use a transparent authorization via Windows Authentication when iAuthenticationMode is set to AUTHENTICATION_MODE_SSPI and lpszPassword is also used (see Remarks).

lpszBrandLogoFileName

[in] Pointer to a text buffer that contains a full path to the logo image file that will be created and filled by the logo uploaded on the IM server. This parameter can be NULL.

lpszBrandLinkUrl

[out] Pointer to a text buffer that receives an URL associated with the logo image file on the IM server. Size of the buffer must be 255 symbols of length. This parameter can be NULL.

lpszBrandName

[out] Pointer to a text buffer that receives a brand name from the IM server. Size of the buffer must be 64 symbols of length. This parameter can be NULL.

lpsConfigIniFileName

[in] Pointer to a text buffer that contains a full path to existing configuration ini file that should be matched and downloaded from IM server if required. This parameter is not used in this version of SDK and must be NULL.

lpdwExtendedCode

[out] Pointer to a DWORD variable that gets an extended code if error result is returned. For available codes see Available Extended Codes topic.

Return Value

S_OK

The function was successful.

E_INVALIDARG

One or more arguments are incorrect.

E_FAIL

Some error occurred in the function. Check lpdwExtendedCode variable to get extended information on the error.

Remarks

The IM client uses transparent authentication via Windows Authentication if iAuthenticationMode variable is set to AUTHENTICATION_MODE_SSPI. This means that both lpszPassword and lpszDomain parameters must be NULL in order to use credentials of current user logged into Windows domain network. But the client can perform Windows Authentication using different credentials, for example if the user wants to authorize with the IM server outside the Windows domain network, from home PC, etc. In those cases both lpszPassword and lpszDomain parameters must be used.