Messaging Service Access Modules

By Monica Pal, Apple Computer, Inc.

Introduction

Apple’s new System 7 Pro adds AppleScript™, QuickTime™ and PowerTalk™ to the System 7 Macintosh Operating System.

PowerTalk system software and PowerShare™ servers contain several new technologies that enable developers to create a new and exciting generation of collaborative applications. PowerTalk, PowerTalk-savvy and collaborative applications enable PowerTalk users to communicate and exchange information in a simple, consistent manner.

PowerTalk system software and PowerShare servers implement the Apple Open Collaboration Environment (AOCE™), an architecture for collaboration. AOCE defines mail and messaging, catalog, authentication and digital signature services. AOCE also defines Messaging Service Access Modules (MSAMs), applications that enable PowerTalk users to communicate with external or non-AOCE system users. This article describes AOCE messaging service access modules.

AOCE

AOCE store and forward messaging services enable PowerTalk users to exchange information over phone lines and the AppleTalk network. PowerTalk users can also exchange information over other media and with users on external or non-AOCE messaging systems via AOCE messaging service access modules.

Before sending messages, users must be able to address the messages. AOCE catalog services enable users to store address information and any other data that may be required for collaboration. Users may store information in personal catalogs on their PowerTalk machine or on PowerShare catalog servers. Users may also store and access information on external or non-AOCE catalog or directory servers from their PowerTalk machine via catalog service access modules.

With the advent of the data-highway and with more and more people collaborating electronically, there is a need for electronic communication to be authenticated - a need for the collaborating parties to be assured of the identity of the people that they are exchanging information with. There is also a need for the communication to be private, so that no one else can eavesdrop or wire-tap on the conversation or tamper with the data that is being exchanged. AOCE mutual authentication services and the Apple Secure Data Stream Protocol (ASDSP) enable people and processes to verify the identity of the person on the other side of the communications session and to encrypt the data that is exchanged.

AOCE digital signatures technology enables users to sign documents electronically such that recipients can verify the name of the signer and verify that the document has not been altered since it was signed.

AOCE services are provided by the Inter-Program Messaging Manager, Catalog Manager, Authentication Manager and Digital Signatures Manager.

PowerTalk

PowerTalk extends the user’s reach by enabling users to access external or non-AOCE messaging and catalog services by dragging and dropping messaging service access modules and catalog services access modules into their system folder. Once external services have been installed and configured, users can access them without launching separate applications and logging-in to each external system.

PowerTalk enables users to access AOCE and external collaboration services in a simple, standard manner in the Finder by installing three new icons on the desktop - the Universal Mailbox, Catalog Browser and Keychain.

PowerTalk also enables users to access AOCE and external collaboration services in a consistent manner from within any PowerTalk-savvy application by providing two standard dialogs implemented by the Standard Catalog Package and the Standard Mail Package.

Before PowerTalk, my work day would begin by picking up letters delivered by the U.S. Postal service, company mail service, and faxes from my mailbox in the mailroom. Then I would get to my desk and check my voice mail, followed by AppleLinks, Internet mail and QuickMail. If I wanted to send a letter, I printed copies to send via the U.S. Postal service or fax or I logged-in to different electronic mail systems to send my letter.

With PowerTalk, I can browse for and find addresses of AOCE and external mail system recipients using the Catalog Browser in the Finder or Standard Catalog from within an application. I can then drag my letter to the address icon or use the Standard Mail dialog (also called the Mailer) to address the letter, indicate the subject of the letter, add enclosures, sign and send the letter.

I can view - enumerate and read - faxes, voicemail, PowerTalk letters, letters in my accounts on external mail systems etc., from within my Universal Mailbox on the desktop.

In the next section, we examine MSAMs, the AOCE components that enable PowerTalk users to read all their mail in one place and send mail to users on all types of mail systems in one way.

Messaging Service Access Modules

MSAMs allow PowerTalk users to exchange mail and messages with users of non-PowerTalk or external mail and messaging systems.

MSAMs transport messages between an AOCE system and an external mail system and translate messages between the AOCE message format and the external mail system’s message format.

Translating a message includes translating the contents of the message and translating addresses in the message. Sometimes, parts of a message cannot be translated. For example, some external systems only understand plain text. In this case, MSAMs will indicate that data was lost in the translation. For example, if the message contained a picture, the MSAM will indicate that the original message contained a picture that could not be translated.

In addition to transporting and translating messages, MSAMs also generate reports on messages. A report is sent to the sender of a message to inform the sender that a message was successfully delivered or that a message was not delivered to one or more recipients.

There are two types of Messaging Service Access Modules - Personal Messaging Service Access Modules (PMSAMs) and Server-based Messaging Service Access Modules (SMSAMs).

A PMSAM is an application that runs on the user’s PowerTalk machine. A PMSAM allows a PowerTalk user to read mail that has arrived in his/her account or mailbox on a different mail system and to send mail to people that have accounts on that external mail system. A PMSAM logs into the external mail account using the user’s account name and password in order to read and send mail.

An SMSAM is an application that runs on a PowerShare mail server. An SMSAM allows PowerShare users to exchange mail with users that have accounts on external mail systems. A SMSAM is similar to a traditional mail gateway in that it forwards mail from one mail system to another and operates on behalf of users of either mail system. It does not need to know about individual users and does not log into individual user accounts.

Both PMSAMs and SMSAMs communicate with the Messaging Manager using the Messaging Manager’s back-end MSAM API. The MSAM API includes calls that enable AOCE messages to be created and submitted to the Messaging Manager for delivery. Messages waiting to be forwarded to the external system are stored in containers called message queues. The MSAM API includes calls that enable MSAMs to enumerate, read and delete messages in a message queue.

The Messaging Manager communicates with the MSAM using High-Level Events. For example, High-Level Events are used to notify the MSAM about new messages waiting in the out-going message queue.

Messages, Letters and Reports

An AOCE message consists of a message header and zero or more message blocks. The message header contains information about the message - for example, the sender of the message, when the message was sent, the priority it was sent at, the recipients of the message. The header also contains a message identifier (a number that uniquely identifies the message), the size of the message, the number of blocks in the message, and the creator and type of the message. The creator and type of a message is similar to a Macintosh file creator and type. The creator indicates which application created the message and the type indicates the set of message blocks that may be contained in the message. For example, a letter is a message of type ‘lttr’ and letters always contain a letter header in a message block of type ‘lthd’.

Message blocks contain the information that is being exchanged, for example, the text of a letter. Data in a message block can be of any type and any size.

Each message block has a creator and type. The creator indicates which application created the message block and the type gives some indication of the format of data in the message block. For example, message blocks of type ‘PICT’ contain pictures.

An AOCE letter contains a message block called the letter header. The letter header contains information that people need about the letter. This information is in addition to the information in the message header. For example, the letter header contains the subject of the letter. The message header contains a list of recipients of the message and the letter header identifies the recipients as the primary or “to” recipients, secondary or “cc” recipients and blind carbon-copy or “bcc” recipients. A letter may contain additional message blocks containing styled text, pictures, sounds and movies. A letter may also have message blocks containing files and folders as attachments.

A report is a message of type ‘rptn’. The sender of a message may request a report be generated when delivery is successful and/or unsuccessful. The sender may request that the original message be included in the report and that either one report be generated when the result for all recipients is known or that reports be generated as soon as the fate of any recipient is known. A report contains one message block with the report information and may contain another message block with the original message. Report information includes the message identifier of the original message, the time the report was generated and, for each recipient, the result of attempting to deliver to that recipient.

Addresses

AOCE users can address messages to recipients on external messaging systems either by using PowerTalk Address Templates to create addresses or by using the type-in address feature provided by the Standard Catalog package. (A PowerTalk Template is a set of resources used by the Catalog Browser in order to view and edit records in a catalog.)

A recipient in the external system is addressed by specifying the external system and the address of the recipient within the external system. The external system is represented in the AOCE system either by an external catalog or by a special catalog folder called a “foreign DNode” in the AOCE catalog. The address of the recipient in the external system is specified in the extension field of an AOCE address. The format of information in this field is defined by the MSAM developer.

For example, my address on the internet would specify the external system using the external catalog name “Internet” and specify my account on the internet using the string “pal@apple.com” in the extension field. Another example would specify my fax address using the external catalog name “Fax Network” and my fax number “408-555-1234” in the extension field.

Server-based MSAMs

SMSAMs are standard Macintosh applications that run on the same machine as a PowerShare Mail Server. The SMSAM may be launched by an administrator by double-clicking the application icon or by it may be launched automatically by the System at startup.

SMSAM Setup

Before an SMSAM can begin transferring messages between mail systems, it configures itself in each system such that both systems know about the SMSAM and the services it offers. How an SMSAM sets itself up in an external system depends on the external system. In the AOCE system, an SMSAM makes a call to the Messaging Manager to create a record of type “Forwarder” in the catalog. The record contains information about the SMSAM, including it’s name and password.

The administrator then uses the Admin Utility to add an attribute with the name of the co-resident PowerShare Mail Server to the SMSAM record. Next, the administrator uses the Admin Utility to tell the co-resident PowerShare Mail Server to create an out-going message queue for the SMSAM. Messages addressed to recipients on external systems are routed to this server-based message queue by AOCE PowerShare servers. Messages are stored in the outgoing queue until deleted by the SMSAM.

A single SMSAM may forward messages between an AOCE system and several other external messaging systems. The SMSAM record contains a list of the external systems that the SMSAM is connected to. The SMSAM advertises it’s connection to external systems via this list and PowerShare servers learn about which external messaging services are accessible and where to route messages by looking at this list.

Note that AOCE users need not have accounts in the external system in order to exchange messages with external users. The SMSAM may be implemented such that it logs into individual user’s accounts to send and receive messages, but that is generally not the case.

SMSAM Operation

Once the SMSAM has been launched, it uses the MSAM API to notify the PowerShare Mail Server that it has started up. The SMSAM then enumerates messages in the outgoing queue.

For each message that is waiting to be forwarded to the external system, the SMSAM reads the message header and blocks and translates the AOCE message to a message in the external system’s format. The SMSAM then routes the message to external recipients.

The SMSAM generates a report to the sender of the message, indicating whether delivery of the message was successful. Finally, the SMSAM deletes the message from the outgoing queue.

The SMSAM also translates and transfers messages from the external system to the AOCE system. The AOCE system routes and delivers messages and generates reports on them. These reports are routed to the SMSAM’s outgoing queue.

Personal MSAMs

PMSAMs are background applications that run on the user’s PowerTalk machine. They are installed by dropping the MSAM file into the extensions folder.

PMSAMs are launched by the Messaging Manager and may stop executing when they have no work to do. PMSAMs are launched at several different times including at startup, at user-specified scheduled times, when a client makes a call to the Messaging Manager requesting that they be launched, and when a message is waiting to be sent out to the external system.

PMSAM Setup

The PMSAM file contains application code, a PowerTalk Setup Template used to configure the MSAM and an Address Template used to create addresses of recipients on the external system. These are AOCE addresses that encapsulate the recipient’s address in the external system in the extension field.

At startup, the KeyChain looks for access modules in the extensions folder. The Keychain lists the services provided by any access modules it finds and enables users to set these services up. When a user selects a service, the Keychain uses the Setup Template from the PMSAM file to prompt the user for setup information.

Setup information may include the external account name, password, connection information such as modem type, when to connect or how frequently, and any other information that may be required by the MSAM to connect to the external system and log into the user’s account.

Setup information is stored in a personal catalog called the Setup Catalog on the user’s machine. A record is created for each PMSAM and information on the access module is stored as attributes within the record.

PMSAM slots

A user may have several accounts on a particular external mail system. For example, I may have the AppleLink account name MONICA.PAL and the account name AOCE.DEVU. I use the account name MONICA.PAL for all my personal mail and AOCE.DEVU for exchanging information on AOCE related courses. A single PMSAM can be configured to log into and read mail from both these accounts.

In addition, a user may have several accounts on different mail systems of the same type, for example I may have an SMTP account on the Internet and another SMTP account on a separate, private company network. A single PMSAM can be configured to log into and read mail from both these accounts.

The term slot is used to represent an account on an external system. A single PMSAM can be configured to log into and transfer mail from several slots. The PMSAM record in the Setup Catalog has a reference to a slot record for each slot it manages.

The Messaging Manager creates an out-going message queue on the user’s machine for each slot. Messages addressed to recipients on the external system connected via the slot will be routed to this message queue by the Messaging Manager. Messages are stored in the outgoing queue until deleted by the PMSAM.

PMSAM Operation

Once the PMSAM is launched, it uses the MSAM API to get a reference to it’s record in the Setup Catalog. Next, the PMSAM uses the Catalog Manager API to read account and connection information on each slot that has been configured.

For each slot, it then goes through the following steps: the PMSAM logs into the user’s external account. Next, the PMSAM enumerates messages in the outgoing queue. For each message in the queue, it opens and reads the message, translates the message into the external system’s message format and then transfers the message to the external system. The external system is then responsible for routing and delivering the message to external recipients.

The PMSAM generates a report to the PowerTalk user, indicating whether delivery of the message was successful. Finally, the PMSAM deletes the message from the outgoing queue.

If the PMSAM encounters any operational errors, for example if it cannot connect to the external system or if the password is not valid etc., it suspends operations and notifies the Messaging Manager. The Messaging Manager in turn notifies the user via an alert icon in the Universal Mailbox. Once the user fixes the problem and hits the “Resolve” button, the Messaging Manager notifies the PMSAM which in turn resumes operations.

In addition to transferring messages from the out-going queue to recipients on the external system, the PMSAM also reads new messages that have arrived in the PowerTalk user’s account on the external system. A PMSAM may read messages using one of three different operational modes - standard, on-line and quasi-batch.

Standard Mode

A PMSAM may translate and transfer messages to the user’s PowerTalk machine and then delete the messages from the external account. This mode of operation is called standard-mode and is analogous to the way SMSAMs operate. PMSAMs always use this mode when transferring non-letter messages.

Some users, however, may not want to have all their letters transferred from the external system to their PowerTalk machine. They may not have enough disk space on their PowerTalk machine or they may prefer to use the disk space on the external system. In addition, some users may want access to their letters from within the external system, for example, by using a different application.

On-line Mode

In these situations, the PMSAM may operate in on-line mode. In this mode, for each message in the external account, the PMSAM creates a reference to the message on the PowerTalk machine. The reference is called a message summary and contains information on the message, such as the name of sender, the subject, priority and time the message was sent. The PMSAM may also save any information it needs in the message summary, such as the message’s identifier on the external system.

Just like each slot managed by the PMSAM has an out-going message queue, each slot also has an incoming message queue. Message summaries corresponding to messages in an external account are stored in that slot’s incoming message queue.

When a user opens his/her Universal Mailbox, the Messaging Manager looks into all the incoming message queues and returns information stored in message summaries. Thus, opening the Universal Mailbox and enumerating letters that have arrived is a fast operation that does not require PMSAMs to connect to external systems.

If the user now chooses to open and read a message, the Messaging Manager sends a High-Level Event to the PMSAM telling it to translate and transfer the particular message. After the PMSAM transfers the message to the incoming queue, the Messaging Manager opens the message for the user. Thus the PMSAM can transfer a message on demand, as needed by the user, and delete the cached copy of the message after the user has finished reading it. PMSAMs that access the external account over a local area network may use this mode of operation.

Quasi-batch Mode

Depending on the external system and the overhead required to transfer a message on demand, the PMSAM may operate in an intermediate mode called quasi-batch. In this mode, the PMSAM may cache messages on demand and leave some messages cached rather than deleting them after the user has finished reading. The number of messages cached may simply be all messages, a specific number of messages, or a number computed depending on the size of messages cached. Instead of caching messages on demand, the PMSAM may also “pre-fetch” messages, for example it may log into the user’s account at night and cache either all the new messages or some number of the newest messages. This is particularly useful if the PMSAM accesses the external account over a slow connection.

Synchronizing messages

When the user deletes an incoming message in the Universal Mailbox, the Messaging Manager identifies the corresponding message summary and marks that message as having been deleted. The Messaging Manager also notifies the PMSAM by sending it a High-Level Event. The PMSAM deletes the message from the external account and deletes the message summary from the incoming message queue. Similarly when a message is deleted in the external account, the PMSAM reflects this in the Universal Mailbox by making a Messaging Manager call to delete the corresponding message summary and the cached copy of the message.

In addition to synchronizing message deletion in the external account and Universal Mailbox, the Messaging Manager and PMSAM also synchronize state changes. For example, when a letter is read from within the Universal Mailbox, the PMSAM updates the status of the letter on the external system. Similarly, if the user reads the letter from within the external system, the PMSAM updates the information in the message summary and the Universal Mailbox shows the letter as having been read.

Developing an MSAM

SMSAMs and PMSAMs do the same job - they translate and transfer messages between AOCE and other mail systems. There are a lot of similarities and a few differences in their operation.

The mechanics of translating a message is very similar for SMSAMs and PMSAMs. There are minor variations, but for the most part you may use the same routines in the MSAM API to read and write AOCE messages and the same algorithm to translate between message formats.

Configuring MSAMs, setting up connections to the external system and transporting messages will probably be different for SMSAMs and PMSAMs. This is because SMSAMs run on PowerShare Mail Servers and communicate with external mail servers on behalf of all users while PMSAMs run on the user’s PowerTalk machine and use different protocols to connect and log-in to the external system on behalf of one user. In order to configure a PMSAM, you must write a Setup Template. On the other hand, in order to configure an SMSAM, you must use SMSAM specific calls in the MSAM API and use the SMSAM’s user interface to prompt the administrator for setup information.

Both MSAMs need to use the authentication manager and catalog manager in order to access configuration information. PMSAMs read records in the Setup Catalog and SMSAMs read records in the PowerShare Catalog.

MSAM developers must also provide Address Templates so that users can view and edit external mail addresses. Finally, MSAM developers may enable users to browse for addresses in external mail directories or catalogs by providing Catalog Service Access Modules.

Conclusion

For those of you who have lasted this far, developing an MSAM may feel like a major undertaking. The extensive API and lots of jargon can be intimidating, but don’t let that deter you.

The API is as large as it is because AOCE provides a number of different services. In addition, the API can be viewed as having low level calls and high level calls just like the File Manager and the API is tailored for each development task. For example, the Digital Signatures API enables you to sign and verify any data, but also has calls to sign and verify entire files. In addition, there are calls in the Inter-Program Messaging Manager and Standard Mail APIs that may be used to sign and verify messages.

As for the jargon, if you are familiar with other messaging systems, once you have mapped the concepts, for example catalogs to directories (similar concepts but not the same), understanding the documentation will be that much easier. Talking about documentation, the AOCE APIs are documented in Inside Macintosh:AOCE Application Interfaces and Inside Macintosh:Access Modules. The PowerTalk Software Development Kit (APDA Part Number R0525LL/A) includes user and developer documentation, APIs, sample code, development tools, System 7 Pro (without encryption) and updates to PowerTalk software. There is also a self-paced course from Apple Developer University on developing PowerTalk templates (APDA Part Number R0530LL/A), that includes a PowerTalk template creation tool.

And now, here’s my sales pitch.

Before you dig in, get oriented by attending Apple Developer University’s “Introduction to PowerTalk” course (Call (408)974-4897 to register or link DEVUNIV). This one day class walks you through the AOCE Architecture, the main concepts and services provided by each component of AOCE, and how the various components relate to each other. The class gives you an idea of how PowerTalk and PowerShare implement the AOCE Architecture. Hands-on labs help you understand what goes on behind the scenes when you use PowerTalk software and you can also take a look at PowerShare software - Catalog and Mail Servers and the Admin Utility. Hope to see you there!