CMC_return_code cmc_send (
CMC_session_id session, CMC_message FAR * message, CMC_flags send_flags, CMC_ui_id ui_id, CMC_extension FAR s* send_extensions )
Parameters
session
[in] Opaque session handle that represents a MAPI session object indicating a session with a message service. If the value provided for the session parameter is invalid, the cmc_send function returns CMC_E_INVALID_SESSION_ID.
message
[in] Pointer to a CMC_message structure identifying the message to be sent. If the client application has not set the flag CMC_SEND_UI_REQUESTED in the send_flags parameter, the message structure must specify at least one primary (TO), carbon-copy (CC), or blind carbon-copy (BCC) recipient. All other structure members are optional. The cmc_send function ignores the time_sent and message_reference members.
send_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 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_send 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_send does not display a dialog box and returns an error value if the caller does not supply enough information.
CMC_SEND_UI_REQUESTED
Displays a dialog box to prompt for recipients, message field information, and other sending options. If this flag is not set, cmc_send does not display a dialog box and the caller must specify at least one recipient.
ui_id
[in] Handle of a dialog box for cmc_send to present when resolving processing questions, prompting the user for additional information, or verifying provided information.
send_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_send function. A value of NULL for the send_extensions parameter indicates that the client application has no extensions for cmc_send and is expecting no extensions.
On output, cmc_send returns to the array new information about the send operation. It returns NULL if it generates no output extensions.
Return Values
CMC_E_AMBIGUOUS_RECIPIENT
The recipient name was ambiguous. Multiple matches were found.
CMC_E_ATTACHMENT_NOT_FOUND
The specified attachment was not found as specified.
CMC_E_ATTACHMENT_OPEN_FAILURE
The specified attachment was found but could not be opened, or the attachment file could not be created.
CMC_E_ATTACHMENT_READ_FAILURE
The specified attachment was found and opened, but there was an error reading it.
CMC_E_ATTACHMENT_WRITE_FAILURE
The attachment file was created successfully, but there was an error writing it.
CMC_E_COUNTED_STRING_UNSUPPORTED
The current 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_MESSAGE_PARAMETER
One of the parameters in the message was invalid.
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_LOGON_FAILURE
The service, user name, or password specified were invalid, so logon cannot be completed.
CMC_E_RECIPIENT_NOT_FOUND
One or more of the specified recipients were not found.
CMC_E_TEXT_TOO_LARGE
The size of the text string passed to the current implementation is too large.
CMC_E_TOO_MANY_FILES
The current implementation cannot support the number of files specified.
CMC_E_TOO_MANY_RECIPIENTS
The current implementation cannot support the number of recipients specified.
CMC_E_UNSUPPORTED_DATA_EXT
The current implementation does not support the data extension 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_USER_CANCEL
The operation was canceled by the user.
CMC_E_USER_NOT_LOGGED_ON
The user was not logged on and the CMC_LOGON_UI_ALLOWED flag was not set.
Remarks
The cmc_send function can, at the client application's option, either use an interface, like a dialog box, to prompt the user for message creation or proceed without any user interaction. A successful return from this function does not necessarily imply recipient validation.
The client application can optionally provide recipient list, subject text, attachments, and note text for the message. If the client application does not provide the required message elements, the cmc_send function can prompt the user for them if a dialog box is available. If the client provides one or more recipients, the function can send the message without prompting the user. If the client provides optional parameters and requests a dialog box, the parameters provide the initial values for the dialog box.
The following conditions apply to the CMC_message structure members:
message_type
To specify an interpersonal message, use a pointer to the string "CMC:IPM". If the client application provides a pointer value of NULL or a pointer to an empty string, cmc_send uses the default string CMC:IPM.
subject
A pointer value of NULL indicates no subject text.
text_note
A pointer value of NULL indicates no message text. If the client application does pass a non-null value to indicate the message text that exceeds the limits of the service provider, the provider can demote the text to an attachment. Alternatively, it can cause cmc_send to return CMC_E_TEXT_TOO_LARGE.
recipients
A pointer value of NULL indicates no recipients. If the client application passes a non-null value to indicate recipients in excess of the number of recipients that the service provider allows per message, cmc_send returns CMC_E_TOO_MANY_RECIPIENTS.
Note that the CMC_recipient structure pointed to by recipients can include either the recipient's name, an address, or a name and address pair. If the client application specifies only a name, cmc_send resolves the name to an address using name resolution rules defined by the CMC implementation. If the client specifies only an address, cmc_send uses this address for delivery and for the recipient display name. Finally, if the client specifies a name and address pair, cmc_send does not resolve the name.
The cmc_send function does not require a recipient of type originator to send a message.
attachments
A pointer value of NULL indicates no attachments. If the client application passes a non-null value to indicate attachments in excess of the number of attachments that the service provider allows per message, cmc_send returns CMC_E_TOO_MANY_FILES.
The cmc_send function reads the attachment files before it returns. Thus the caller or user can freely change or delete attachment files after cmc_send returns without affecting the message.
message_flags
Bitmask of message flags. The following flag can be set:
CMC_MSG_TEXT_NOTE_AS_FILE
The text_note member of the message parameter is ignored and the message text is contained in the file referred to by the first attachment. If this flag is set to zero, the message text is contained in the text_note member.