Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 6 - Message Manager / Using the Message Manager

Setting and Getting Global Data for a Single Handler Instance

You can use the SetMessageHandlerInstanceContext function to store data that can be used by a single instance of a message handler. A new instance of your message handler is created each time a new printing job is created. For example, if four printing jobs are created, four instances of the message handler are created. Each job has a unique context called the instance context.

Listing 6-3 uses this function to store global data whenever a new printing job is initiated. If there are multiple print jobs, this function will be called when each job is started.

Listing 6-3 Storing global data for a single message handler instance

typedef struct MyDataRec {
   long something;
   long somethingElse;
} MyDataRec, **MyDataHdl;

OSErr MyInitialize()
{
   OSErr       err;
   MyDataHdl   dataHandle;

/*
   Create a new temporary memory handle, initialize
   it, and store it as the message handler's instance
   context.
*/
   dataHandle = (MyDataHdl) TempNewHandle(sizeof(MyDataRec),
                                                 &err);

   if (err == noErr)
   {
      MyInitDataHandle(dataHandle);
      SetMessageHandlerInstanceContext(dataHandle);
   }

   return err;
}

In Listing 6-3, you begin by creating a handle to store global data for the MyDataRec structure. Each message handler instance has a unique copy with unique values for the fields of the data structure. If there is insufficient memory to create the handle, an error will be generated. If the handler is successfully created, the handler is initialized. The SetMessageHandlerInstanceContext function is then used to store a reference to the handle that can then be used by this message handler's overrides. If you use this code in an extension and four jobs were created for it, each job would have a handle to a unique copy of a record for the structure.

You can use the GetMessageHandlerInstanceContext function to retrieve the data that you stored with the SetMessageHandlerInstanceContext function. Listing 6-4 uses the GetMessageHandlerInstanceContext function to return and dispose of the handle containing the global data that was previously stored in Listing 6-3.

Listing 6-4 Getting and disposing of global data

OSErr MyShutDown()
{
   MyDataHdl dataHandle;

/*
   Retrieve the message handler's instance context.  If the
   value returned isn't nil, it's a handle that we stored
   earlier. Dispose of the handle and set the instance
   context to nil to "clear" it.
*/
   dataHandle = (MyDataHdl) GetMessageHandlerInstanceContext();

   if (dataHandle != nil)
   {
      DisposHandle((Handle) dataHandle);
      SetMessageHandlerInstanceContext(nil);
   }

   return noErr;
}

In Listing 6-4, the GetMessageHandlerInstanceContext function is used to get the previously stored handle containing the global data. If the handle isn't nil, it's the handle that was previously stored and it is disposed of. Finally, the SetMessageHandlerInstanceContext function is used to set the context data to nil. If the instance context is nil, the handle was previously disposed of.

The SetMessageHandlerInstanceContext function is described on page 6-19. The GetMessageHandlerInstanceContext function is described on page 6-20.

Global data is discussed in the section "Global Data Storage for Printing Extensions and Printer Drivers" beginning on page 6-7.