Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 11 - Program-to-Program Communications Toolbox / Using the PPC Toolbox

PPC Toolbox Calling Conventions

Most PPC Toolbox functions can execute synchronously (meaning that the application cannot continue until the function completes execution) or asynchronously (meaning that the application is free to perform other tasks while the function is executing). The PPC Toolbox functions that can only be executed synchronously include PPCInit, PPCBrowser, StartSecureSession, DeleteUserIdentity, and GetDefaultUser. All other PPC Toolbox functions can execute asynchronously or synchronously. Here's an example:

FUNCTION PPCFunction (pb: PPCParamBlockPtr; 
                      async: Boolean): OSErr;

The pb parameter should point to a PPC parameter block. Set the async parameter to TRUE if you want the function to execute asynchronously; set it to FALSE if you want the function to execute synchronously.

Note

The PPCInform, PPCRead, and PPCWrite functions should always be executed asynchronously, because they require interaction from the other application in the session before they complete execution.

The PPCParamBlockRec data type defines the PPC parameter block.

TYPE PPCParamBlockRec = 
   RECORD
      CASE Integer OF
      0: (openParam:       PPCOpenPBRec);       {PPCOpen params}
      1: (informParam:     PPCInformPBRec);     {PPCInform params}
      2: (startParam:      PPCStartPBRec);      {PPCStart params}
      3: (acceptParam:     PPCAcceptPBRec);     {PPCAccept params}
      4: (rejectParam:     PPCRejectPBRec);     {PPCReject params}
      5: (writeParam:      PPCWritePBRec);      {PPCWrite params}
      6: (readParam:       PPCReadPBRec);       {PPCRead params}
      7: (endParam:        PPCEndPBRec);        {PPCEnd params}
      8: (closeParam:      PPCClosePBRec);      {PPCClose params}
      9: (listPortsParam:  IPCListPortsPBRec);  {IPCListPorts }
                                                { params}
   END;

For an illustration of the fields of each individual parameter block (such as PPCInformPBRec or IPCListPortsPBRec), see Figure 11-18 on page 11-47.

Your application transfers ownership of the PPC parameter block (and any buffers or records pointed to by the PPC parameter block) to the PPC Toolbox until a PPC function completes execution. Once the function completes, ownership of the parameter block (and any buffers or records it points to) is transferred back to your application. If a PPC Toolbox function is executed asynchronously, your program cannot alter memory that might be used by the PPC Toolbox until that function completes.

A PPC Toolbox function that is executed asynchronously must specify NIL or the address of a completion routine in the ioCompletion field of the PPC parameter block. You should use the ioResult field to determine the actual result code when an asynchronously executed PPC Toolbox function completes.

If you specify NIL in the ioCompletion field, you should poll the ioResult field of the PPC parameter block after the function is called to determine whether the PPC function has completed the requested operation. You should poll the ioResult field within the event loop of your application. If the ioResult field contains a value other than 1, the function has completed execution. Note that you must not poll the ioResult field at interrupt time to determine whether the function has completed execution.

If you specify a completion routine in the ioCompletion field, it is called at interrupt time when the PPC Toolbox function completes execution.

WARNING

Completion routines execute at the interrupt level and must preserve all registers other than A0, A1, and D0-D2. (Note that MPW C and MPW Pascal do this automatically.) Your completion routine must not make any calls to the Memory Manager directly or indirectly, and it can't depend on the validity of handles to unlocked blocks. The PPC Toolbox preserves the application global register A5.

You can write completion routines in C, Pascal, or assembly language. A completion routine declared in Pascal has this format:

PROCEDURE MyCompletionRoutine (pb: PPCParamBlockPtr);

The pb parameter points to the PPC parameter block passed to the PPC Toolbox function.

You may call another PPC Toolbox function from within a completion routine, but the function called must be executed asynchronously. It is recommended that you allocate parameter blocks of data type PPCParamBlockRec so that you may reuse the pb parameter to call another PPC Toolbox function from within a completion routine. For example, you should call either the PPCAccept function or the PPCReject function asynchronously from within a PPCInform completion routine to accept or reject the session request.

If your application is executing PPC Toolbox functions asynchronously, you may want to define your own record type to hold all data associated with a session. You can attach the data to the end of the parameter block. Here's an example:

TYPE 
   SessRecHndl = ^SessRecPtr;
   SessRecPtr = ^SessRec;
   SessRec = 
   RECORD
      pb:                  PPCParamBlockRec; {must be first }
                                             { item in record}
      thePPCPortRec:       PPCPortRec;
      theLocationNameRec:  LocationNameRec;
      theUserName:         Str32;
   END;

The additional data elements in your record can be accessed during execution of a completion routine by coercing the pb parameter to a pointer to your record type.