Important: The information in this document is obsolete and should not be used for new development.
PConfirmName
ThePConfirmName
function confirms that a network-visible entity whose name you know is still available on the network and that the address associated with the name has not been changed.
FUNCTION PConfirmName (thePBptr: MPPPBPtr; async: Boolean): OSErr;
thePBptr
- A pointer to an MPP parameter block.
async
- A Boolean that specifies 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. --> ioRefNum Integer The .MPP driver reference number. --> csCode Integer Always confirmName
.--> interval Byte The retry interval. <-> count Byte The retry count. --> entityPtr Ptr A pointer to an entity name. --> confirmAddr AddrBlock The entity address. <-- newSocket Byte The current socket number.
Field Description
ioCompletion
- A pointer to a completion routine that you can provide. When you execute a function asynchronously, the .MPP driver calls your completion routine when it completes execution of the function if you specify a pointer to the routine as the value of this field. Specify
NIL
for this field if you do not wish to provide a completion routine. If you execute a function synchronously, the .MPP driver ignores theioCompletion
field. For information about completion routines, see the chapter "Introduction to AppleTalk" in this book.ioResult
- The result of the function. When you execute the function asynchro-
nously, the function sets this field to 1 and returns a function result ofnoErr
as soon as the function begins execution. When the function completes execution, it sets theioResult
field to the actual result code.ioRefNum
- The .MPP driver reference number. The MPW interface fills in
this field.csCode
- The command code of the .MPP command to be executed. The MPW interface fills in this field.
interval
- The retry interval to be used by NBP when it looks on the internet for the entity. The retry interval value specifies how long the function is to wait between retries in 8-tick units. A value of 7 for the
interval
field is usually sufficient (7 8 = 56 ticks equals approximately 1 second).count
- The retry count to be used by NBP when it looks on the internet for the entity. The value of
count
specifies the number of times thePConfirmName
function is to retry the operation. A retry count of 3 or 4 is usually sufficient. ThePConfirmName
function decrements this field each time it looks for names.entityPtr
- A pointer to an entity name that you want to confirm. The entity name must be in the format that Figure 3-5 on page 3-11 shows.
You can use theNBPSetEntity
procedure to create the entity name record.confirmAddr
- The last known address of the network-visible entity whose existence you wish to confirm.
newSocket
- The current socket number of the entity. If the socket number of
the entity has changed, thePConfirmName
function returns the new socket number in this field and returns thenbpConfDiff
result code.DESCRIPTION
If you already know the name and address of a network-visible entity, but want to confirm that the name is still registered with NBP and that the address hasn't changed before you attempt to send data to it, you can use thePConfirmName
function. If the address is no longer associated with the name,PConfirmName
returns a result code
ofnbpNoConfirm
, indicating that the name may have been removed from the socket.
If the name is assigned to another socket,PConfirmName
returns the current socket number in the parameter block'snewSocket
field and a result code ofnbpConfDiff
. This function generates less network traffic than thePLookupName
function.SPECIAL CONSIDERATIONS
Memory used for the buffer containing the entity name and the record containing the entity address belongs toPConfirmName
until the function completes execution.ASSEMBLY-LANGUAGE INFORMATION
To execute thePConfirmName
function from assembly language, call the_Control
trap macro with a value ofconfirmName
in thecsCode
field of the parameter block. To execute the_Control
trap asynchronously, include the value,ASYNC
in the operand field. To execute this function from assembly language, you must also specify the driver reference number.RESULT CODES
noErr 0 No error nbpNoConfirm -1025 Name not confirmed nbpConfDiff -1026 Name confirmed for different socket tooManyReqs -1097 Too many concurrent requests; wait a few minutes, then try the request again reqAborted -1105 Request canceled SEE ALSO
For a description of theAddrBlock
data type, see "Address Block Record" on page 3-19.To find the address of a network-visible entity whose name or address you do not already know, use the
PLookupName
function, described on page 3-28.To cancel a name confirmation request, use the
PKillNBP
function, described on page 3-36.