Legacy Document

Inside Macintosh: Networking /

Chapter 7 - Datagram Delivery Protocol (DDP) / DDP Reference

Routines / Opening and Closing DDP Sockets

POpenSkt

The POpenSkt function opens a socket for your application to use, and it adds that socket to the socket table along with a pointer to the socket listener that you provide.

FUNCTION POpenSkt (thePBptr: MPPPBPtr; async: Boolean): OSErr;

thePBptr

A pointer to an MPP parameter block.

async

A Boolean that specifies whether or not the function should be executed asynchronously. Specify TRUE for asynchronous execution.

-->	ioCompletion	ProcPtr	A pointer to completion routine.
<--	ioResult	OSErr	The result code.
-->	csCode	Integer	Always openSkt for this function.
<->	socket	Byte	The socket number.
-->	listener	Ptr	A pointer to socket listener.

Field Description

socket

The number of the socket you wish to open. Specify 0 for this field to have DDP assign a socket number in the range 128 through 254 and return it in this field. Socket numbers 1 through 63 are reserved for use by Apple Computer, Inc. You can use socket numbers 64 through 127 for this field during program development; however, it is recommended that you not use these numbers in a commercial product as there is no mechanism for resolving conflicts in the case that someone else uses the same socket number.

listener

Pointer to a socket listener that you provide. You cannot specify NIL for this field. See "A Sample Socket Listener" beginning on page 7-20 for information on writing a socket listener.

DESCRIPTION

The POpenSkt function opens a DDP socket and associates that socket with the
socket listener whose pointer you specify. If you specify 0 for the socket field, DDP dynamically assigns a socket, which it opens, and DDP returns the number of that
socket to you.

Alternatively, you can specify a socket number as the value of the socket field. The POpenSkt function returns a result code of ddpSktErr if any of the following conditions is true:

• You specify the number of an already open socket.
• You pass a socket number greater than 127.
• The socket table is full.

The POpenSkt function is equivalent to calling the PBControl function with a value of openSkt in the csCode field of the parameter block.

You must provide a socket listener when you call the POpenSkt function. If you do not intend to listen for DDP datagrams through the socket you open with this function, you can provide a socket listener that does nothing but immediately return control to DDP.

DDP reads the destination socket address and delivers datagrams to the socket listener associated with the socket. The socket listener can be part of a DDP client application or a higher-level AppleTalk protocol that is also a client of DDP.

If you want a process using a socket to be visible to other processes using the AppleTalk network, use the NBP PRegisterName function to register the name that is associated with the socket and address of the process. See the chapter "Name-Binding Protocol (NBP)" in this book for more information about NBP.

SPECIAL CONSIDERATIONS

You cannot specify NIL for the listener parameter; if you do so, your application will crash and the computer on which it is running will hang.

ASSEMBLY-LANGUAGE INFORMATION

To execute the POpenSkt function from assembly language, call the _Control trap macro with a value of openSkt in the csCode field of the parameter block. You must also specify the .MPP driver reference number. To execute the _Control trap asynchronously, include the value ,ASYNC in the operand field.

RESULT CODES

noErr	0	No error
ddpSktErr	-91	Bad socket number or socket table is full

SEE ALSO

For information about how to use the POpenSkt function in sequence with other routines to send and receive data over an AppleTalk network, see "Sending and Receiving Data: An Overview" beginning on page 7-9.