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 3 - Name-Binding Protocol (NBP) / NBP Reference
Routines / Handling Name and Address Requests


PConfirmName

The PConfirmName 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.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe function result.
-->ioRefNumIntegerThe .MPP driver reference number.
-->csCodeIntegerAlways confirmName.
-->intervalByteThe retry interval.
<->countByteThe retry count.
--> entityPtrPtrA pointer to an entity name.
--> confirmAddrAddrBlockThe entity address.
<-- newSocketByteThe 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 the ioCompletion 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 of noErr as soon as the function begins execution. When the function completes execution, it sets the ioResult 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 the PConfirmName function is to retry the operation. A retry count of 3 or 4 is usually sufficient. The PConfirmName 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 the NBPSetEntity 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, the PConfirmName function returns the new socket number in this field and returns the nbpConfDiff 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 the PConfirmName function. If the address is no longer associated with the name, PConfirmName returns a result code
of nbpNoConfirm, 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's newSocket field and a result code of nbpConfDiff. This function generates less network traffic than the PLookupName function.

SPECIAL CONSIDERATIONS
Memory used for the buffer containing the entity name and the record containing the entity address belongs to PConfirmName until the function completes execution.

ASSEMBLY-LANGUAGE INFORMATION
To execute the PConfirmName function from assembly language, call the _Control trap macro with a value of confirmName in the csCode 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
noErr0No error
nbpNoConfirm-1025Name not confirmed
nbpConfDiff-1026Name confirmed for different socket
tooManyReqs-1097Too many concurrent requests; wait a few minutes, then try the request again
reqAborted-1105Request canceled
SEE ALSO
For a description of the AddrBlock 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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996