CMC_message

A CMC_message structure contains information about a CMC message.

Quick Info

typedef struct { 
     CMC_message_reference     *message_reference; 
     CMC_string     message_type; 
     CMC_string subject; 
     CMC_time      time_sent; 
     CMC_string text_note; 
     CMC_recipient *recipients; 
     CMC_attachment     *attachments; 
     CMC_flags message_flags; 
     CMC_extension *message_extensions; 
} CMC_message; 
 

Members

message_reference

Pointer to the message reference, which is a counted string — that is, a CMC_counted_string structure. The message reference is a unique identifier for a message within a mailbox.

message_type

Pointer to a string that identifies the type of the message. Three different string identifiers are available:

• Object identifiers, which are used for message types identified by object identifiers as defined in CCITT Recommendation X.208.
• CMC registered values, which are used for message types defined in the CMC specification.
• Bilaterally defined values, which are used for message types that are unregistered. CMC does not ensure that bilaterally defined values are unique.

For the complete specification of CMC message types, see "Remarks."

subject

Pointer to a string describing the subject of the message.

time_sent

The CMC_time structure containing the date and time when the client application submits the message to the CMC implementation.

text_note

Pointer to the string containing the message text. If the value of this member is NULL, there is no message text. If the CMC_MSG_TEXT_NOTE_AS_FILE flag is set for the message_flags member, the message text is in the first attachment to the message. For information on message text format, see "Remarks."

recipients

Pointer to the first element in an array of CMC_recipient structures defining the message recipients.

attachments

Pointer to the first element in an array of CMC_attachment structures defining the attachments to the message.

message_flags

Bitmask of message flags. The following flags can be set:

CMC_MSG_LAST_ELEMENT

The last element in an array of CMC_message structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

CMC_MSG_READ

The message has been read. If this flag is set to zero, the message has not been read.

CMC_MSG_TEXT_NOTE_AS_FILE

The text_note member 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_MSG_UNSENT

The client application has not sent the message, for example when the message is a draft. The sender can create such a message with the CMC_X_COM_SAVE_MESSAGE data extension. If this flag is set to zero, the client application has sent the message.

message_extensions

Pointer to the first structure in an array of CMC_extension structures representing the message extensions.

Remarks

Message types are used to distinguish between various sorts of messages that might require different processing. For example, the message type might be used by the client application to determine how to display the message or by CMC to determine how to send the message.

CMC message types possible in the message_type member of a CMC_message structure can have the following formats and are case-insensitive.

"OID: " + object_identifier 
"CMC: " + cmc_registered_value 
"BLT: " + string 
 

An object_identifier is a string containing a series of whitespace separated integers. See CMC_object_identifier for details.

The following is a list of message types:

IPM

Interpersonal message. An interpersonal message is a memo-like message containing a recipient list, an optional subject, an optional text note, and zero or more attachments. The CMC_message structure is optimized to accommodate a message with the registered value IPM.

IP RN

Read notification for an interpersonal message. A read notification indicates the recipient has opened a message.

IP NRN

Nonread notification for an interpersonal message. A nonread notification indicates a message has been removed from the recipient's mailbox without being opened. For instance, the service or user has discarded the message or it has been automatically forwarded to another recipient.

DR

Delivery report. A delivery report indicates the service was able to deliver a message to its recipient.

NDR

Nondelivery report. A nondelivery report indicates the message service was not able to deliver a message to its recipient.

Bilaterally defined values are arbitrary strings and are used to identify custom message types used by the client application.

As the syntax preceding indicates, the OID: type identifier indicates a type identified by an object identifier, the CMC: type identifier indicates a type identified by a CMC registered value, and the BLT: type identifier indicates a type identified by a bilaterally defined value. Following are examples of valid type identifiers:

OID: 1 2 840 113556 3 2 850 
CMC: IPM 
BLT: my special message type 
 

You can format type identifiers as you choose; the CMC implementation also defines a canonical type identifier format that allows a client application to easily compare type identifier strings. The CMC implementation always returns type identifiers in this format, which guarantees the following:

• All tokens are separated with a single space.
• The type identifiers OID:, CMC:, and BLT: are returned in uppercase.

The CMC specification does not define what it will do with type identifier strings that are not in this format.

The formats of messages with the preceding registered values within a CMC_message structure depend on the messaging protocols employed by the underlying messaging system. Often, non-IPM messages take the form of a program-generated message, which follows a memo-like format similar to an IPM format but serves instead to convey information about a previously sent message.

Note The cmc_registered_value types correspond to X.400 message types; however, non-X.400 messaging systems can also use them. Thus, these message types are meant to apply generically and not specifically to X.400 services.

Some implementations only support the interpersonal message type (CMC: IPM). Some implementations might treat messages of types other than IPM as IPM messages or might generate an error for such messages.

For the text_note member, the format of the message text is a sequence of paragraphs, whether it is passed in memory or in a file. Each paragraph is terminated with the appropriate line terminator for the platform: CR (carriage return) for Macintosh, LF (linefeed) for UNIX, and CR/LF for MS-DOS and Windows. The CMC implementation can word-wrap long lines (paragraphs). There is no guarantee that paragraph formatting will remain constant when a message is saved and read back. For example, the cmc_read function can return a long paragraph as a series of shorter paragraphs.

See Also

CMC_attachment, CMC_extension, CMC_recipient, cmc_send, CMC_time