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

dspWrite

The dspWrite routine writes bytes into a connection end's send queue for ADSP or ASDSP to transmit across a connection. When ASDSP is used and the encrypt bit is
set, ASDSP encrypts the data before sending it. You use the PBControl function to
call the dspWrite 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 dspWrite for this function.
-->	ccbRefNum	Integer	The CCB reference number.
-->	reqCount	Integer	The requested number of bytes.
<--	actCount	Integer	The actual number of bytes written.
-->	dataPtr	Ptr	A pointer to the data buffer.
-->	eom	Byte	For ADSP: a flag indicating end of message. For ASDSP: a flag indicating end of message or encryption.
-->	flush	Byte	A flag indicating whether to send buffered data.

Field Description

csCode

The routine selector, always dspWrite for this routine.

ccbRefNum

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

reqCount

The number of bytes to write.

actCount

The actual number of bytes written to the send queue.

dataPtr

A pointer to the buffer from which ADSP or ASDSP should read the data that is to be sent.

eom

For ADSP, a flag indicating if the last byte written to the send queue was a logical end-of-message indicator. If the last byte constitutes an EOM, you set this parameter to 1. If not, you set this parameter to 0. The high-order bits of the eom parameter are reserved for use by ADSP; you must leave these bits equal to 0.

For ASDSP, if this is a secure connection, this field constitutes two single-bit flags instead of a zero/nonzero byte. If set to 1, bit 0 indicates the end of message; if set to 1, bit 1 turns on encryption. Note that ASDSP checks this flag on the first write of the connection and the first write following a write for which the end-of-message flag (bit 0 of the eom field) is set.

flush

A flag indicting whether or not ADSP or ASDSP should immediately send the data in the send queue to the remote connection. Set flush to 1 to cause ADSP or ASDSP to immediately transmit any data in the send queue that has not already been transmitted. Set flush to 0 to allow data to accumulate in the send queue until another condition occurs that causes data to be transmitted. The high-order bits of the flush parameter are reserved for use by ADSP or ASDSP; you must leave these bits equal to 0.

DESCRIPTION

The dspWrite routine sends data across an ADSP or ASDSP connection. The send queue contains all data that has been sent to ADSP or ASDSP for transmission and that has not yet been acknowledged. Some of the data in the send queue might have already been transmitted, but ADSP or ASDSP retains it in the send queue until the remote connection end acknowledges its receipt in case the data has to be retransmitted. The dspWrite routine completes execution when it has copied all of the data from the data buffer into the send queue.

ADSP or ASDSP transmits the data in the send queue when the remote connection end has room to accept the data and one of the following conditions occurs:

• You call the dspWrite routine with the flush parameter set to a nonzero number.
• The number of bytes in the send queue equals or exceeds the blocking factor. (You use the sendBlocking parameter to the dspOptions routine to set the blocking factor.)
• The send timer expires.
• A connection event requires that the local connection end send an acknowledgment packet to the remote connection end.

For an ADSP dspWrite call, you can set the reqCount parameter to 0 and the eom parameter to 1 to indicate that the last byte you sent the previous time you called the dspWrite routine was the end of the message. You can set the reqCount parameter to a value larger than the size of the send queue. If you do so, the dspWrite routine writes as much data as it can into the send queue, sends the data and waits for acknowledg-
ment, and then writes more data into the send queue until it has written the amount of data you requested. In this case, the routine does not complete execution until it has finished writing all of the data into the send queue.

For an ASDSP dspWrite call, you can set the encrypt bit of the eom field (bit 1) of the DSP parameter block. Note that ASDSP checks this flag on the first write of the connec-
tion or the first write following a write for which the end-of-message flag (bit 0 of the eom field) is set. You can set the end-of-message bit (bit 0) of the eom field to indicate the end of the message.

• To set the encrypt bit, you use the dspEncryptMask mask or the
  dspEncryptBit constant.
• To set the end-of-message bit, you use the dspEOMMask mask or the
  dspEOMBit constant.

Set the flush parameter to 1 to cause ADSP to immediately transmit any data in the send queue that has not already been transmitted. Set the flush parameter to 0 to allow data to accumulate in the send queue until another condition occurs that causes data to be transmitted.

If you want to encrypt all messages, you can simply set the encrypt bit on all calls to the dspWrite function.

ASSEMBLY-LANGUAGE INFORMATION

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

RESULT CODES

noErr	0	No error
errState	-1278	Connection is not open
errAborted	-1279	Request aborted by dspRemove or dspClose routine
errRefNum	-1280	Bad connection reference number