The Common Messaging Calls (CMC) client interface is a set of ten functions that enables you to add simple messaging capabilities to your client applications quickly. For example, your client can send a message with a single CMC function call and receive a message with two CMC function calls.
Because CMC is built on top of the core MAPI subsystem, it shares the advantage of messaging system independence. The CMC API is especially valuable because it is also independent of the operating system and the underlying hardware used by the messaging system, providing a common messaging interface that can be used in virtually any environment. The CMC API is therefore a good choice for a messaging API when your client must run on multiple platforms and provide simple messaging functionality on each of these platforms.
Because CMC isolates clients from the complexities of MAPI, service providers, networking, and any other mechanisms which implement messaging, the remainder of this document will use the term "messaging system" to mean all of those things taken together. As far as a CMC client is concerned, the implementation layer underneath CMC is the messaging system that the client is using.
Although the Microsoft CMC implementation is built on top of a MAPI implementation, it is important to note that other implementations of CMC from other vendors might not be. In this document, "CMC" and "CMC implementation" mean "Microsoft's implementation of the CMC API using the MAPI API."
The CMC API was developed in conjunction with the X.400 API Association (XAPIA) standards organization and a group of e-mail vendors and users. It is supported on Microsoft Windows, MS-DOS, OS/2, Macintosh, and UNIX platforms. Because CMC is supported on several different platforms, a client application written to the CMC standard can be ported to other platforms. In contrast, MAPI is a Windows-only standard.
The CMC API supports three principal tasks: sending messages, retrieving messages, and looking up addressing information.
Note that these tasks do not have to be performed in isolation from each other. You can establish a session once with a call to the cmc_logon function and use the resulting CMC session for the duration of the user's interaction with the application. During that time, you can make many CMC calls to perform messaging tasks such as send messages, receive them, and make address book queries.
The CMC API works as a layer between a messaging-enabled application and the messaging system. The messaging system can support multiple messaging protocols, each using different messaging formats and protocols, for example, X.400, RFC 822, and Simple Mail Transfer Protocol. The design of the CMC interface specifies that its functions be independent of the messaging protocols. However, the API does enable developers to use extensions to invoke protocol-specific functions. For more information, see Using CMC Data Extensions.
An address book, a submission queue, and a receiving Inbox are the three messaging system components in the CMC API model.
Using the address book, the messaging-enabled application can look up information about users of connected messaging systems and can resolve users' names to actual addresses. Some messaging systems can also provide an interface enabling users to create recipient lists for messages or find out details about specific recipients.
The CMC implementation assigns a submission queue for each messaging-enabled application. By doing so, CMC provides each application with synchronous submission of messages to the underlying messaging system; once a call to send a message has returned, the calling application is guaranteed that the submission process has completed (although no guarantee is made about whether the message was successfully delivered). When the call has returned, the CMC implementation has all further responsibility for submitting the message to the underlying messaging system.
On the receiving side, an Inbox receives all messages for a user. The messaging system maintains Inboxes on behalf of messaging users. These Inboxes are accessible to users of messaging-enabled applications who have the proper permissions. With the CMC API, you can retrieve summaries of the contents of an Inbox, along with identifiers for the particular messages summarized. You can use these identifiers to select and retrieve individual messages.
The CMC API uses a fixed set of API functions, data structures, and data types. The API functions are the functions that your client calls to carry out messaging tasks. The data structures are the groupings of information that your client must provide to the CMC APIs, and are sometimes returned by the CMC APIs. The data types are basic elements that comprise the data structures. They each have a specific range of values and specific memory storage characteristics (for example, Boolean and floating point) and can have specific operations performed on them. For reference information, see Functions, Structures and Data Types, and Data Extensions.