Important: The information in this document is obsolete and should not be used for new development.
dspWrite
ThedspWrite
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 thePBControl
function to
call thedspWrite
routine. See "Routines" on page 5-43 for a description of thePBControl
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. Setflush
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 theflush
parameter are reserved for use by ADSP or ASDSP; you must leave these bits equal to 0.DESCRIPTION
ThedspWrite
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. ThedspWrite
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
- 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 thedspOptions
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.
dspWrite
call, you can set thereqCount
parameter to 0 and theeom
parameter to 1 to indicate that the last byte you sent the previous time you called thedspWrite
routine was the end of the message. You can set thereqCount
parameter to a value larger than the size of the send queue. If you do so, thedspWrite
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 theeom
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 theeom
field) is set. You can set the end-of-message bit (bit 0) of theeom
field to indicate the end of the message.
Set the
- To set the encrypt bit, you use the
dspEncryptMask
mask or thedspEncryptBit
constant.- To set the end-of-message bit, you use the
dspEOMMask
mask or thedspEOMBit
constant.
flush
parameter to 1 to cause ADSP to immediately transmit any data in the send queue that has not already been transmitted. Set theflush
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 thedspWrite
routine from assembly language, call the_Control
trap macro with a value ofdspWrite
in thecsCode
field of the parameter block.RESULT CODES
noErr 0 No error errState -1278 Connection is not open errAborted -1279 Request aborted by dspRemove
ordspClose
routineerrRefNum -1280 Bad connection reference number