Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

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.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe function result.
<--userDataLongIntFour bytes of user data.
<--reqTIDWordThe transaction ID.
-->csCodeIntegerAlways getRequest for this function.
-->atpSocketByteThe socket number.
<--atpFlagsByteThe control information.
<--addrBlockLongIntThe destination socket address.
<->reqLengthWordOn input, the request buffer size. On return,
the actual of the request received.
-->reqPointerPtrA pointer to the request buffer.
<--bitMapByteA 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
noErr0No error
badATPSkt-1099Bad 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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996