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

Hopper Disassembler 4.2.13- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
iFFmpeg 6.4.3 - Convert multimedia files...
iFFmpeg is a comprehensive media tool to convert movie, audio and media files between formats. The FFmpeg command line instructions can be very hard to master/understand, so iFFmpeg does all the hard... Read more
Firefox 55.0.2 - Fast, safe Web browser.
Firefox offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals and casual... Read more
FileZilla 3.27.1 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.27.1: Fixed Vulnerabilities: Change client... Read more
Merlin Project 4.2.7 - $289.00
Merlin Project is the leading professional project management software for OS X. If you plan complex projects on your Mac, you won’t get far with a simple list of tasks. Good planning raises... Read more
Dashlane 4.8.4 - Password manager and se...
Dashlane is an award-winning service that revolutionizes the online experience by replacing the drudgery of everyday transactional processes with convenient, automated simplicity - in other words,... Read more
f.lux 39.984 - Adjusts the color of your...
f.lux makes the color of your computer's display adapt to the time of day, warm at night and like sunlight during the day. Ever notice how people texting at night have that eerie blue glow? Or wake... Read more
Sketch 46.2 - Design app for UX/UI for i...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more
Microsoft Office 2016 15.37 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
Slack 2.7.1 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.7.1: You're nearly finished signing in when suddenly – bonk... Read more

Bottom of the 9th (Games)
Bottom of the 9th 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Play the most exciting moment of baseball in this fast-paced dice and card game! | Read more »
The best apps for viewing the solar ecli...
If you somehow missed the news, many parts of the United States will be witness to a total solar eclipse on August 21 for the first time in over 90 years. It'll be possible to see the eclipse in at least some capacity throughout the continental U... | Read more »
The 5 best mobile survival games
Games like ARK: Survival Evolved and Conan Exiles have taken the world of gaming by storm. The market is now flooded with hardcore survival games that send players off into the game's world with nothing but maybe the clothes on their back. Never... | Read more »
Portal Walk (Games)
Portal Walk 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Portal Walk is adventure and relaxing platform game about Eugene. Eugene stuck between worlds and trying to find way back home.... | Read more »
Technobabylon (Games)
Technobabylon 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: City of Newton, 2087. Genetic engineering is the norm, the addictive Trance has replaced almost any need for human interaction,... | Read more »
5 reasons why 2v2 is the best mode in Cl...
Supercell has been teasing fans with 2v2 windows that allow players to team up for limited periods of time. The Summer of 2v2 was just this past July, but players are already clamoring for more of that sweet, sweet team-based action. The fans have... | Read more »
The best deals on the App Store this wee...
It seems like the week's only just started, and yet here we are with a huge pile of discounted games to sort through. There are some real doozies on sale this week. We're talking some truly stellar titles. Let's take a look at four of the best... | Read more »
Cat Quest Guide - How to become a purrfe...
Cat Quest is an absolutely charming open-world RPG that's taken the gaming world quite by storm. This game about a world populated by furry kitty warriors is actually a full-length RPG with sturdy mechanics and a lovely little story. It's certainly... | Read more »
Silly Walks Guide - How to strut your st...
Silly Walks is an all new adventure game that lives up to its name. It sees you playing as a variety of snack foods as you teeter-totter your way to rescue your friends from the evil blender and his villainous minions. It's all very . . . well... | Read more »
The best mobile point-and-click adventur...
Nostalgia for classic point-and-click adventure games has reached an all-time high in recent years, and the rise of mobile games have provided a perfect platform for this old-school genre. This week we're going to take a look at some of the best... | Read more »

Price Scanner via

New iOS 11 Productivity Features Welcome But...
The iOS community is in late summer holding mode awaiting the September arrival of the iPhone 8 and iOS 11. iOS 11 public betas have been available for months — number six was released this week —... Read more
Samsung Electronics Launches New Portable SSD...
Samsung Electronics America, Inc. has announced the launch of Samsung Portable SSD T5 – its newest portable solid state drive (PSSD) that raises the bar for the performance of external memory... Read more
TrendForce Reports YoY Gain of 3.6% for 2Q17...
Market research firm TrendForce reports that the global notebook shipments for this second quarter registered a sequential quarterly increase of 5.7% and a year-on-year increase of 3.6%, totaling 39.... Read more
Sale! 10-inch iPad Pros for $50 off MSRP, no...
B&H Photo has 10.5″ iPad Pros in stock today and on sale for $50 off MSRP. Each iPad includes free shipping, and B&H charges sales tax in NY & NJ only: – 10.5″ 64GB iPad Pro: $599, save $... Read more
Sale! 2017 13-inch Silver 2.3GHz MacBook Pro...
Amazon has new 2017 13″ 2.3GHz/128GB Silver MacBook Pro on sale today for $100 off MSRP including free shipping. Their price is the lowest available for this model from any reseller: – 13″ 2.3GHz/... Read more
WaterField Unveils Collaboratively-Designed,...
In collaboration with customers and seasoned travelers, San Francisco maker WaterField Designs set out to create the preeminent carry-on system to improve the experience of frequent fliers. The... Read more
Miya Notes Mac-Client for Google Keep (Launch...
MacPlus Software has announced te launch of Miya Notes for Google Keep 1.0, a powerful Mac-client for Google Keep. Millions of people use Google Keep on their phones and online, but a convenient Mac... Read more
Apple refurbished iMacs available starting at...
Apple has previous-generation Certified Refurbished 2015 21″ & 27″ iMacs available starting at $849. Apple’s one-year warranty is standard, and shipping is free. The following models are... Read more
2017 13-inch MacBook Airs on sale for $100 of...
B&H Photo new 2017 13″ MacBook Airs on sale today for $100 off MSRP, starting at $899: – 13″ 1.8GHz/128GB MacBook Air (MQD32LL/A): $899, $100 off MSRP – 13″ 1.8GHz/256GB MacBook Air (MQD42LL/A... Read more
12-inch MacBooks on sale for $100 off MSRP
Amazon has 2017 12″ Retina MacBooks on sale for $100 off MSRP. Shipping is free: 12″ 1.2GHz Space Gray MacBook: $1199.99 $100 off MSRP 12″ 1.2GHz Silver MacBook: $1198 $101 off MSRP 12″ 1.2GHz Gold... Read more

Jobs Board

*Apple* Customer Experience (ACE) Leader - A...
…management to deliver on business objectivesTraining partner store staff on Apple products, services, and merchandising guidelinesCoaching partner store staff on Read more
*Apple* Solutions Consultant (ASC) - Poole -...
Job Summary The people here at Apple don't just create products - they create the kind of wonder that's revolutionised entire industries. It's the diversity of those Read more
Business Development Manager, *Apple* iClou...
Job Summary Apple is seeking an entrepreneurial person to help grow the Apple iCloud business, a service that is integral to the Apple customer experience. Read more
Product Metrics Manager - *Apple* Media Pro...
Job Summary Apple is seeking a product manager responsible for overseeing the instrumentation and analysis of usage data, in order to make data driven product Read more
iOS Wallet & *Apple* Pay Engineer - App...
Job Summary The iOS Apple Pay & Wallet team is looking for talented, add credit and debit cards to Wallet using Apple Pay. You can use Apple Pay in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.