cmc_query_configuration

The cmc_query_configuration function determines configuration information for the installed CMC implementation.

Quick Info

CMC_return_code cmc_query_configuration (

Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If this parameter is set to zero, there is no session and the cmc_query_configuration function returns the default logon information to the buffer indicated by the reference parameter. If the session parameter is set to a nonzero value, cmc_query_configuration returns configuration information as determined by the session. If the value provided for the session parameter is invalid, cmc_query_configuration returns cmc_e_invalid_session_id.

item

[in] Enumerated variable that identifies the configuration information required by the client application. The cmc_query_configuration function will write different values to the buffer or pointer that the reference parameter points to depending on the value of the item parameter. The caller must allocate this buffer or pointer before calling cmc_query_configuration. Possible item values are:

CMC_CONFIG_CHARACTER_SET

The reference parameter should be a pointer to a CMC_object_identifier4YJ__MF structure array. The cmc_query_configuration function writes a pointer to the array of CMC_object_identifier structures that indicate the character sets supported by the current CMC implementation to the location pointed at by the reference parameter. The cmc_query_configuration function ends the array with a null CMC_object_identifier structure.

The first object identifier in the array is the default character set used if the calling client application or service provider does not specify one explicitly. The calling client or provider uses one of these object identifiers at logon to specify that the implementation use a different character set than the default. This array should be freed with cmc_free1RMW6IO.

CMC_CONFIG_DEFAULT_SERVICE

The reference parameter should be a pointer to a CMC_string data type. The cmc_query_configuration function writes a pointer to the default message service name, if available, to the location indicated by the reference parameter. The cmc_query_configuration function writes NULL to this location if no default service name is available.

The calling client or provider can use this string, along with the one returned by CMC_CONFIG_DEFAULT_USER, as defaults when prompting the user for the service name, user name, and password. The string is returned in the CMC implementation s default character set.

CMC_CONFIG_DEFAULT_USER

The reference parameter should be a pointer to a CMC_string data type. The cmc_query_configuration function writes a pointer to the default user name, if available, to the location indicated by the reference parameter. The cmc_query_configuration function writes NULL to this location if no default user name is available.

The calling client or provider can use this string, along with the one returned by CMC_CONFIG_DEFAULT_SERVICE, as defaults when prompting the user for the provider name, user name, and password. The string is returned in the CMC implementation s default character set.

CMC_CONFIG_LINE_TERM

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_LINE_TERM_CRLF if the line delimiter is a carriage return followed by a line feed, CMC_LINE_TERM_LF if the line delimiter is a line feed, or CMC_LINE_TERM_CR if the line delimiter is a carriage return.

CMC_CONFIG_REQ_PASSWORD

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_REQUIRED_NO if the password is not required to log on, CMC_REQUIRED_OPT if the password is optional to log on, or CMC_REQUIRED_YES if the password is required to log on.

CMC_CONFIG_REQ_SERVICE

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_REQUIRED_NO if the service name is not required to log on, CMC_REQUIRED_OPT if the service name is optional to log on, or CMC_REQUIRED_YES if the service name is required to log on.

CMC_CONFIG_REQ_USER

The reference parameter should be a pointer to a CMC_enum variable, which is set to CMC_REQUIRED_NO if the user name is not required to log on, CMC_REQUIRED_OPT if the user name is optional to log on, or CMC_REQUIRED_YES if the user name is required to log on.

CMC_CONFIG_SUP_COUNTED_STR

The reference parameter should be a pointer to a CMC_boolean variable, which is set to TRUE if the CMC_COUNTED_STRING_TYPE flag is supported during logon.

CMC_CONFIG_SUP_NOMKMSGREAD

The reference parameter should be a pointer to a CMC_boolean variable, which will be set to TRUE if the cmc_read1RN7TEN function supports the CMC_DO_NOT_MARK_AS_READ flag.

CMC_CONFIG_UI_AVAIL

The reference parameter should be a pointer to a CMC_boolean variable, which will be set to TRUE if there is a dialog box provided by the CMC implementation.

CMC_CONFIG_VER_IMPLEM

The reference parameter should be a pointer to a CMC_uint16 variable, which is set to the version number for the implementation, multiplied by 100. For example, version 1.01 returns 101.

CMC_CONFIG_VER_SPEC

The reference parameter should be a pointer to a CMC_uint16 variable, which is set to the CMC specification version number for the implementation, multiplied by 100. For example, version 1.00 returns 100.

reference

[out] Pointer to a buffer or pointer to which cmc_query_configuration writes configuration information. The value of reference depends on the value of item, as previously described.

config_extensions

[in, out] Pointer to an array of CMC_extensionWY87UR structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_query_configuration function. A value of NULL for the config_extensions parameter indicates that the client application has no extensions for cmc_query_configuration and is expecting no extensions.

On output, cmc_query_configuration writes to the array new information about the query configuration operation. It writes NULL if it generates no output extensions.

Return Values

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_ENUM

A CMC_enum value was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid. Either the reference parameter did not point to a writeable location, or the config_extensions parameter was badly formed.

CMC_E_NOT_SUPPORTED

The current implementation does not support the operation requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

Remarks

The client application must cast the reference parameter to the CMC_buffer type before calling cmc_query_configuration. The client application must allocate sufficient memory to contain the information passed in the item parameter. When this memory is no longer needed, the client should free this memory with whatever memory management routines it is using, or with a call to the cmc_free function if required by the previous explanation.

See Also