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 other PPC Toolbox functions can execute asynchronously or synchronously. Here's an example:
The pb parameter should point to a PPC parameter block. The async
parameter is TRUE if the function is to be executed asynchronously. be executed asynchronously, because they require interaction from the other
application in the session before they complete execution.
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
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 in order 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 most common
high-level languages 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 pre serves the application global register A5.
You can write completion routines in C, Pascal, or assembly language. A
completion routine declared in Think C has this format:
Pascal void MyCompletionRoutine (PPCParam blockPtr pb);
The pb parameter points to the PPC parameter block passed to the
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
PPC Toolbox function from within a completion routine. For example, you 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:
#include <PPCToolbox.h>
typedef struct SessRec SessRec;
typedef SessRec *SessRecPtr;
typedef SessRecPtr *SessRecHndl;
struct SessRec
{
};
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.