Legacy Document

Inside Macintosh: Networking /

Chapter 5 - AppleTalk Data Stream Protocol (ADSP) / ADSP Reference

Routines / Maintaining an ADSP Connection and Using It to Exchange Data

dspRead

The dspRead routine reads data from a connection end's receive queue and writes the data to a buffer that you specify. You use the PBControl function to call the dspRead routine. See "Routines" on page 5-43 for a description of the PBControl function.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
-->	ioCRefNum	Integer	The driver reference number.
-->	csCode	Integer	Always dspRead for this function.
-->	ccbRefNum	Integer	The CCB reference number.
-->	reqCount	Integer	The requested number of bytes.
<--	actCount	Integer	The actual number of bytes read.
-->	dataPtr	Ptr	A pointer to the data buffer.
<--	eom	Byte	A flag indicating the end of message.

Field Description

csCode

The routine selector, always dspRead for this routine.

ccbRefNum

The connection control block (CCB) reference number that the dspInit routine returned.

reqCount

The number of bytes that ADSP is to read.

actCount

The actual number of bytes that ADSP read.

dataPtr

A pointer to the buffer into which ADSP is to place the data.

eom

A flag indicating if the last byte that ADSP read was a logical end-of-message indicator. If the last byte constitutes an EOM,
ADSP sets this parameter to 1. If not, it sets this parameter to 0.

DESCRIPTION

The dspRead routine reads data from an ADSP connection. You can continue to read bytes as long as data is in the receive queue, even after you have called the dspClose routine or after the remote connection end has called the dspClose or dspRemove routine. The dspRead routine completes execution when it has read the number of
bytes you specify or when it encounters an end of message (that is, the last byte
of data in an ADSP packet that has the EOM bit set in the packet header).

You can call the dspStatus routine to determine the number of bytes remaining to be read from the read queue, or you can continue to call the dspRead routine until the actCount and eom parameters both return 0.

If either end closes the connection before you call the dspRead routine, the command reads whatever data is available and returns the actual amount of data read in the actCount parameter. If the connection is closed and there is no data in the receive queue, the dspRead routine returns the noErr result code with the actCount parameter set to 0 and the eom parameter set to 0.

ASSEMBLY-LANGUAGE INFORMATION

To execute the dspRead routine from assembly language, call the _Control trap macro with a value of dspRead in the csCode field of the parameter block.

RESULT CODES

noErr	0	No error
errFwdReset	-1275	Read terminated by forward reset
errState	-1278	State isn't open, closing, or closed
errAborted	-1279	Request aborted by dspRemove or dspClose routine
errRefNum	-1280	Bad connection reference number