Important: The information in this document is obsolete and should not be used for new development.
PGetRequest
ThePGetRequest
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 thePGetRequest
function to do this. In almost all cases, you should call thePGetRequest
function asynchronously to avoid delaying execution of your program until after an ATP request comes in. ThePGetRequest
function completes execution after it receives an ATP request.The
PGetRequest
function returns the transaction ID of the request that it receives in thereqTID
field. You should save this value if you intend to respond to the request; this transaction ID is used as an input parameter to thePSendResponse
andPAddResponse
functions. To determine that the request transaction ID specified in thereqTID
field is valid, first check theatpTIDValidvalue
bit (bit 1) of theatpFlags
field. If this bit is set, thereqTID
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 thereqLength
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 thePGetRequest
function from assembly language, call the_Control
trap macro with a value ofgetRequest
in thecsCode
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 thePOpenATPSkt
function, described on page 6-30.