cmc_list

The cmc_list function lists summary information for messages that meet client application-specified criteria.

Quick Info

CMC_return_code cmc_list (
  CMC_session_id session,                   
  CMC_string message_type,                  
  CMC_flags list_flags,                     
  CMC_message_reference * seed,             
  CMC_uint32 FAR * count,                   
  CMC_ui_id ui_id,                          
  CMC_message_summary FAR * FAR * result,   
  CMC_extension FAR * list_extensions       
)
 

Parameters

session

[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the session handle is invalid, this function returns cmc_e_invalid_session_id.

message_type

[in] Pointer to the ASCII name of the type of message for which this function lists information. If the cmc_list function does not recognize the specified message type, it returns cmc_e_unrecognized_message_type. If the function receives a value of NULL for the message type, it lists information for all available message types.

list_flags

[in] Bitmask of flags. The following flags can be set:

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_list does not display a dialog box and returns an error value instead.

CMC_LIST_COUNT_ONLY

Lists only a count of messages meeting the specified criteria, not any actual summary information. If this flag is not set, the function lists summary information in the array.

CMC_LIST_MSG_REFS_ONLY

Writes only message reference information to the array pointed to by the result parameter. If this flag is not set, cmc_list writes information to all members of the structures in the array.

CMC_LIST_UNREAD_ONLY

Lists unread messages only. If this flag is not set, cmc_list can list both read and unread messages.

seed

[in] Pointer to a message reference that identifies the message after which cmc_list should begin to search. A value of NULL for this parameter indicates that the function should start the search with the first message in the mailbox. A pointer to a message reference of length zero is invalid and causes cmc_list to return cmc_e_invalid_message_reference. If the seed parameter is part of a structure that is returned by an earlier CMC call, the structure that was allocated by CMC should be freed before the current session exits.

count

[in, out] A message count. On input, this parameter specifies a pointer to the maximum number of messages for which cmc_list should provide summary information. A value of zero indicates no maximum.

On output, the count parameter specifies the location to which cmc_list writes the number of messages for which it provides summary information. If no messages match the search criteria, or if the mailbox is empty, cmc_list writes zero.

ui_id

[in] Handle of a dialog box for cmc_list to present to help resolve processing questions.

result

[out] Pointer to the location to which cmc_list writes the address of the array of CMC_message_summary structures that it has written.

list_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_list function. A value of NULL for the list_extensions parameter indicates that the client application has no extensions for cmc_list and is expecting no extensions.

On output, cmc_list writes to the array new information about its processing of the message summaries. 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_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_MESSAGE_REFERENCE

The specified message reference is invalid or no longer valid — for example, it has been deleted.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid — for example, after logging off.

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_UNRECOGNIZED_MESSAGE_TYPE

The specified message type is not supported by the current implementation.

CMC_E_UNSUPPORTED_FLAG

The flag requested is not supported.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The function extension requested is not supported.

Remarks

The client application can specify a cmc_list search to start with a certain message or to start at the first message in the mailbox. It can also specify the maximum number of messages to list. The cmc_list function writes the summary information for the specified messages in an array of CMC_message_summary structures. Using the message references in these structures, the application can then make calls to the cmc_read and cmc_act_on functions for additional processing.

Before cmc_list writes message summary information, it must allocate memory for the structure array to contain the information. When this memory is no longer needed, the client application should free the entire array with a call to the cmc_free function.

See Also

cmc_act_on, CMC_extension, cmc_free, CMC_message_summary, cmc_read