cmc_query_configuration

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

Quick Info

Header file:

XCMC.H

CMC_return_code cmc_query_configuration (
  CMC_session_id session,                
  CMC_enum item,                         
  CMC_buffer reference,                  
  CMC_extension FAR * config_extensions  
)

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_identifier 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_free.
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 current implementation does not set default message service names, so NULL is always written in response to CMC_CONFIG_DEFAULT_SERVICE.
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 current implementation does not set default user names, so NULL is always written in response to CMC_CONFIG_DEFAULT_USER.
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_read 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_extension 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.