Opening and Maintaining an ADSP Connection
between a socket on your local node and a remote socket, use the following
procedure:
OpenDriver function is used to return the reference number for 2. Allocate nonrelocatable memory for a connection control block
(CCB), send and receive queues, and an attention-message buffer. If you need to allocate the memory dynamically while the program is
running, use the NewPtr routine. Otherwise, the way in which you
allocate the memory depends on the compiler you are using. (The code
example at the end of this section shows how it's done in C.) The
memory that you allocate becomes the property of ADSP when you call
the dspInit routine to establish a connection end. You cannot write any
data to this memory except by calling ADSP, and you must ensure that
the memory remains locked until you call the dspRemove routine to
eliminate the connection end.
The CCB is 242 bytes. The attention-message buffer must be 570 bytes. When you send bytes to a remote connection end, ADSP stores
the bytes in a buffer called the send queue. Until the remote connection
end acknowledges their receipt, ADSP keeps the bytes you sent in the
send queue so that they are available to be retransmitted if necessary.
When the local connection end receives bytes, it stores them in a buffer,
called the receive queue, until you read them. The sizes you need for
the send and receive queues depend on the lengths of the messages being
sent.
ADSP does not transmit data from the remote connection end until
there is room for it in your receive queue. If your send or receive
queues are too small, they limit the speed with which you can transmit
and receive data. A queue size of 600 bytes should work well for most
applications. If you are using ADSP to send a continuous flow of data, a
larger data buffer improves performance. If your application is
sending or receiving the user's keystrokes, a smaller buffer should be
adequate. The constant minDSPQueueSize indicates the minimum queue
size that you can use.
you must allocate send and receive queues that are 12 percent larger
than the actual buffer sizes you need. You must do this in order to
variable, portion of the buffer space for their overhead.
qFlags field, which is the first field in the dCtlQHdr field in the
driver's device control entry (DCE) data structure. Version 1.5 of
3.Use the dspInit routine to establish a connection end. You must
provide pointers to the CCB, send queue, receive queue, and attention-message buffer. You may also provide a pointer to the user
routine that ADSP calls when your connection end receives an
unsolicited connection event. User routines are discussed in the section
If there is a specific socket that you want to use for the connection
end, you can specify the socket number in the localSocket parameter. If
you want ADSP to assign the socket for you, specify 0 for the
localSocket parameter. ADSP returns the socket number when the
dspInit routine completes execution.
4. If you wish, you can use the NBPRegister function to add the name and address of your connection end to the node's names table (see
5. You can use the dspOptions routine to set several parameters that
control the behavior of the connection end. Because every parameter
has a default value, the use of the dspOptions routine is optional. You
can specify values for the following parameters:
• The sendBlocking parameter, which sets the maximum number of
bytes that may accumulate in the send queue before ADSP sends a
packet to the remote connection end. You can experiment with different
values of the sendBlocking parameter to determine which provides the
best performance. Under most circumstances, the default value of 16
bytes gives good performance.
• The badSeqMax parameter, which sets the maximum number of
out-of-sequence data packets that the local connection end can receive
before requesting the remote connection end to retransmit the missing
data. Under most circumstances, the default value of 3 provides good
performance.
• The useCheckSum parameter, which determines whether the
Datagram Delivery Protocol (DDP) should compute a checksum and
include it in each packet that it sends to the remote connection end.
Using checksums slows communications slightly. Normally ADSP and
DDP perform enough error checking to ensure safe delivery of all data.
Set the useCheckSum parameter to 1 only if you feel that the network is
highly unreliable.
6. Call the dspOpen routine to open the connection. The dspOpen
routine has four possible modes of operation: ocAccept, ocEstablish,
ocRequest, and ocPassive. Normally you use either the ocRequest or
ocPassive mode. You must specify one of these four modes for the
ocMode parameter when you call the dspOpen routine.
The ocAccept mode is used only by connection servers. The ocEstablish
mode is used by routines that determine their connection-opening
parameters and establish a connection independently of ADSP, but use
ADSP to transmit and receive data.
Use the ocRequest mode when you want to establish communications
with a specific socket on the internet. When you execute the dspOpen
routine in the ocRequest mode, ADSP sends an open-connection request
to the address you specify.
If the socket to which you send the open-connection request is a
connection listener, the connection server that operates that connection
listener can choose any socket on the internet to be the connection end
that responds to the open-connection request. To restrict the socket
from which you will accept a response to your open- connection
request, specify a value for the filterAddress parameter to the dspOpen
routine. When your connection end receives a response from a socket
that meets the restrictions of the filterAddress parameter, it
acknowledges the response and ADSP completes the connection.
To use the ocRequest mode, you must know the complete internet
address of the remote socket, and the ADSP client at that address must
either be a connection listener or have executed the dspOpen routine in
the ocPassive mode. You can use the PLookupName function to obtain a list of names of objects on the internet and to determine the internet
address of a socket when you know its name. The PLookupName function is the preferred interface version of the NBPLookup function. Enhancements to the wild-card-lookup feature of the
Name-Binding Protocol (NBP) are discussed in A New NBP
Use the ocPassive mode when you expect to receive an open- connection
request from a remote socket. You can specify a value for the
filterAddress parameter to restrict the network number, node ID, or
socket number from which you will accept an open-connection request.
When your connection end receives an open-connection request that
meets the restrictions of the filterAddress parameter, it acknowledges
the request and ADSP completes the connection.
You can poll the state field in the CCB to determine when the connection end is waiting to receive an open-connection request, when
the connection end is waiting to receive an acknowledgment of an
open-connection request, and when the connection is open. (see,
result code for the dspOpen routine when the routine completes
execution. If the routine returns the noErr result code, then the
connection is open.
7. Use the dspRead routine to read data that your connection end has
received from the remote connection end. Use the dspWrite routine to
send data to the remote connection end. Use the dspAttention routine to
send attention messages to the remote connection end.
The dspWrite routine places data in the send queue. ADSP is a full-duplex, symmetric communications protocol. You can send data at
any time, and your connection end can receive data at any time, even at
the same time as you are sending data. ADSP transmits the data in the
send queue when 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 that you set with the dspOptions routine.
• The send timer expires. The send timer sets the maximum amount of
time that can pass before ADSP sends all unsent data in the send queue
to the remote connection end. ADSP calculates the best value to use for
this timer and sets it automatically.
• A connection event requires that the local connection end send an
acknowledgment packet to the remote connection end.
If you send more data to the send queue than it can hold, the dspWrite
routine does not complete execution until it has written all the data to
the send queue. If you execute the dspWrite routine asynchronously,
ADSP returns control to your program and writes the data to the send
queue as quickly as it can. This technique provides the most efficient
use of the send queue by your program and by ADSP. Because ADSP
does not remove data from the send queue until that data has not only
been sent but also acknowledged by the remote connection end, using the
flush parameter to the dspWrite routine does not guarantee that the
send queue is empty. You can use the dspStatus routine to determine
how much free buffer space is available in the send queue.
The dspRead routine reads data from the receive queue into your application's private data buffer. ADSP does not transmit data until
there is space available in the other end's receive queue to accept it.
Because a full receive queue slows the communications rate, you should
read data from the receive queue as often as necessary to keep sufficient
buffer space available for new data. You can use either of two
techniques to do this:
• allocate a small receive queue (about 600 bytes) and call the
dspRead routine asynchronously. Your completion routine for the
dspRead routine should then call the dspRead routine again.
• allocate a large receive queue and call the dspRead routine less
frequently.
If there is less data in the receive queue than the amount you specify
with the reqCount parameter to the dspRead command, the command does
not complete execution until there is enough data available to satisfy
the request. There are three exceptions to this rule:
• If the end-of-message bit in the ADSP packet header is set, the
dspRead command reads the data in the receive queue, returns the