Legacy Document

Inside Macintosh: Networking /

Chapter 6 - AppleTalk Transaction Protocol (ATP) / ATP Reference

Routines / Setting Up a Socket to Listen for Requests

PGetRequest

The PGetRequest function sets up a socket to listen for a request from another socket.

FUNCTION PGetRequest (thePBPtr: ATPPBPtr; async: Boolean): OSErr;

thePBPtr

A pointer to an ATP parameter block.

async

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

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
<--	userData	LongInt	Four bytes of user data.
<--	reqTID	Word	The transaction ID.
-->	csCode	Integer	Always getRequest for this function.
-->	atpSocket	Byte	The socket number.
<--	atpFlags	Byte	The control information.
<--	addrBlock	LongInt	The destination socket address.
<->	reqLength	Word	On input, the request buffer size. On return, the actual of the request received.
-->	reqPointer	Ptr	A pointer to the request buffer.
<--	bitMap	Byte	A bitmap.

Field Description

userData

The 4 user bytes from the request.

reqTID

The transaction ID of the request that PGetRequest has received. ATP supplies this value.

atpSocket

The number of the socket that is to be used to listen for requests. This is the number of a socket you opened using the POpenATPSkt function call.

atpFlags

A control information field whose bits, numbered 0-7, are used
as flags.

ATP sets bit 5, the exactly-once flag (atpXOvalue), if the request received is part of an exactly-once transaction.

addrBlock

The AppleTalk internet address of the socket from which the request was sent. ATP returns this value.

reqLength

On input, the size in bytes of the buffer to be used to store the incoming request. On return, the actual number of bytes of the request received.

reqPointer

A pointer to the location of the buffer to be used to store the incoming request.

bitMap

A bitmap of the transaction that ATP returns.

DESCRIPTION

To receive an ATP request, you must set up a socket to listen for incoming requests; you use the PGetRequest function to do this. In almost all cases, you should call the PGetRequest function asynchronously to avoid delaying execution of your program until after an ATP request comes in. The PGetRequest function completes execution after it receives an ATP request.

The PGetRequest function returns the transaction ID of the request that it receives in the reqTID field. You should save this value if you intend to respond to the request; this transaction ID is used as an input parameter to the PSendResponse and PAddResponse functions. To determine that the request transaction ID specified in the reqTID field is valid, first check the atpTIDValidvalue bit (bit 1) of the atpFlags field. If this bit is set, the reqTID field value is valid.

You must allocate nonrelocatable memory to be used as the buffer to hold an incoming request. Make sure that you allocate enough memory to hold the entire request; ATP
will not deliver more data than will fit in the amount of buffer space that you specified as the value of the reqLength field. The buffer should be 578 bytes long, which is the maximum size of a request packet, unless you know the exact size of the request.

SPECIAL CONSIDERATIONS

Memory used for the incoming request buffer belongs to ATP for the life of the call.

ASSEMBLY-LANGUAGE INFORMATION

To execute the PGetRequest function from assembly language, call the _Control trap macro with a value of getRequest in the csCode field of the parameter block. To execute this function from assembly language, you must also specify the .ATP driver reference number.

RESULT CODES

noErr	0	No error
badATPSkt	-1099	Bad responding socket

SEE ALSO

For information on opening a socket that you can set up to receive requests, use the POpenATPSkt function, described on page 6-30.