Legacy Document

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.

-->	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 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

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 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.