Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Interapplication Communication /
Chapter 11 - Program-to-Program Communications Toolbox / PPC Toolbox Reference
PPC Toolbox Routines / Reading and Writing Data


PPCWrite

Use the PPCWrite function to write message blocks during a session.

FUNCTION PPCWrite (pb: PPCWritePBPtr; async: Boolean): OSErr;
pb
A pointer to a PPCWrite parameter block.
async
A value that specifies whether the function is to be executed asynchronously (TRUE) or synchronously (FALSE). You should execute the PPCWrite function asynchronously.
-->ioCompletionPPCCompProcPtrAddress of a completion routine
<--ioResultOSErrResult code
-->sessRefNumPPCSessRefNumSession reference number
-->bufferLengthSizeLength of data buffer
<--actualLengthSizeActual length of data written
-->bufferPtrPtrPointer to data buffer
-->moreBooleanTRUE if more data in this block to be written
-->userDataLongIntApplication-specific data
-->blockCreatorOSTypeCreator of block written
-->blockTypeOSTypeType of block written

DESCRIPTION
If your application calls the PPCWrite function asynchronously, you must specify in the ioCompletion field either the address of a completion routine or NIL. If you set ioCompletion to NIL, you should poll the ioResult field of the PPC parameter block (from your application's main event loop) to determine whether the PPC Toolbox has completed the requested operation. A value in the ioResult field other than 1 indicates that the call is complete. Note that it is unsafe to poll the ioResult field at interrupt time since the PPC Toolbox may be in the process of completing a call. See "PPC Toolbox Calling Conventions" beginning on page 11-14.

If you call the PPCWrite function asynchronously, you must not change any of the fields in the parameter block until the call completes. The buffer pointed to by the record of data type PPCWritePBRec is owned by the PPC Toolbox until the call completes. These objects must not be deallocated or moved in memory while the call is in progress.

The sessRefNum field specifies a session identifier. This must be a valid session reference number returned from a previous PPCStart, StartSecureSession, or PPCInform function.

The bufferLength and bufferPtr fields specify the length and location of a buffer the message block is sent to. If the PPCWrite function returns a noErr result code, the actualLength field returns the actual size of the message block that was written.

Set the more field to TRUE to indicate that you will be using the PPCWrite function again to append data to this message block. Set the more field to FALSE to indicate that this is the end of the data in this message block.

The initiating port can specify any information in the userData field. The PPCRead function reports this data to the responding port upon its completion.

Set the userData, blockCreator, and blockType fields for each message block that you create. These fields can give the receiving application information about how to process the contents of the message block. They are ignored when you append information to a message block.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the PPCWrite function are
Trap macroSelector
_PPC$0006

The registers on entry and exit for this routine are
Registers on entry
A0Pointer to a parameter block
D0Selector code
Registers on exit
D0Result code

RESULT CODES
noErr0No error
notInitErr-900PPC Toolbox has not been initialized yet
noGlobalsErr-904System unable to allocate memory, critical error
noSessionErr-908Invalid session reference number
badReqErr-909Bad parameter or invalid state for this operation
sessClosedErr-917The session has closed
SEE ALSO
For an example of the use of the PPCWrite function in conjunction with the PPCRead function, see "Exchanging Data During a PPC Session" beginning on page 11-39.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996