Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 11 - Program-to-Program Communications Toolbox / PPC Toolbox Reference

PPC Toolbox Routines / Reading and Writing Data

PPCRead

Use the PPCRead function to read message blocks during a session.

FUNCTION PPCRead (pb: PPCReadPBPtr; async: Boolean): OSErr;

pb

A pointer to a PPCRead parameter block.

async

A value that specifies whether the function is to be executed asynchronously (TRUE) or synchronously (FALSE). You should execute the PPCRead function asynchronously.

-->	ioCompletion	PPCCompProcPtr	Address of a completion routine
<--	ioResult	OSErr	Result code
-->	sessRefNum	PPCSessRefNum	Session reference number
-->	bufferLength	Size	Length of data buffer
<--	actualLength	Size	Actual length of data read
-->	bufferPtr	Ptr	Pointer to data buffer
<--	more	Boolean	TRUE if more data in this block to be read
<--	userData	LongInt	Application-specific data
<--	blockCreator	OSType	Creator of block read
<--	blockType	OSType	Type of block read

DESCRIPTION

If your application calls the PPCRead 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 for detailed information.

If you call the PPCRead 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 PPCReadPBRec 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 to read data from. 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 will be read into. Your application must allocate the storage for the buffer. The actualLength field returns the actual size of the data read into your data buffer.

The more field returns TRUE if the provided buffer cannot hold the remainder of the message block. Your application may read a message block in several pieces. It is not necessary to have a buffer large enough to read in the entire message block, so a message block can span multiple calls to the PPCRead function.

Upon completion of the PPCRead function, the userData, blockCreator, and blockType fields contain information regarding the contents of the message block. You specify these fields using the PPCWrite function.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the PPCRead function are

Trap macro	Selector
_PPC	$0007

The registers on entry and exit for this routine are

Registers on entry
A0	Pointer to a parameter block
D0	Selector code

Registers on exit
D0	Result code

RESULT CODES

noErr	0	No error
notInitErr	-900	PPC Toolbox has not been initialized yet
noGlobalsErr	-904	System unable to allocate memory, critical error
noSessionErr	-908	Invalid session reference number
badReqErr	-909	Bad parameter or invalid state for this operation
sessClosedErr	-917	The session has closed

SEE ALSO

For an example of the use of the PPCRead function in conjunction with the PPCWrite function, see "Exchanging Data During a PPC Session" beginning on page 11-39.