Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 6 - Message Manager / Using the Message Manager

Setting and Getting Global Data for Multiple Handler Instances

You can use the SetMessageHandlerClassContext function to store data that can be used by multiple copies of your message handler in memory. This common data can be accessed by multiple print jobs and eliminates the need for storing redundant data. Listing 6-5 shows how to use the SetMessageHandlerClassContext function to store global data that can be used by multiple handler instances.

Listing 6-5 Storing global data for multiple handler instances

typedef struct MySharedDataRec {
   unsigned long  ownerCount;
   long           someData;
   long           someMoreData;
} MySharedDataRec, **MySharedDataHdl;

OSErr MyInitialize()
{
   OSErr             err = noErr;
   MySharedDataHdl   sharedDataHdl;

/*
   Retrieve the message handler's class context.  If the
   value returned is nil, the class context isn't set up.  In
   that case, create a new handle, initialize
   it, set its owner count to 1, and store it in our class
   context.
   
   If the class context has been set up, retrieve the data
   handle and increment its owner count.  (We will use the
   owner count in our gxShutDown message override.)
*/
   sharedDataHdl = (MySharedDataHdl)
               GetMessageHandlerClassContext();

   if (sharedDataHdl == nil)
   {
      sharedDataHdl = (MySharedDataHdl)
                  TempNewHandle(sizeof(MySharedDataRec), &err);
      if (!err)
      {
         MyInitSharedDataHandle(sharedDataHdl);
         (*sharedDataHdl)->ownerCount = 1;
         SetMessageHandlerClassContext(sharedDataHdl);
      }
   }
   else
      ++(*sharedDataHdl)->ownerCount;

   return err;
}

In contrast to the instance context that is always nil as you enter into an initialize routine, with the class context you can't assume that the context is nil. For example, you may be the third instance of this message handler. As a result, you need to test to see if the class context is already set up. If it is, you increment the owner count. If it isn't you se tup the context. This ensures that the class context is only set up once Listing 6-5 shows how to use the owner count to set up the class context. If the class context is not nil, then you increment the owner count. Otherwise, create the handle, set the owner count to 1, and store the class context.

You can use the GetMessageHandlerClassContext function to retrieve data that has been stored by the SetMessageHandlerClassContext function. Listing 6-6 shows how to retrieve a message handler's class context and use the information during shutdown.

Listing 6-6 Retrieving a message handler's class context

OSErr MyShutDown()
{
   MySharedDataHdl   sharedDataHdl;

/*
   Retrieve the message handler's class context.  If the
   value returned is nil, the class context isn't set up.
   Otherwise, decrement our data's owner count.
   If the owner count falls below 1, dispose of the
   actual data and set our class context to nil to
   "clear" it.
*/
   sharedDataHdl = (MySharedDataHdl)
               GetMessageHandlerClassContext();

   if (sharedDataHdl != nil)
   {
      if (--(*sharedDataHdl)->ownerCount < 1)
      {
         DisposHandle((Handle) sharedDataHdl);
         SetMessageHandlerClassContext(nil);
      }
   }

   return noErr;
}

In Listing 6-6, you use the GetMessageHandlerClassContext function to obtain and use the class context during shutdown. If the class context is not nil, you decrement the owner count. If the owner count is less than 1, there are no other owners and you may then dispose of the data. Using the owner count during shutdown prevents disposing of data more than once.

The SetMessageHandlerClassContext function is described on page 6-21. The GetMessageHandlerClassContext function is described on page 6-22.

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