December 93 - BUILDING POWERTALK-SAVVY APPLICATIONS
BUILDING POWERTALK-SAVVY APPLICATIONS
STEVE FALKENBURG
PowerTalk is a new software product based on the Apple Open Collaboration
Environment (AOCE). By adding support for PowerTalk to your application, you can
begin to take advantage of the wide range of services provided by the emerging world of
collaborative computing. This article touches on two areas of this environment --
electronic mail and digital signatures -- and shows how they can be incorporated into
a typical application program.
AOCE consists of a set of human interface elements and programming interfaces that
make collaboration on an electronic document simpler and more secure; PowerTalk is
its client software component (and PowerShare its server software). Two elements of
PowerTalk are the Standard Mail Package's mailer, which provides application-level
electronic mail support, and the DigiSign digital signature mechanism, which
safeguards documents from electronic tampering. Support for these features of
PowerTalk should not be limited to networking and communications applications. The
real power of PowerTalk lies in its ability to be built into a wide range of productivity
applications, from spreadsheets to presentation packages. Ultimately, the Send and
Sign menu items should be as pervasive as Print is today.
Using a small drawing application called CollaboDraw as our example, we'll go step by
step through the process of adding support for the PowerTalk Standard Mail Package
and Digital Signature Package.
WHAT EVERY APPLICATION SHOULD KNOW ABOUT
POWERTALK
Before walking through the code, we'll give a brief overview of the PowerTalk features
we'll be adding to CollaboDraw. Very basic descriptions of the Standard Mail Package
and Digital Signature Package follow. Additional information on PowerTalk can be found
in the full PowerTalk API documentation.
PUSHING THE STANDARD MAIL ENVELOPE
One of the unique features of PowerTalk is that it allows many individual applications
to add support for mailing documents directly, without going through an intermediate
e-mail application such as QuickMail or AppleLink. The Standard Mail Package
provides a consistent interface for mailing documents from one user to another within
applications, and includes all of the human interface elements needed to address, send,
and receive messages. The major component of the Standard Mail Package is themailer .
The mailer is a window pane that's at the top of all documents that are mailed. The
mailer window pane can be contracted to display only a single line or expanded to allow
manipulation of the mailer's contents. Figure 1 shows a CollaboDraw window
containing an expanded mailer window pane.
Figure 1 CollaboDraw Window With a Mailer
The mailer can be thought of as a kind of extended mailing label. It contains not only the
names of the sender and receivers of the letter, but also a subject for the letter and an
area where files and folders can be enclosed.
Making an application mail-aware involves adding several standard menu items. In
CollaboDraw, there's a separate Mail menu, but if this isn't a viable option, it's
acceptable to add these menu items to the File menu. The standard Mail menu is shown
in Figure 2. The items Reply to All, Open Next Letter, and Tag Letter are optional and
not required for minimal mailer support.
Figure 2 The Mail Menu
When users want to send a document from CollaboDraw, their favorite
PowerTalk-savvy drawing program, they simply add a mailer to their drawing
document, transforming the document into a letter. They fill out the mailer and choose
Send from the Mail menu. The letter is then sent automatically to the recipient's
mailbox in the Finder. Recipients of the document would, in turn, double-click the
letter they received in their PowerTalk Finder mailbox, which opens the letter in
their copy of CollaboDraw and displays it with the attached mailer. Once they were
done reviewing the letter, they could keep the mailer attached if they wanted to reply
to the letter, forward the letter, or keep the additional information the mailer
provides. Or they could select Remove Mailer from the Mail menu, which removes the
mailer from the window, transforming the letter back into adocument. (The Remove
Mailer menu item replaces Add Mailer when there's a mailer in the window.)
Much of the power of PowerTalk Standard Mail stems from the fact that all
PowerTalk-aware applications support an additional file type: the letter. In the
Finder, letters can appear in disk windows, in the PowerTalk Finder mailbox window,
and even on the desktop or in the trash. Users can treat these letters like standard
documents, dragging them between folders to copy them, dragging them to the trash to
erase them, and even double-clicking them or dragging them to an application to open
them. When integrating mailer support into an existing application, it's best to think
of letters in much the same way -- simply as an additional document type. Using this
strategy, we'll see that adding a mailer requires little in the way of application
redesign.
UNLOCKING THE POWER OF DIGITAL SIGNATURES
Another very powerful PowerTalk feature that can be added to document-based
applications with a small amount of effort is digital signatures. PowerTalk's DigiSign
digital signature technology allows you to apply a personal "signer" to an object or a
file before distribution. Other users can then verify the digital signature, which
guarantees the identity of the person who signed the object as well as ensuring that the
object has not been altered in any way. If the object is modified after being signed, the
signature verification will fail, which will indicate that either the object has changed
or the signature has been tampered with.
Digital signature support also requires adding several menu items. These items are
normally added to an application's Edit menu, but because CollaboDraw has plenty of
space in the menu bar, they were separated into a Signatures menu (see Figure 3).
Figure 3 The Signatures Menu
Within CollaboDraw, digital signature support is provided for the individual shapes
and groups of shapes. To sign a shape, the user simply selects the shape (or group) and
then chooses Sign Selected Shapes from the Signatures menu. A dialog box appears,
prompting for the user's signer identification code. Once the user enters the password
protecting the signer, the selected shape is signed; a dashed rectangle appears around
the shape, with a small icon button (labeled with a pen) in the lower right corner,
indicating that the shape has been signed. (If you were adding digital signature support
to a text-based application, the dashed rectangle would surround the signed text.)
Figure 4 shows a signed shape.
Figure 4 A Signed Shape
To verify the integrity of the signature, a user could either click the pen button in the
corner of the shape or select the shape and choose Verify Selected Shapes from the
Signatures menu. If the signature verification is successful, the dialog box in Figure 5
is displayed, showing the identity of the signer.
Figure 5 Signature Verification Dialog Box
The DigiSign Digital Signature Manager provides routines to display the dialog boxes
described above, as well as standard icons for use in constructing the pen icon button.
This makes adding digital signature support a relatively painless operation.
LETTER FORMATS
As was mentioned earlier, you can think of letters as another type of document that
your application needs to support. Before describing how to add support for this new
document type, we'll spend some time discussing the format of PowerTalk letters.
Letters are a special kind of PowerTalkmessage. A letter is different from a message
in that it is sent from one user to another and is meant to be read by a human, whereas
a standard message is sent from one program to another and is meant to be read by a
program. Both share the same low-level format, consisting of amessage header and a
series ofmessage blocks .
The message header describes the message as a whole, including who the message is
from, who the message is to, the subject of the message, the date it was sent, and
whether the message is a letter. The header stores most of the information contained
in the mailer window pane shown in Figure 1, with the exception of enclosures.
Each message also contains message blocks, where the actual message data is stored.
Each block has a type and a creator, as well as message data and a length field.
PowerTalk-defined message blocks store message enclosures, digital signatures, or
message content. In addition, application-specific message blocks can be stored here.
PowerTalk letters have a well-defined content format, which is made up of any
combination of three formats: AppleMail format, Snapshot format, and Native
Application format. Figure 6 shows a letter with all three of these content formats.
Figure 6 PowerTalk Letter With Content Blocks
AppleMail format is one of the most commonly supported content types. It's made up of
runs of text, styled text, PICTs, sounds, and QuickTime movies. In Figure 6, the
AppleMail block contains a small amount of styled text, followed by a picture, followed
by a sound in AIFF format. Using Standard Mail routines, applications can easily get
this content out of a letter and display it to the user. AppleMail format is the native
format for the AppleMail letter application, which ships with PowerTalk. This means
that if you send a letter from your mail-aware application and the recipient doesn't
have a copy of that application, the recipient will still be able to read the letter's
content if you included it in AppleMail format. In addition, PowerTalk Mail Service
Access Modules (MSAMs) will most likely use this format to convert messages to other
external mail systems.
Snapshot format consists simply of PICT snapshots of each page of your letter. It's
similar to AppleMail format in that other letter applications or MSAMs are likely to
be able to read mail sent in this format. Snapshot format is provided for the
convenience of fax gateways, which can easily use it to image letters to fax machines,
and also to offer a WYSIWYG format that preserves the exact look of the original
document.
For applications that use QuickDraw GX, the graphics content for each page needs to be
translated into standard QuickDraw before it can be added to the Snapshot content
block. QuickDraw GX provides a set of routines for this purpose, contained in
PicturesAndPICTLibrary (and documented within that library's source code on the
QuickDraw GX CD). These routines allow you to pass in a QuickDraw GX picture and
receive a QuickDraw PICT as a result. On a QuickDraw system, only the QuickDraw
data in this PICT will be drawn. When you pass the PICT into a QuickDraw GX system
and convert it with the GXConvertPICTToShape routine, the routine will use the
QuickDraw GX data rather than the QuickDraw data. Finally, Native Application format
is basically a copy of your original document's disk file put into the letter's content
area. This format, meant mostly for the private use of your application, is useful for
sending documents between two users who both have the same PowerTalk-aware
application. For example, if two users had CollaboDraw, our mail-aware application,
and one user sent the other a CollaboDraw letter that included the document in Native
Application format, the receiving application could simply extract an FSSpec for the
document file to interpret the data in that document. This means you won't lose