cmc_send

The cmc_send function sends a message.

Quick Info

Header file:

XCMC.H

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.

cmc_send

Quick Info

Parameters

Return Values

Remarks

See Also