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: 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.

-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe function result.
-->ioCRefNumIntegerThe driver reference number.
-->csCodeIntegerAlways dspWrite for this function.
-->ccbRefNumIntegerThe CCB reference number.
-->reqCountIntegerThe requested number of bytes.
<--actCountIntegerThe actual number of bytes written.
-->dataPtrPtrA pointer to the data buffer.
-->eomByteFor ADSP: a flag indicating end of message. For ASDSP: a flag indicating end of
message or encryption.
-->flushByteA 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:

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.

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
noErr0No error
errState-1278Connection is not open
errAborted-1279Request aborted by dspRemove or dspClose routine
errRefNum-1280Bad connection reference number

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996