TweetFollow Us on Twitter




[IMAGE Falkenburg_final_REV1.GIF]

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.


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.

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.

[IMAGE Falkenburg_final_REV2.GIF]

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.

[IMAGE Falkenburg_final_REV3.GIF]

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.

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).

[IMAGE Falkenburg_final_REV4.GIF]

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.

[IMAGE Falkenburg_final_REV5.GIF]

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.

[IMAGE Falkenburg_final_REV6.GIF]

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.


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.

[IMAGE Falkenburg_final_REV7.GIF]

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 information by translating your document into another format, but can instead preserve your private document format.


It's time to look at our sample application. For simplicity, PowerTalk support will be added to a limited MacDraw®-like application, CollaboDraw, included on this issue's CD. In this section I briefly describe the basic application framework. Later sections will show how I added support for the mailer and digital signatures.

The CollaboDraw application is based on a simplified object-oriented message-passing framework. It's simplified in that only windows are treated as objects, and the code is actually written in C, not C++. The basis for this object scheme is a block containing the window content, along with functions, calledmethods , for processing events that occur in that window. The block is a handle that's allocated dynamically for each window and is stored in the window's refCon field. In this way, I can remove all of the multiwindow complexity from my event loop and simply send a message to the window receiving the event, letting it take its own action.

I won't go into the details of what the CollaboDraw framework does, as I want to concentrate on the PowerTalk aspect of the sample. It's important to recognize, however, that CollaboDraw is a fairly typical drawing application. As you'll see, it's certainly not necessary to redesign an application to add PowerTalk support.


A large part of the PowerTalk support code in CollaboDraw is for the mailer window pane and for enabling the mailer to send and receive letters. I've outlined the necessary code below, with samples interspersed showing proper use of the Standard Mail Package calls.

Before using PowerTalk in CollaboDraw, we first need to make sure that PowerTalk services are available. This is done once when CollaboDraw launches. The following routine checks whether PowerTalk is installed and available:

Boolean HasStandardMail(void)
    OSErr   err;
    long    response;

    err = Gestalt(gestaltSMPMailerVersion, &response);
    if ((err!=noErr) || (response==0))
        return false;
    return true;

The above routine determines whether PowerTalk and the mailer calls are available by checking the gestaltSMPMailerVersion attribute. Since PowerTalk may not be installed or may be disabled, quitting when PowerTalk is unavailable is incorrect behavior. Instead, like CollaboDraw, the application should just disable or hide its PowerTalk services, letting the user work with the rest of the application normally.

Once it's known that PowerTalk is available and active, the next step to using Standard Mail services in CollaboDraw is to initialize the Standard Mail Package.

OSErr InitStandardMail(void)
    OSErr err;
    err = SMPInitMailer(kSMPVersion);
    return err;

SMPInitMailer takes the current version number of the Standard Mail Package as input. Later versions of PowerTalk will continue to support older Standard Mail calls by identifying the version the application was compiled with and mimicking those interfaces.

Now that CollaboDraw has checked for and initialized the Standard Mail Package, it can continue normally, entering its event loop. The next support code we'll cover deals with opening letters and creating new letters from existing drawings.

Typically, a user opens a letter in CollaboDraw, or any other mail-aware application, by double- clicking a letter in the Finder. This, in turn, generates an Open Document core Apple event, which we process in the normal way, with one change: instead of getting the FSSpec out of the event, mail- aware applications need to check the type of each item in the event, handling both FSSpecs and LetterSpecs. The LetterSpec is necessary since PowerTalk letters, in addition to residing in the file system, can be opened from the PowerTalk mailbox, which is not an HFS volume. A LetterSpec uniquely identifies a letter inside the mailbox and can be passed via an Apple event to the mail-aware application to open a letter. The following section of the Apple event handler shows how to process both LetterSpecs and FSSpecs:

AECountItems(&docList, &itemsInList);
    for (index=1; index<=itemsInList; index++) {
        err = AESizeOfNthItem(&docList, index, &returnedType, &size);
        if (err!=noErr)
            return err;
        if ((returnedType == typeLetterSpec) || 
               (returnedType==typeFSS)) {
            diskForm = false;
            err = AEGetNthPtr(&docList, index, typeLetterSpec,
                    &keywd, &returnedType, (Ptr)&myLetterSpec,
                    sizeof(LetterSpec), &actualSize);
        } else if (returnedType == typeAlias) {
            diskForm = true;
            err = AEGetNthPtr(&docList, index, typeFSS, &keywd,
                    &returnedType, (Ptr)&myFSS, sizeof(myFSS),
    if (err!=noErr)
        return err;
    if ((returnedType==typeLetterSpec) || (returnedType==typeAlias) ||
            (returnedType==typeFSS)) {
        err = HandleOpenDoc(diskForm, &myFSS, &myLetterSpec);
    if (err!=noErr)
        return err;

To handle opening either LetterSpecs or FSSpecs as letters, PowerTalk defines a variant structure called a LetterDescriptor that supports both formats. Once we have a LetterDescriptor, we can use this information to open the letter. The mailer-window method CollaboDraw uses to open letters is shown below.

void *DMailerLoadWindow(WindowPtr window, WInfoPtr infoPtr, void *data)
    OSErr               err;
    LetterDescriptor    *letterDesc;
    Point               upLeft = {0, 0};
    FSSpec              enclSpec;
    Handle              letterDescHndl;
    . . .
    letterDesc = (LetterDescriptor *)data;
    . . .
    err = SMPOpenLetter(letterDesc, window, upLeft, true, 
            gPreferences.expandOnOpen, nil, 0L);// Open the letter.
    if (err!=noErr) {
        return nil;
    err = SMPGetMainEnclosureFSSpec(window, &enclSpec);
    if (err!=noErr) {
        return nil;
    return DrawLoadWindow(window, infoPtr, &enclSpec);

After some housekeeping, which has been omitted for clarity, the load method given above calls SMPOpenLetter to open the letter in an existing window. The window was created earlier and was passed into the load method as input. SMPOpenLetter registers this window with the Standard Mail Package and associates it with the letter identified in the LetterDescriptor. SMPGetMainEnclosureFSSpec is then called to extract the native CollaboDraw document out of the letter, as described earlier in the section "Letter Formats." Finally, the standard CollaboDraw load method is called, which reads the shapes from the document and draws them in the window. CollaboDraw supports opening only letters that contain its native application format, meaning that if the main enclosure block is not present, CollaboDraw doesn't open the letter. For an application to support opening letters without native application content, translation into one of the other content types would be necessary.

In addition to opening existing letters, CollaboDraw allows users to add mailers to existing documents, transforming these documents into letters. When a user chooses the menu item Add Mailer, the following routine is called:

void MakeMailerFromDrawing(WindowPtr window)
    WInfoPtr    infoPtr;
    char        hState;
    Point   topLeft = {0, 0};
    OSErr   err;
    short   mWidth, contHeight, expHeight;
    SetWindowKind(window, kDrawMailerWindow);
    infoPtr = BeginWindowAccess(window, &hState);
    . . .

    // Add the mailer.
    err = SMPNewMailer(window, topLeft, true,
            gPreferences.expandOnCreate, kDefaultIdentity, nil, 0L);
    if (err!=noErr)
    // Set the window indent fields.
    err = SMPGetDimensions(&mWidth, &contHeight, &expHeight);
    if (err!=noErr)
    if (infoPtr->otherFlags[kMailerExpanded])
        infoPtr->topIndent = expHeight;
        infoPtr->topIndent = contHeight;
    EndWindowAccess(window, hState);

When a user chooses to turn a document into a letter, the MakeMailerFromDrawing routine first changes the class of the window. This in turn causes the mailer-window methods, instead of the draw-window methods, to be called in response to events. Next, this routine adds a mailer to the window with an SMPNewMailer call. Like SMPOpenLetter, this routine associates a particular window with a Standard Mail letter. The kDefaultIdentity parameter to SMPNewMailer is defined as 0 and indicates that the Standard Mail Package should track identities for the application. Finally, the content area of the window is lowered to account for the added height of the mailer. This height can be obtained with an SMPGetDimensions call, which returns both the expanded and contracted heights of the mailer.

Since letters are a new document type, new methods are needed to handle events in letter windows. As we'll see, however, we can leverage off of our window class structure to minimize additional code.

When a window contains a mailer, PowerTalk handles a subset of events for that window automatically. This includes mouse-down events, key-down events, update events for the mailer window pane, activate events, deactivate events, and even null events. The event-handling method for mailer windows is as follows:

void *DMailerEventWindow(WindowPtr window, WInfoPtr infoPtr,
         void *data)
    SMPMailerResult     whatHappened;
    EventRecord         *ev;
    OSErr               err;

    ev = (EventRecord *)data;
    err = SMPMailerEvent(ev, &whatHappened, nil, 0L);
    if (err!=noErr) 
    return (void *)(ProcessPowerTalkWhatHappened(window, infoPtr, 

So that PowerTalk will get a first look at the events, CollaboDraw calls SMPMailerEvent with each event received via WaitNextEvent when the frontmost window is a mailer window. This routine will return a value in the whatHappened field indicating what action Standard Mail took and whether you still need to process the event. Here's the postprocessing code for these events:

Boolean ProcessPowerTalkWhatHappened(WindowPtr window, WInfoPtr
                                infoPtr, SMPMailerResult mailResult)
    OSErr           err;
    SMPMailerState  state;
    long                *lastChanged;
    // See if mailer has changed since we last changed the mailer
    // menus.
    err = SMPGetMailerState(window, &state);
    if (err != noErr)
    lastChanged = (long *)&infoPtr->otherData[kLastChangedData];
    if (*lastChanged != state.changeCount) {
        *lastChanged = state.changeCount;
        infoPtr->changed = true;
        FixMailerMenus(window, infoPtr);
    if ((mailResult & kSMPContractedMask) != 0)
        HandleContract(window, infoPtr);

    if ((mailResult & kSMPExpandedMask) != 0)
        HandleExpand(window, infoPtr);
    if (((mailResult & kSMPMailerBecomesTargetMask) != 0) ||
            ((mailResult & kSMPAppBecomesTargetMask) != 0))
        FixMailerMenus(window, infoPtr);
    // Check the menus for *every* event that the mailer handles.
    // We may need to update the Undo item in the File menu.
    if ((mailResult & kSMPAppShouldIgnoreEventMask) != 0)
        FixMailerMenus(window, infoPtr);
    if ((mailResult & kSMPAppMustHandleEventMask) != 0)
        return false;       // App must handle this event.
    else return true;       // Mailer handled this event completely.

Most of the postprocessing involves recalculating the menu items, since the mailer may have affected which items should be active. In addition to this menu handling, if the kSMPContracted or kSMPExpanded bit is set as a result of the event, CollaboDraw calls its own private routine HandleExpand or HandleContract. In turn, this routine calls SMPExpandOrContract to expand the mailer to its full size or contract it to a single line.

Besides generic event processing, we need to add some minor modifications to the mouse-click method for mailer windows. This is reasonably straightforward:

void *DMailerClickWindow(WindowPtr window, WInfoPtr infoPtr,
         void *data)
    RgnHandle   savedClip;
    GrafPtr         savePort;
    void            *returnVal;
    OSErr       err;
    Boolean         alreadyChanged;
    // Make sure we can change the letter.
    alreadyChanged = infoPtr->changed;
    if (!alreadyChanged && (gCurrentShape!=kSelectShape)) {
        err = SMPPrepareToChange(window);
        if (err==userCanceledErr)
            return nil;

    // Since we're drawing a shape, clear any mailer undo buffer.
    err = SMPClearUndo(window);
    if (err!=noErr)
    // Remove mailer from clipping region.
    savedClip = NewRgn();
    ClipToDrawing(window, infoPtr);
    // Call draw-window click method and maybe mark letter changed.
    returnVal = DrawClickWindow(window, infoPtr, data);
    if (!alreadyChanged && infoPtr->changed) {
        err = SMPContentChanged(window);
        if (err!=noErr)

    // Restore clipping region.
    return returnVal;

Before passing the click up to the draw-window method to draw or select shapes, we need to notify PowerTalk that the letter content will be changing. To do this, we first call SMPPrepareToChange. If the letter has been digitally signed as a whole, a dialog box warning the user will appear. If the user cancels the change in response to the dialog box (the user may not want to invalidate the signature), the routine exits. Next, the SMPClearUndo routine clears any undo operations from the mailer undo buffer, since only one undo can be pending for a single window. Then the draw area is removed from the window's clipping region, and the superclass click method is called. Upon return, SMPContentChanged is called if the letter has changed. Finally, the clipping region is restored and the method exits.

As you may have noticed from the above discussion, the mailer keeps its own undo buffer. This is because Standard Mail supports the Clipboard operations of Cut, Copy, Paste, Clear, Select All, and Undo for the mailer portion of letters. The code necessary to support the Clipboard is shown in the mailer-window Cut method:

void *DMailerCutWindow(WindowPtr window, WInfoPtr infoPtr,
            void *data)
    #pragma unused (data)
    OSErr               err;
    SMPMailerResult whatHappened;
    err = SMPMailerEditCommand(window, kSMPCutCommand,
    if (err!=noErr)
    return (void *)(ProcessPowerTalkWhatHappened(window, infoPtr, 

As you can see, support for Clipboard operations involves just a single call to SMPMailerEditCommand followed by a call to the CollaboDraw routine ProcessPowerTalkWhatHappened. Similar methods are used for Copy, Paste, Clear, Select All, and Undo.

Using the code discussed above, CollaboDraw can open and create letters, as well as address them via the mailer. However, a mail-aware application needs to be able to send letters as well. This section extracts the relevant pieces of the CollaboDraw CommSendLetter routine to explain the process of sending a letter step by step. The first step in sending a letter is to display the send options dialog box. This dialog is very similar to the standard print dialog, providing the user with options as to how the letter should be sent. CollaboDraw uses the following code to display this dialog:

GetResString(nativeFormat, kAppNameID, kAppName);
GetWTitle(window, docTitle);
nativeFormatArray[0] = (StringPtr)nativeFormat;
err = SMPSendOptionsDialog(window, docTitle, nativeFormatArray, 1,
        kSMPNativeMask | kSMPImageMask | kSMPStandardInterchangeMask,
        &gPreferences.sendFormat, nil, 0L, &gPreferences.sendFormat,

if (err==userCanceledError)
if (err!=noErr) {

The SMPSendOptionsDialog routine is built into the Standard Mail Package and handles the task of prompting the user for send options. As input, this routine takes the mailer window, the name of the document being mailed, a list of supported native formats, a list of which send formats are supported, and several other send option flags. This routine returns the name of the format that should be used to send the letter, which is used in the next part of the send process:


// Use our creator if we have native format, else use AppleMail
// creator.
if ((gPreferences.sendFormat.whichFormats & kSMPNativeMask)!=0) {
    letterCreator = kAppCreator;
    letterType = kCDLtrMsgType;
else {
    letterCreator = 'lap2';
    letterType = kMailLtrMsgType;
err = SMPBeginSend(window, letterCreator, letterType,
        &gPreferences.sendOptions, &mustAddContent);
if (err!=noErr) {
    EndWindowAccess(window, hState);
if (mustAddContent) {
    if (err==noErr)
        err = AddLetterBlocks(window, infoPtr,
    if (err!=noErr)
err = SMPEndSend(window, (err==noErr));
if (err!=noErr)

The above code first calls SMPBeginSend to start the send process. The send options are passed as input to this routine, and relevant information is extracted to build the header for the letter. This call also signals the Standard Mail Package that any content-adding calls apply to the letter specified in the SMPBeginSend call. Next, the actual blocks of content are added to the letter with the CollaboDraw AddLetterBlocks call, described below. Note that the content blocks are added only if mustAddContent, which is returned from SMPBeginSend, is true. It isn't necessary to add content blocks if a letter is being forwarded unchanged.

Finally, the SMPEndSend call completes the send process. The second parameter to SMPEndSend is true if the letter should be sent, false if it should be aborted.

The AddLetterBlocks routine described above adds the content in any combination of the three formats described earlier in the section "Letter Formats." It simply checks the sendFormat parameter returned from the SMPSendOptions dialog box to determine which formats to add. Native Application format is specified by kSMPNativeMask, AppleMail format by kSMPStandardInterchangeMask, and Snapshot format by kSMPImageMask.

Routines for adding content in the three formats follow.

Native Application format. The AddNativeContent routine adds content in Native Application format to a letter.

OSErr AddNativeContent(WindowPtr window, WInfoPtr infoPtr,
                                StringPtr nativeFormatName)
    OSErr           err;
    FSSpec          fSpec;
    OCECreatorType  blockType;
    // Save file temporarily.
    err = SaveFileToTemp(infoPtr, &fSpec);
    if (err!=noErr)
        return err;
    err = SMPAddMainEnclosure(window, &fSpec);
    // Add native format name string block.
    if (err==noErr) {
        blockType.msgCreator = kMailAppleMailCreator;
        blockType.msgType = kSMPNativeFormatName;
        err = SMPAddBlock(window, &blockType, false,
                &nativeFormatName[1], nativeFormatName[0],

    return err;

Native content is stored and accessed via file system FSSpecs, so adding content in this format requires that the document to be included first be saved in a temporary file. The SaveFileToTemp routine, not shown here, does this. Once an FSSpec to the document is available, SMPAddMainEnclosure is called and passed the letter window and the FSSpec. Finally, once this routine completes, a block is added to indicate the name of the native format used in the letter. Note that the native content for CollaboDraw is simply a CollaboDraw drawing document. This document is extracted when a letter is opened to get the list of shapes present in that letter.

AppleMail format. Content in AppleMail format is added with the following routine:

OSErr AddAppleMailLetterContent(WindowPtr window, WInfoPtr infoPtr)
    OSErr       err;
    PicHandle   thePicture;
    thePicture = DrawImageToPicture(window, infoPtr);
    if (thePicture) {
        err = SMPAddContent(window, kMailPictSegmentType, false, 
                *thePicture, GetHandleSize((Handle)thePicture), nil,
                true, smRoman);
        return kInternalError;
    return err;

Content in AppleMail format consists of a series of blocks containing text, styled text, pictures, sound, or movies. For CollaboDraw, we simply add a picture block containing all of the shapes in the current document. To add this block, we first call DrawImageToPicture, a CollaboDraw routine to allocate a PicHandle containing the shapes. We then call SMPAddContent with this picture to add the block.

Snapshot format. The final content format supported by CollaboDraw is Snapshot format, and the routines below add a Snapshot block to a letter.

OSErr AddLetterImage(WindowPtr window, WInfoPtr infoPtr)
    return SMPImage(window, DrawImageProc, (long)infoPtr, false);

pascal void DrawImageProc(long refCon, Boolean inColor)
    #pragma unused (inColor)
    OpenCPicParams  newHeader;
    OSErr           err;
    Point           zeroPt = {0, 0};
    WInfoPtr        infoPtr;
    TPrInfo             prInfo;
    infoPtr = (WInfoPtr)refCon;
    prInfo = (**(infoPtr->printRecord)).prInfo;
    newHeader.srcRect = prInfo.rPage;
    newHeader.hRes = FixRatio(prInfo.iHRes, 1);
    newHeader.vRes = FixRatio(prInfo.iVRes, 1);
    newHeader.version = -2;
    newHeader.reserved1 = 0;
    newHeader.reserved2 = 0L;
    err = SMPNewPage(&newHeader);
    if (err!=noErr)
    DrawAllShapes(infoPtr, zeroPt);

The SMPImage call takes care of including these image blocks for a letter. This routine is given the letter window and a draw-image routine, as well as a generic data pointer as input. The draw-image routine for CollaboDraw is called DrawImageProc; it accepts the window info block in the data pointer field. This callback first sets up the resolution and size of the page by extracting this information from the print record for the window. Next, SMPNewPage is called to set up the port into which the shapes will be imaged. Finally, the shapes are drawn into the page with the CollaboDraw routine DrawAllShapes, adding the final content blocks to the letter.

Once a letter has been opened within CollaboDraw, several options are available. If additional correspondence is necessary, the letter can be replied to or forwarded. The mailer can also be removed, which turns the letter back into a document. This operation is very similar to closing a letter and is described in the next section. The following code is used to reply to a letter:

replyWindow = MakeWindow(kDrawMailerWindow, &newWindRect, newTitle,
err = SMPMailerReply(window, replyWindow, replyToAll, topLeft, true,
        true, kDefaultIdentity, nil, 0L);
if (err!=noErr)

The first step in replying to a letter is to make a new window in which the reply letter will be created. The CollaboDraw routine MakeWindow is called to create a new window of the mailer class. Once this window has been created, SMPMailerReply can be called, which takes the existing letter window, the new letter window, and several other parameters as input. As a result of the call, the reply letter is created and automatically addressed to the originator of the original message.

The mail forwarding process does not involve the creation of a new letter window. Instead, another mailer is added to the existing letter, and the mailers can be viewed by clicking a dog-ear in the corner of the mailer window pane. The code to forward a letter is as follows:

void CommForward(WindowPtr window)
    WInfoPtr    infoPtr;
    char        hState;
    OSErr   err;
    infoPtr = BeginWindowAccess(window, &hState);
    HandleExpand(window, infoPtr);  
                              // Expand window before doing forward.
    err = SMPMailerForward(window, kDefaultIdentity);
    if (err!=noErr)
    infoPtr->saved = false;
    DMailerActivateWindow(window, infoPtr, nil);
    EndWindowAccess(window, hState);

To forward a letter, the mailer in the window is first expanded. This allows the new mailer to be fully visible when it's created. The CollaboDraw routine HandleExpand calls SMPExpandOrContract to expand the mailer. Next, SMPMailerForward actually adds the mailer to the letter. Once this is done, the state of the document is changed to indicate that the letter is now an outgoing letter instead of a received letter. Finally, the activate-event method is called on the window to readjust the menu items that relate to sending mail.

When it's time to close a letter window, there's a short process that must be adhered to. First, the optional close options dialog box can be displayed. This dialog gives the user the option of deleting the letter or tagging it before it's closed. CollaboDraw uses the following code to display this dialog:

if (gPreferences.closeOptionsDialog) {
    err = SMPCloseOptionsDialog(window, &gPreferences.closeOptions);
    if (err!=noErr)
        returnValue = false;

Since the dialog box is optional, CollaboDraw has a preference variable that tracks whether the dialog should be displayed. If it should be displayed, this is done by calling SMPCloseOptionsDialog with the letter window and the close options to use when closing the letter. Note that the close options are also stored in the preferences, to allow the dialog to default to the close options last used.

The next step in the close process is to make sure that there are no open enclosures and that there are no Finder copies in progress that would prevent the closure of the letter. The following code excerpt checks for this:

err = SMPPrepareToClose(window);
if (err==kSMPHasOpenAttachments) {
    StopAlert(kHasOpenAttachID, nil);
    returnValue = false;
else if (err==kSMPCopyInProgress) {
    StopAlert(kCopyInProgress, nil);
    returnValue = false;

SMPPrepareToClose returns kSMPHasOpenAttachments if there are open enclosures and kSMPCopyInProgress if the user is in the process of copying a document to or from the enclosures list. In response, CollaboDraw presents an alert to the user and will not allow the letter to be closed.

The final steps in closing the letter are to remove the mailer from the window and close the window. Here's the code to do this removal:

err = SMPDisposeMailer(window, closeOptions);
if (err!=noErr)
return DrawDestroyWindow(window, infoPtr, data);

The PowerTalk routine SMPDisposeMailer removes the mailer pane from the window passed as input and releases all memory associated with the letter window. Once this is done, CollaboDraw calls the draw-window method for closing a window, which takes care of disposing of the rest of the window and document structures.


Digital signature services can also be incorporated into applications, providing a level of security not previously possible with personal computers. CollaboDraw allows signing and verifying within documents at a shape level. Individual shapes can be selected and signed, and the signatures are carried around with the shapes when the documents are saved or sent to other users. In addition to this shape-level digital signature support, the Standard Mail Package provides support for signing letters as a whole. By supporting the mailer, we automatically get this letter-based digital signature functionality.

Since digital signatures are quite large in size (they can be several kilobytes each), I elected not to store the signatures in memory with the document shapes. Instead, I store the signatures in the resource fork of each document file. The signature storage strategy is not covered in depth in the code below, but you can refer to the digital signature code within CollaboDraw to see how it's done.

To sign a shape or set of shapes within CollaboDraw, the user must select the shapes and choose the Sign Selected Shapes menu item. In response to this, the following code is called:

void CommSign(WindowPtr window)
    WInfoPtr        infoPtr;
    char                hState;
    ShapeListPtr    shapeList;
    SIGContextPtr   sigContext;
    Size                sigSize;
    OSErr           err;
    if (!IsAppWindow(window))
    err = SIGNewContext(&sigContext);
    if (err==noErr) {
        infoPtr = BeginWindowAccess(window, &hState);   
        err = SIGSignPrepare(sigContext, nil, nil, &sigSize);
        for (shapeList=infoPtr->data;
                (err==noErr) && (shapeList!=nil);
                shapeList=shapeList->next) {
            if (shapeList->selected) {
                err = SignShape(infoPtr, sigContext, shapeList,
                InvalShapeArea(window, infoPtr, shapeList);
                                                     // Redraw shape.
        DSIGSetupSignMenu(window, infoPtr);
        EndWindowAccess(window, hState);
    if (err!=noErr)

The first important call in the above code is SIGNewContext. This routine creates a digital signature context, which is required for each signing or verification session. Creating a context allocates the resources needed to perform signing and verification of objects.

Next, SIGSignPrepare is called. This routine prompts the user to enter a signer identification code, allowing the signer to be applied to the selected objects.

Now that the signature has been set up, each shape can be signed individually with a call to the CollaboDraw routine SignShape. Once each shape has been signed, SIGDisposeContext can be called to end the signing session.

The SignShape routine carries out the task of producing and storing a signature for each shape to be signed, as follows:

OSErr SignShape(WInfoPtr infoPtr, SIGContextPtr sigContext,
                    ShapeListPtr theShape, Size sigSize)
    OSErr           err;
    Handle          signature;
    short           resID;
    short           saveResFile;
    DigSigListPtr   theSig;
    // Allocate storage for the signature.
    signature = NewHandleChk(sigSize);
    if (MemError()!=noErr)
        return MemError();
    // Process the data for the signature.
    err = ProcessShapeData(sigContext, theShape);
    if (err!=noErr) {
        return err;
    // Create the signature.
    err = SIGSign(sigContext, (SIGSignaturePtr)*signature, nil);
    if (err!=noErr)
        return err;
    // Add the signature to the shape.
    saveResFile = CurResFile();
    resID = Unique1ID(kSignatureResType);
    AddResource(signature, kSignatureResType, resID, "\p");

    . . .

Before a shape can be signed, memory must first be allocated to hold the signature for the shape. The size of the block required to hold the signature is returned by SIGSignPrepare, and this value is passed in as the sigSize parameter to the SignShape routine.

Once the signature storage has been allocated, all of the data to be signed in the shape must be handed to the Digital Signature Manager in a byte stream. This process is required to generate a unique number identifying the contents of the document. The CollaboDraw routine ProcessShapeData handles this data streaming. Within ProcessShapeData, the Digital Signature Manager routine SIGProcessData is called to stream the data.

err = SIGProcessData(sigContext, theShape, kShapeSignLength);

Once the unique number, also known as adigest , has been created, the signer is then applied to that number to create a signature with the call SIGSign. The signature is stored in the handle allocated at the start of the routine and is then added to the resource fork of the document file.

Once a shape has been signed, it can later be verified from within CollaboDraw. The high-level CollaboDraw routine CommVerify is called in response to the Verify Selected Shapes menu item. This routine is almost identical to the CommSign routine given earlier, so it isn't included here. It simply calls SIGNewContext and then repeatedly calls the CollaboDraw routine VerifyShape. Once each shape has been verified, CommVerify calls SIGDisposeContext.

The VerifyShape routine is analogous to the SignShape routine. Instead of adding a signature to a shape, this routine retrieves the signature for a shape, verifies the signature, and displays information about the signer.

signatureSize = SizeResource(sigHandle);
err = SIGVerifyPrepare(sigContext, (SIGSignaturePtr)*sigHandle,
          signatureSize, nil);
if (err==noErr) {
    // Process the data for the signature.
    err = ProcessShapeData(sigContext, theShape);
    if (err==noErr) {
        err = SIGVerify(sigContext);
        if (err==noErr)
        err = SIGShowSigner(sigContext, nil);   // Show signer info.

The section of VerifyShape shown above comes just after the signature is extracted from the resource fork of the document. Once the signature is in sigHandle, SIGVerifyPrepare is called. This routine prepares the Digital Signature Manager to receive data via the SIGProcessData call. Once this data has been streamed to create a digest, the digest is compared to the one stored in the signature with the SIGVerify routine. This routine will return noErr if the two digests match. When this occurs, a SIGShowSigner call will present a dialog box displaying information about the signer of the shape.


This discussion of the PowerTalk Standard Mail and Digital Signature packages doesn't even begin to touch on the many features available to developers through PowerTalk. You can take advantage of InterProgram Messaging for store and forward application communication, use the Standard Catalog interfaces for picking items out of catalogs, write custom catalog templates, use PowerTalk authentication services, or build service access modules to interface to alternate message delivery or directory catalog services. By adding standard mail and digital signature support to CollaboDraw, we've enhanced the usefulness of our simple drawing program in many ways. When combined with other applications that support PowerTalk collaborative services, communication and productivity within a workgroup can be taken to new levels.

STEVE FALKENBURG has been working in Apple's Developer Technical Support group ever since he finished his lastdevelop  article nearly three years ago. When not supporting PowerTalk (and Macintosh on PowerPC), Steve can be found hiking around California everywhere from Mount Tamalpais to Big Basin. Some people think he's just searching for the perfect mountain vista, but he's also trying his best to keep pace with his hiking partner, Nancy. *

DigiSign's digital signature implementation is based on a public key/private key standard developed by RSA Technologies, Inc. The technology underlying digital signatures is beyond the scope of this article; interested readers should refer to the PowerTalk documentation for more information. *

This article hasn't covered a few other PowerTalk features that CollaboDraw takes advantage of. Among these are printing, tagging letters, and opening the next letter from the mailbox. Refer to the sample code included on this issue's CD for implementation details of these features.*

THANKS TO OUR TECHNICAL REVIEWERS Godfrey DiGiorgi, John Evans, Steve Fisher, Martin Minow *


Community Search:
MacTech Search:

Software Updates via MacUpdate

Skype - Voice-over-internet p...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
Bookends 13.2.6 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
BusyContacts 1.4.0 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Chromium 77.0.3865.75 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 77.0.3865.75: A list of changes is available... Read more
DiskCatalogMaker 7.5.5 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Alfred 4.0.4 - Quick launcher for apps a...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more
A Better Finder Rename 10.45 - File, pho...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
iFinance 4.5.11 - Comprehensively manage...
iFinance allows you to keep track of your income and spending -- from your lunchbreak coffee to your new car -- in the most convenient and fastest way. Clearly arranged transaction lists of all your... Read more
OmniGraffle Pro 7.11.3 - Create diagrams...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
BBEdit 12.6.7 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more

Latest Forum Discussions

See All

Five Nights at Freddy's AR: Special...
Five Nights at Freddy's AR: Special Delivery is a terrifying new nightmare from developer Illumix. Last week, FNAF fans were sent into a frenzy by a short teaser for what we now know to be Special Delivery. Those in the comments were quick to... | Read more »
Rush Rally 3's new live events are...
Last week, Rush Rally 3 got updated with live events, and it’s one of the best things to happen to racing games on mobile. Prior to this update, the game already had multiplayer, but live events are more convenient in the sense that it’s somewhat... | Read more »
Why your free-to-play racer sucks
It’s been this way for a while now, but playing Hot Wheels Infinite Loop really highlights a big issue with free-to-play mobile racing games: They suck. It doesn’t matter if you’re trying going for realism, cart racing, or arcade nonsense, they’re... | Read more »
Steam Link Spotlight - The Banner Saga 3
Steam Link Spotlight is a new feature where we take a look at PC games that play exceptionally well using the Steam Link app. Our last entry talked about Terry Cavanaugh’s incredible Dicey Dungeons. Read about how it’s a great mobile experience... | Read more »
PSA: GRIS has some issues
You may or may not have seen that Devolver Digital just released GRIS on the App Store, but we wanted to do a quick public service announcement to say that you might not want to hop on buying it just yet. The puzzle platformer has come to small... | Read more »
Explore the world around you in new matc...
Got a hankering for a fresh-feeling Match-3 puzzle game that offers a unique twist? You might find exactly what you’re looking for with What a Wonderful World, a new spin on the classic mobile genre which merges entertaining puzzles with global... | Read more »
Combo Quest (Games)
Combo Quest 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Combo Quest is an epic, time tap role-playing adventure. In this unique masterpiece, you are a knight on a heroic quest to retrieve... | Read more »
Hero Emblems (Games)
Hero Emblems 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ** 25% OFF for a limited time to celebrate the release ** ** Note for iPhone 6 user: If it doesn't run fullscreen on your device... | Read more »
Puzzle Blitz (Games)
Puzzle Blitz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Puzzle Blitz is a frantic puzzle solving race against the clock! Solve as many puzzles as you can, before time runs out! You have... | Read more »
Sky Patrol (Games)
Sky Patrol 1.0.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.1 (iTunes) Description: 'Strategic Twist On The Classic Shooter Genre' - Indie Game Mag... | Read more »

Price Scanner via

Save $150-$250 on 10.2″ WiFi + Cellular iPads...
Verizon is offering $150-$250 discounts on Apple’s new 10.2″ WiFi + Cellular iPad with service. Buy the iPad itself and save $150. Save $250 on the purchase of an iPad along with an iPhone. The fine... Read more
Apple continues to offer 13″ 2.3GHz Dual-Core...
Apple has Certified Refurbished 2017 13″ 2.3GHz Dual-Core non-Touch Bar MacBook Pros available starting at $1019. An standard Apple one-year warranty is included with each model, outer cases are new... Read more
Apple restocks 2018 MacBook Airs, Certified R...
Apple has restocked Certified Refurbished 2018 13″ MacBook Airs starting at only $849. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is shipped free. The... Read more
Sunday Sale! 2019 27″ 5K 6-Core iMacs for $20...
B&H Photo has the new 2019 27″ 5K 6-Core iMacs on stock today and on sale for up to $250 off Apple’s MSRP. Overnight shipping is free to many locations in the US. These are the same iMacs sold by... Read more
Weekend Sale! 2019 13″ MacBook Airs for $200...
Amazon has new 2019 13″ MacBook Airs on sale for $200 off Apple’s MSRP, with prices starting at $899, each including free shipping. Be sure to select Amazon as the seller during checkout, rather than... Read more
2019 15″ MacBook Pros now on sale for $350-$4...
B&H Photo has Apple’s 2019 15″ 6-Core and 8-Core MacBook Pros on sale today for $350-$400 off MSRP, starting at $2049, with free overnight shipping available to many addresses in the US: – 2019... Read more
Buy one Apple Watch Series 5 at Verizon, get...
Buy one Apple Watch Series 5 at Verizon, and get a second Watch for 50% off. Plus save $10 on your first month of service. The fine print: “Buy Apple Watch, get another up to 50% off on us. Plus $10... Read more
Sprint offers 64GB iPhone 11 for free to new...
Sprint will include the 64GB iPhone 11 for free for new customers with an eligible trade-in in of the iPhone 7 or newer through September 19, 2019. The fine print: “iPhone 11 64GB $0/mo. iPhone 11... Read more
Verizon offers new iPhone 11 models for up to...
Verizon is offering Apple’s new iPhone 11 models for $500 off MSRP to new customers with an eligible trade-in (see list below). Discount is applied via monthly bill credits over 24 months. Verizon is... Read more
AT&T offers free $300 reward card + free...
AT&T Wireless will include a second free 64GB iPhone 11 with the purchase of one eligible iPhone at full price. They will also include a free $300 rewards card. The fine print: “Buy an elig.... Read more

Jobs Board

Student Employment (Blue *Apple* Cafe) Spri...
Student Employment (Blue Apple Cafe) Spring 2019 Penn State University Campus/Location: Penn State Brandywine Campus City: Media, PA Date Announced: 12/20/2018 Date Read more
Best Buy *Apple* Computing Master - Best Bu...
**732359BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Location Number:** 000171-Winchester Road-Store **Job Description:** Read more
*Apple* Mobile Master - Best Buy (United Sta...
**732324BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 000013-Fargo-Store **Job Description:** **What does a Best Read more
Best Buy *Apple* Computing Master - Best Bu...
**732455BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000449-Auburn Hills-Store **Job Description:** **What does a Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**732490BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Location Number:** 000449-Auburn Hills-Store **Job Description:** At Best Buy, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.