cmc_logon

The cmc_logon function logs a client application on to a service provider.

Quick Info

CMC_return_code cmc_logon (
  CMC_string service,                   
  CMC_string user,                      
  CMC_string password,                  
  CMC_object_identifier character_set,   
  CMC_ui_id ui_id,                      
  CMC_uint16 caller_CMC_version,        
  CMC_flags logon_flags,                
  CMC_session_id FAR * session,         
  CMC_extension FAR * logon_extensions  
)
 

Parameters

service

[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.

See Also

CMC_extension, cmc_query_configuration