[in] Pointer to the location of the service provider for the CMC implementation. Passing NULL for the service parameter indicates either that the client application is requesting logon to a service provider that does not require a service name, or that the client is requesting the CMC implementation's logon dialog box.
user
[in] Pointer to a MAPI profile name identifying the client application. Passing NULL for the user parameter indicates either that the client is requesting logon to a service provider that does not require a user name, or that the client is requesting the CMC implementation's dialog box to prompt for a name.
password
[in] Pointer to a MAPI profile password required for access to the CMC implementation. Passing NULL for the service parameter indicates either that the client is requesting logon to a service provider that does not require a password, or that the client is requesting the CMC implementation's dialog box to prompt for a password.
character_set
[in] Pointer to an object identifier for the character set used by the client application. The client application can call the cmc_query_configuration function to retrieve the available values. The CMC implementation requires a non-null value for the character_set parameter.
ui_id
[in] Handle of a dialog box for the cmc_logon function to present to help resolve processing questions or prompt for logon.
caller_CMC_ version
[in] The client application's CMC version number, multiplied by 100. For example, version 1 is specified as the integer 100.
logon_flags
[in] Bitmask of flags. The following flags can be set:
CMC_COUNTED_STRING_TYPE
The string type the calling application or provider uses for CMC interactions is a CMC_counted_string. If this flag is not set, the function treats all strings as null-terminated strings.
CMC_ERROR_UI_ALLOWED
Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_logon does not display a dialog box and returns an error value instead.
CMC_LOGON_UI_ALLOWED
Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_logon does not display a dialog box and returns an error value if the user does not supply enough information.
session
[out] Pointer to the location to which cmc_logon writes an opaque session handle. This identifier represents a MAPI session object indicating a session with a message service.
logon_extensions
[in, out] Pointer to an array of CMC_extension structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_logon function. A value of NULL for the logon_extensions parameter indicates that the client application has no extensions for cmc_logon and is expecting no extensions.
On output, cmc_logon writes to the array new information about the logon operation. It writes NULL if it generates no output extensions.
Return Values
CMC_E_COUNTED_STRING_UNSUPPORTED
This implementation does not support the counted-string type.
CMC_E_FAILURE
There was a general failure that does not fit the description of any other return value.
CMC_E_INSUFFICIENT_MEMORY
Insufficient memory was available to complete the requested operation.
CMC_E_INVALID_FLAG
A flag set using a flags parameter was invalid.
CMC_E_INVALID_PARAMETER
A function parameter was invalid.
CMC_E_INVALID_UI_ID
The specified user-interface identifier is invalid or no longer valid.
CMC_E_LOGON_FAILURE
The service, user name, or password specified was invalid, so logon cannot be completed.
CMC_E_PASSWORD_REQUIRED
A password is required on this message service.
CMC_E_SERVICE_UNAVAILABLE
The service requested was unavailable.
CMC_E_UNSUPPORTED_CHARACTER_SET
The current implementation does not support the character set requested.
CMC_E_UNSUPPORTED_FLAG
The current implementation does not support the flag requested.
CMC_E_UNSUPPORTED_FUNCTION_EXT
The current implementation does not support the function extension requested.
CMC_E_UNSUPPORTED_VERSION
The current implementation cannot support the version specified in the call.
Remarks
The cmc_logon function can, at the client application's option, either prompt the user for information through a dialog box or proceed without any user interaction. It writes a session handle that the client application can use in subsequent calls to the CMC implementation.