Legacy Document

Inside Macintosh: Networking /

Chapter 5 - AppleTalk Data Stream Protocol (ADSP) / ADSP Reference

Routines / Establishing and Terminating an ADSP Connection

dspOpen

The dspOpen routine opens a connection end. You can open a connection end in request mode, passive mode, accept mode, or establish mode. You use the PBControl function to call the dspOpen routine. See "Routines" on page 5-43 for a description of the PBControl function.

-->	ioCompletion	ProcPtr	A pointer to completion routine.
<--	ioResult	OSErr	The function result.
-->	ioCRefNum	Integer	The driver reference number.
-->	csCode	Integer	Always dspOpen for this function.
-->	ccbRefNum	Integer	The CCB reference number.
<--	localCID	Integer	The ID of this connection end.
<->	remoteCID	Integer	The ID of remote connection end.
<->	remoteAddress	AddrBlock	A remote internet address.
-->	filterAddress	AddrBlock	A filter for open-connection requests.
<->	sendSeq	LongInt	The initial send sequence number.
<->	sendWindow	Integer	The initial size of remote receive queue.
-->	recvSeq	LongInt	The initial receive sequence number.
<->	attnSendSeq	LongInt	The attention send sequence number.
-->	attnRecvSeq	LongInt	The attention receive sequence number.
-->	ocMode	Byte	The connection-opening mode.
-->	ocInterval	Byte	The interval between open requests.
-->	ocMaximum	Byte	The number of open-connection request retries.

The use of parameters by the dspOpen routine depends on the mode in which the routine is executed, as follows:

ocRequest		ocPassive		ocAccept		ocEstablish
-->	ioCompletion	-->	ioCompletion	-->	ioCompletion	-->	ioCompletion
<--	ioResult	<--	ioResult	<--	ioResult	<--	ioResult
-->	ioCRefNum	-->	ioCRefNum	-->	ioCRefNum	-->	ioCRefNum
-->	csCode	-->	csCode	-->	csCode	-->	csCode
-->	ccbRefNum	-->	ccbRefNum	-->	ccbRefNum	-->	ccbRefNum
<--	localCID	<--	localCID	<--	localCID	--	localCID
<--	remoteCID	<--	remoteCID	-->	remoteCID	-->	remoteCID
-->	remoteAddress	<--	remoteAddress	-->	remoteAddress	-->	remoteAddress
-->	filterAddress	-->	filterAddress	--	filterAddress	--	filterAddress
<--	sendSeq	<--	sendSeq	-->	sendSeq	-->	sendSeq
<--	sendWindow	<--	sendWindow	-->	sendWindow	-->	sendWindow
--	recvSeq	--	recvSeq	--	recvSeq	-->	recvSeq
<--	attnSendSeq	<--	attnSendSeq	-->	attnSendSeq	-->	attnSendSeq
--	attnRecvSeq	--	attnRecvSeq	--	attnRecvSeq	-->	attnRecvSeq
-->	ocMode	-->	ocMode	-->	ocMode	-->	ocMode
-->	ocInterval	-->	ocInterval	-->	ocInterval	--	ocInterval
-->	ocMaximum	-->	ocMaximum	-->	ocMaximum	--	ocMaximum
Key: --> input <-- output <-> input and output -- not used

Field Description

csCode

The routine selector, always equal to dspOpen for this routine.

ccbRefNum

The connection control block (CCB) reference number that was returned by the dspInit routine for the connection end that you want to use.

localCID

The identification number of the local connection end. This number is assigned by ADSP when you open the connection. ADSP includes this number in every packet sent to a remote connection end. Before you call the dspOpen routine in ocEstablish mode, you must call the dspNewCID routine to cause ADSP to assign this value.

remoteCID

The identification number of the remote connection end. This parameter is returned by the dspOpen routine in the ocRequest and ocPassive modes. A connection server must provide this number to the dspOpen routine when the server executes the routine in ocAccept mode; in this case, the connection server obtains the remoteCID value from the dspCLListen routine. You must provide the remoteCID value to the dspOpen routine when you use the routine in ocEstablish mode.

remoteAddress

The internet address of the remote socket with which you wish to establish communications. This address consists of a 2-byte network number, a 1-byte node ID, and a 1-byte socket number. You must provide this parameter when you call the dspOpen routine in the ocRequest or ocEstablish mode. This parameter is returned by the dspOpen routine when you call the routine in the ocPassive mode. When you call the dspOpen routine in the ocAccept mode, you must use the value for the remoteAddress parameter that was returned by the dspCLListen routine.

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 $00082500, for example, the connection end accepts a connection request from any socket at node $25 of network $0008. Set the filterAddress parameter equal to the remoteAddress parameter to accept a connection only with the socket to which you sent a connection request.

When you execute the dspOpen routine in the ocPassive mode, you can receive a connection request from any ADSP connection end on the internet. When you execute the dspOpen routine in the ocRequest mode, your connection end can receive a connection request acknowledgment from an address different from the one you specified in the remoteAddress parameter only if the remote address you specified was that of a connection listener. In either case, you can use the filterAddress parameter to avoid acknowl-
edging unwanted connection requests.

When you execute the dspOpen routine in the ocAccept mode, your connection listener has already received and decided to accept the connection request. You can specify a filter address for a connection listener with the dspCLListen routine. A connection server can use the dspCLDeny routine to deny a connection request that was accepted by its connection listener.

You cannot use the filter address when you execute the dspOpen routine in ocEstablish mode.

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. ADSP returns a value for the sendSeq parameter when you execute the dspOpen routine in the ocRequest or ocPassive mode. When you execute the dspOpen routine in the ocAccept mode, you must specify
the value for the sendSeq parameter that was returned by the dspCLListen routine. You must provide the value for this parameter when you execute the dspOpen routine in the ocEstablish mode.

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. ADSP returns
a value for the sendWindow parameter when you execute the dspOpen routine in the ocRequest or ocPassive mode. When you execute the dspOpen routine in the ocAccept mode, you must specify the value for the sendWindow parameter that was returned by the dspCLListen routine. You must provide the value for this parameter when you execute the dspOpen routine in the ocEstablish mode.

recvSeq

The sequence number of the next byte that the local connection
end expects to receive. ADSP uses this number to coordinate communications and to check for errors. You must provide the value for this parameter when you execute the dspOpen routine
in the ocEstablish mode. The dspOpen routine does not use
this parameter when you execute it in any other mode.

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. ADSP returns a value
for the attnSendSeq parameter when you execute the dspOpen routine in the ocRequest or ocPassive mode. When you execute the dspOpen routine in the ocAccept mode, you must specify
the value for the attnSendSeq parameter that was returned
by the dspCLListen routine. You must provide the value for
this parameter when you execute the dspOpen routine in the ocEstablish mode.

attnRecvSeq

The sequence number of the next attention packet that the local connection end expects to receive. ADSP uses this number to ensure that packets are delivered in the correct order and to check for errors. You must provide a value for this parameter when you execute the dspOpen routine in the ocEstablish mode. The dspOpen routine does not use this parameter when you execute it in any other mode.

ocMode

The mode in which the dspOpen routine is to operate, as follows:

	Mode	Value	Meaning
	ocRequest	1	ADSP attempts to open a connection with the socket you specify.
	ocPassive	2	The connection end waits to receive a connection request.
	ocAccept	3	The connection server accepts and acknowledges receipt of a connection request.
	ocEstablish	4	ADSP considers the connection established and open; you are responsible for setting up and synchronizing both connection ends.

ocInterval

The period between transmissions of open-connection requests.
If the remote connection end does not acknowledge or deny an open-connection request, ADSP retransmits the request after a
time period specified by this parameter. The time period used by ADSP is (ocInterval 10) ticks, or (ocInterval/6) seconds. For example, if you set the ocInterval parameter to 3, the time period between retransmissions is 30 ticks (1/2 second). You can set the ocInterval parameter to any value from 1 (1/6 second) to
180 (30 seconds). If you specify 0 for the ocInterval parameter, ADSP uses the default value of 6 (1 second).

You must provide a value for the ocInterval parameter when you execute the dspOpen routine in the ocRequest, ocPassive, or ocAccept mode. The dspOpen routine does not use this parameter when you execute it in the ocEstablish mode.

ocMaximum

The maximum number of times to retransmit an open-connection request before ADSP terminates execution of the dspOpen routine. If you specify 0 for the ocMaximum parameter, ADSP uses the default value of 3. If you specify 255 for the ocMaximum parameter, ADSP retransmits the open-connection request indefinitely until the remote connection end either acknowledges or denies the request.

You must provide a value for the ocMaximum parameter when you execute the dspOpen routine in the ocRequest, ocPassive, or ocAccept mode. The dspOpen routine does not use this parameter when you execute it in the ocEstablish mode.

DESCRIPTION

The dspOpen routine opens a connection end. You set the ocMode field of the parameter block to specify the opening mode that the dspOpen routine is to use. The dspOpen routine puts a connection end into one of the four following opening modes:

• The ocRequest mode, in which ADSP attempts to open a connection with the socket at the internet address you specify as the remoteAddress parameter. If the socket you specify as a remote address is a connection listener, it is possible that your application will receive a connection acknowledgment and request from a different address than the one to which you sent the open-connection request. You can use
  the filterAddress parameter to restrict the addresses with which you will accept
  a connection.

  The dspOpen routine completes execution in the ocRequest mode when one of the following occurs: ADSP establishes a connection, your connection end receives
  a connection denial from the remote connection end, your connection end denies the connection request returned by a connection listener, or ADSP cannot complete
  the connection within the maximum number of retries that you specified with the ocMaximum parameter.

• The ocPassive mode, in which the connection end waits to receive an open-
  connection request from a remote connection end. You can use the filterAddress parameter to restrict the addresses from which you will accept a connection request.

  The dspOpen routine completes execution in the ocPassive mode when ADSP establishes a connection or when either connection end receives a connection denial.

• The ocAccept mode, used by connection servers to complete an open-connection dialog. When a connection server is informed by its connection listener that the connection listener has received an open-connection request, the connection server calls the dspInit routine to establish a connection end and then calls the dspOpen routine in ocAccept mode to complete the connection. You must obtain the following parameters from the dspCLListen routine and provide them to the dspOpen routine: remoteAddress, remoteCID, sendSeq, sendWindow, and attnSendSeq. Connection listeners and connection servers are described in "Creating and Using a Connection Listener" beginning on page 5-22 and in "Establishing and Terminating an ADSP Connection" beginning on page 5-44. See "Connection Listeners" on page 5-7 for a brief introduction to connection listeners.

  The dspOpen routine completes execution in the ocAccept mode when ADSP establishes a connection or when either connection end receives a connection denial.

• The ocEstablish mode, in which ADSP considers the connection end established and the connection state open. This mode is for use by clients that determine their connection-opening parameters without using ADSP or the .DSP driver to do so.

  You must first use the dspInit routine to establish a connection end and then execute the dspNewCID routine to obtain an identification number (ID) for the
  local connection end. You must then communicate with the remote connection end
  to send it the local connection ID and to determine the values of the following parameters: remoteAddress, remoteCID, sendSeq, sendWindow, recvSeq, attnSendSeq, and attnRecvSeq. Only then can you execute the dspOpen routine in the ocEstablish mode.

  The dspOpen routine completes execution in the ocEstablish mode immediately.

ASSEMBLY-LANGUAGE INFORMATION

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

RESULT CODES

noErr	0	No error
errOpenDenied	-1273	Open request denied by recipient
errOpening	-1277	Attempt to open connection failed
errState	-1278	Connection end must be closed
errAborted	-1279	Request aborted by dspRemove or dspClose routine
errRefNum	-1280	Bad connection reference number