cmc_send_documents

The cmc_send_documents function sends a document.

Quick Info

Header file:

XCMC.H

CMC_return_code cmc_send_documents (
  CMC_string recipient_addresses,   
  CMC_string subject,               
  CMC_string text_note,             
  CMC_flags send_doc_flags,         
  CMC_string file_paths,            
  CMC_string file_names,            
  CMC_string delimiter,             
  CMC_ui_id ui_id                   
)

Parameters

recipient_addresses

[in] Pointer to the address of the document recipient. When the client application specifies multiple recipients, it should separate the strings using the character specified by the delimiter parameter. The cmc_send_documents function assumes a recipient to be a primary recipient unless the address is prefixed by CC: (carbon copy) or BCC: (blind carbon copy). The TO: prefix can optionally be used with the primary recipient for consistency with the other recipient types. Passing NULL in the recipient_addresses parameter indicates that cmc_send_documents should present a dialog box to prompt for recipients.

subject

[in] Pointer to the subject of the document. Passing NULL in the subject parameter indicates no subject text.

text_note

[in] Pointer to the text note carried with the document. Passing NULL in the text_note parameter indicates no text note.

send_doc_flags

[in] Bitmask of flags used to control how documents are sent. 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_documents does not display a dialog box and returns an error value instead.
CMC_FIRST_ATTACH_AS_TEXT_NOTE: Sends the first attachment as the message text. If this flag is not set, the text_note field contains the text note.
CMC_LOGON_UI_ALLOWED: Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_send_documents does not display a dialog box and returns an error if the user 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_documents does not display a dialog box but must specify at least one recipient.

file_paths

[in] Pointer to the actual path for the attachment file. When the client application specifies multiple paths, it should separate the names using the character indicated by the delimiter parameter.

attach_titles

[in] Pointer to the title of the attachment displayed for the recipient. When the client application specifies multiple titles, it should separate the titles using the character indicated by the delimiter parameter.

delimiter

[in] Pointer to a character used to delimit the names in the file_paths, attach_titles, and recipient_addresses strings. The client application should choose a character that is not used in operating system filenames or recipient names. This parameter cannot be NULL.

ui_id

[in] Handle of a dialog box for cmc_send_documents to present to help resolve processing questions or prompt the user for additional information as required.

Return Values

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_NOT_SUPPORTED: The current implementation does not support counted strings.
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_PARAMETER: A function parameter was invalid.
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 was 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_FLAG: The current implementation does not support the flag 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_documents function is primarily useful for calls from a scripting language application, such as a spreadsheet application using macros, that cannot handle data structures. The cmc_send_documents function tries to establish a session without a logon dialog box. If this is not possible, it prompts the user for logon information to establish a session. Before the function returns, it closes the session.