Connection Listener Setup
A connection listener is a special kind of connection end that listens for
open-connection requests from remote connection ends. Connection listeners
are used by connection servers-that is, programs that assign a socket for
the local connection end only after they receive a connection request from a
remote connection end. A single connection listener can receive connection
requests from any number of remote connection ends.
You can use the routines in this section to
• establish a connection listener
• cause the connection listener to wait for a connection request
• deny a connection request
• close and eliminate a connection listener
in this section.
function, as follows:
ParmBlkPtr thePBptr; address of a parameter block structure Boolean async; 0=await completion; 1=immediate return thePBptr is a pointer to the parameter block used by the PBControl function for .DSP routines
async is a Boolean that specifies whether the function is to execute
synchronously or asynchronously. Set the async parameter to TRUE
to execute the function asynchronously.
The parameter block is shown in the DSPParamBlock . The parameters used with each function are described in this section.
For a general discussion of the use of ADSP, see Using ADSP in the section
Parameter block
¨ ioResult short 2 16 Result code
Æ ioCRefNum short 2 24 Driver reference number
Æ csCode short 2 26 Always dspCLInit
¨ ccbRefNum short 2 32 Reference number of CCB Æ ccbPtr long 4 34 Pointer to CCB ´ localSocket char 1 58 Local DDP socket number
The dspCLInit routine establishes a connection listener; that is, it assigns a
specific socket for use by ADSP and initializes the variables that ADSP uses
to maintain a connection listener. The dspCLInit routine does not cause the
connection listener to listen for connection requests; you must follow the
dspCLInit routine with the dspCLListen routine to activate the connection
listener. Use the dspInit routine to establish a connection end that is not a
connection listener. Use the dspCLRemove routine to eliminate a connection
listener.
The ioResult parameter returns the result of the routine. If you call the
routine asynchronously, the routine sets this field to 1 as soon as it begins
execution, and it changes the field to the actual result code when it completes
execution. The ioCRefNum parameter is the driver reference number returned
by the OpenDriver function. You must specify this number every time you dspCLInit for this routine. The dspCLInit routine returns the ccbRefNum
parameter, which is the CCB reference number. You must provide this number in all subsequent dspCLListen and dspCLRemove calls to this connection
listener.
You must allocate memory for a CCB before you call the dspCLInit routine. The ccbPtr parameter is a pointer to the CCB that you allocated. The CCB is parameter is the DDP socket number of the socket that you want ADSP to use
for this connection end. Specify 0 for this parameter to cause ADSP to assign
the socket. In the latter case, ADSP returns the socket number when the
dspCLInit routine completes execution.
Result codes
noErr (0) No error
ddpSktErr (-91) Error opening socket
dspCLListen
Parameter block
¨ ioResult short 2 16 Result code
Æ ioCRefNum short 2 24 Driver reference number
Æ csCode short 2 26 Always dspCLListen
Æ ccbRefNum short 2 32 Reference number of CCB ¨ remoteCID short 2 36 ID of remote connection end
¨ remoteAddress long 4 38 Remote internet address
Æ filterAddress long 4 42 Filter for open-connection requests
¨ sendSeq long 4 46 Initial send sequence number
¨ sendWindow short 2 50 Initial size of remote receive queue
¨ attnSendSeq long 4 56 Attention send sequence number
The dspCLListen routine causes a connection listener to listen for connection
requests. You must have already used the dspCLInit routine to establish a
connection listener before using the dspCLListen routine. The dspCLListen
routine is used only by connection servers.
When ADSP receives an open-connection request from a socket that satisfies the address requirements of the filterAddress parameter, it returns values for
the remoteCID, remoteAddress, sendSeq, sendWindow, and attnSendSeq
parameters and completes execution of the dspCLListen routine. You must then
either accept the open-connection request by calling the dspOpen routine in the
ocAccept mode or deny the request by calling the dspCLDeny routine.
You can call the dspCLListen routine several times, specifying the same
connection listener. For example, if you wanted to accept connections from any
or all of three different addresses, you could call the dspCLListen routine three
times with a different value for the filterAddress parameter each time. Note
that you must execute the dspCLListen routine asynchronously to take
advantage of this feature.
Field descriptions
ioResult The result of the routine. When you execute the routine
asynchronously, the routine sets this parameter to 1 and returns a
routine result of noErr as soon as the routine begins execution.
When the routine completes execution, it sets the ioResult
parameter to the actual result code.
ioCRefNum The driver reference number. This parameter is returned by the
OpenDriver function You must specify this number every time csCode The routine selector, always dspCLListen for this routine.
ccbRefNum The CCB reference number that was returned by the dspCLInit routine.
remoteCID The identification number of the remote connection end. You must
pass this value to the dspOpen routine when you open the connection
or to the dspCLDeny routine when you deny the connection request.
remoteAddress The internet address of the remote socket that sent a request to
open a connection. This address consists of a 2-byte network
number, a 1-byte node ID, and a 1-byte socket number. You must
pass this value to the dspOpen routine when you open the connection
or to the dspCLDeny routine when you deny the connection request.
filterAddress The internet address of the socket from which you will accept a
connection request. The address consists of three fields: a 2-byte
network number, a 1-byte node ID, and a 1-byte socket number.
Specify 0 for any of these fields for which you wish to impose no
restrictions. If you specify a filter address of 0x000082500, for
example, the connection listener accepts a connection request from
any socket at node 0x025 of network 0x00008.
sendSeq The sequence number of the first byte that the local connection end
will send to the remote connection end. ADSP uses this number to
coordinate communications and to check for errors. You must pass
this value to the dspOpen routine when you open the connection.
SendWindow The sequence number of the last byte that the remote connection
end has buffer space to receive. ADSP uses this number to
coordinate communications and to check for errors. You must pass
this value to the dspOpen routine when you open the connection.
attnSendSeq The sequence number of the next attention packet that the local
connection end will transmit. ADSP uses this number to coordinate
communications and to check for errors. You must pass this value
to the dspOpen routine when you open the connection.
Result codes
noErr (0) No error
errState (-1278) Not a connection listener
errAborted (-1279) Request aborted by the dspRemove routine
errRefNum (-1280) Bad connection reference number
dspCLDeny
Parameter block
¨ ioResult short 2 16 result code
Æ ioCRefNum short 2 24 driver reference number
Æ csCode short 2 26 always dspCLDeny
Æ ccbRefNum short 2 32 reference number of CCB Æ remoteCID short 2 36 ID of remote connection end
Æ remoteAddress long 4 38 remote internet address
The dspCLDeny routine is used by a connection server to inform a remote
connection end that its request to open a connection cannot be honored.
The ioResult parameter returns the result of the routine. If you call the
routine asynchronously, the routine sets this field to 1 as soon as it begins
execution, and it changes the field to the actual result code when it completes
execution. The ioCRefNum parameter is the driver reference number returned
by the OpenDriver function You must specify this number every time you always dspCLDeny for this routine. The ccbRefNum parameter is the CCB reference number for the connection listener that received the connection
request. This number is returned by the dspCLInit routine when you establish
a connection listener. The remoteCID and remoteAddress parameters specify
the address and ID of the remote connection end. These parameters are
returned by the dspCLListen routine.
Result codes
noErr (0) No error
errState (-1278) Not a connection listener
errAborted (-1279) Request aborted by the dspRemove routine
errRefNum (-1280) Bad connection reference number
dspCLRemove
Parameter block
¨ ioResult short 2 16 Result code
Æ ioCRefnum short 2 24 Io driver reference number
Æ csCode short 2 26 Always dspCLRemove
Æ ccbRefNum short 2 32 Reference number ofCCB Æ abort char 1 34 Abort connection listener if not 0
The dspCLRemove routine closes a connection end used as a connection
listener. You can release the memory you allocated for the CCB if you do not
intend to reopen the connection end.
The ioResult parameter returns the result of the routine. If you call the
routine asynchronously, the routine sets this field to 1 as soon as it begins
execution, and it changes the field to the actual result code when it completes
execution. The ioCRefNum parameter is the driver reference number returned
by the OpenDriver function. You must specify this number every time you dspCLRemove for this routine. The ccbRefNum parameter is the CCB reference number that was returned by the dspCLInit routine. If the abort parameter is
nonzero, ADSP cancels any outstanding requests to send pockets (such as the
dspCLDeny routine).
Result codes
noErr (0) No error
errRefNum (-1280) Bad connection reference number