Legacy Document

Inside Macintosh: Networking /

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

Routines / Establishing and Terminating an ADSP Connection

dspInit

The dspInit routine establishes a connection end, that is, it assigns a specific socket for the ADSP connection end to use and initializes the variables that ADSP uses to maintain the connection. You use the PBControl function to call the dspInit routine. See "Routines" beginning on page 5-43 for a description of the PBControl function.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
-->	ioCRefNum	Integer	The driver reference number.
-->	csCode	Integer	Always dspInit for this function.
<--	ccbRefNum	Integer	The CCB reference number.
-->	ccbPtr	TPCCB	A pointer to the CCB.
-->	userRoutine	ProcPtr	A pointer to a routine to call on connection events.
-->	sendQSize	Integer	The size in bytes of the send queue.
-->	sendQueue	Ptr	A pointer to the send queue.
-->	recvQSize	Ptr	The size in bytes of the receive queue.
-->	recvQueue	Ptr	A pointer to the receive queue.
-->	attnPtr	Ptr	A pointer to the buffer for incoming attention messages.
<->	localSocket	Byte	The DDP socket number for this connection end.

Field Description

csCode

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

ccbRefNum

The connection control block (CCB) reference number. The dspInit routine returns the CCB reference number for this connection end
as the value of the ccbRefNum parameter. You must provide this number in all subsequent calls to this connection end.

ccbPtr

A pointer to the CCB that you allocated to be used by this connection end. The CCB is 242 bytes in size and is described in "The ADSP Connection Control Block Record" beginning on page 5-35. See also "Creating and Using a Connection Control Block" on page 5-12.

userRoutine

A pointer to a routine that ADSP is to call each time the connection end receives an unsolicited connection event. Specify NIL for this parameter if you do not want to supply a user routine. Connection events and user routines are discussed in "Writing a User Routine for Connection Events" beginning on page 5-26.

sendQSize

The size in bytes of the send queue. 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 the user's keystrokes, a smaller buffer should be adequate. The constant minDSPQueueSize indicates the minimum queue size that you can use.

sendQueue

A pointer to the send queue that you allocated.

recvQSize

The size in bytes of the receive queue. A queue size of 600 bytes should work well for most applications. If you are using ADSP to receive a continuous flow of data, a larger data buffer improves performance. If your application is receiving a user's keystrokes, a smaller buffer should be adequate. The constant minDSPQueueSize indicates the minimum queue size that you can use.

recvQueue

A pointer to the receive queue that you allocated.

attnPtr

A pointer to the attention-message buffer that you allocated. The attention-message buffer must be the size of the constant attnBufSize.

localSocket

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 this case, ADSP returns the socket number when the dspInit routine completes execution.

DESCRIPTION

The dspInit routine creates and initializes a connection end. The dspInit routine does not open the connection end or establish a connection with a remote connection end; you must follow the dspInit routine with the dspOpen routine to perform
those tasks.

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.

You must allocate memory for the send (sendQueue) and receive (recvQSize) queues and for a buffer (attnPtr) that holds incoming attention messages. You must also allocate a nonrelocatable block of memory (ccbPtr) for the CCB for this connection end.

SPECIAL CONSIDERATIONS

You must allocate nonrelocatable memory for the CCB, the send queue, the receive queue, and the attention-message buffer, and ensure that the memory remains locked until you explicitly remove the connection end by calling the dspRemove routine. Do not write any data to this memory except by calling ADSP routines.

ASSEMBLY-LANGUAGE INFORMATION

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

RESULT CODES

noErr	0	No error
ddpSktErr	-91	Error opening DDP socket
errDSPQueueSize	-1274	Send or receive queue is too small