Legacy Document

Inside Macintosh: Networking With Open Transport / Part 2 - Open Transport Reference

Chapter 22 - Endpoints Reference / Functions

Binding and Unbinding Endpoints /

OTBind

Assigns an address to an endpoint.

C INTERFACE

OSStatus OTBind(EndpointRef ref, 
                     TBind* reqAddr,
                     TBind* retAddr);

C++ INTERFACE

OSStatus TEndpoint::Bind(TBind* reqAddr, 
                     TBind* retAddr);

PARAMETERS

ref

The endpoint reference of the endpoint that you are binding.

reqAddr

A pointer to a TBind structure that contains information about the address to which you want to bind the endpoint and the number of possible outstanding connection requests if this is a connection-oriented endpoint.

If you specify NULL for the reqAddr parameter, Open Transport chooses a protocol address for you and requests 0 as the endpoint's maximum number of outstanding connect indications.

If you want Open Transport to assign an address for you, while still specifying a qlen value, set the addr.len field of the TBind structure to 0.

retAddr

A pointer to a TBind structure that, on return, indicates the address to which the endpoint is actually bound and, for connection-oriented endpoints, indicates the maximum number of outstanding connect indications that this endpoint actually allows. The TBind structure is described in the "Endpoints Reference".

You can set this parameter to NULL if you do not care to know what address the endpoint is bound to or what the negotiated value of qlen is. However, it is almost always a good idea to check this field to find out whether the endpoint negotiated a different queue length from the length you requested.

function result

An error code. See Discussion.

DISCUSSION

You call the OTBind function to request that an endpoint be bound to an address. You can either use the reqAddr parameter to request that the endpoint be bound to a specific address or allow the endpoint provider to assign an address dynamically by passing NULL for this parameter. Consult the documentation for the top-level protocol you are using to determine whether it is preferable to have the address assigned dynamically.

Before you call the function, you must allocate a buffer for the address and set the retAddr->addr.buf field to point to it. You must also specify the maximum size of the address using the retAddr->addr.maxlen field. The function returns the address to which the endpoint is actually bound in the retAddr parameter. This might be different from the address you requested. The field retAddr->addr.len contains the length of the address. If the ret->addr.maxlen field indicates a buffer size that is not large enough to contain the address, the function returns with the result kOTBufferOverflowErr. If the requested address is not available, the function returns the result kOTAddressBusyErr. If the endpoint cannot allocate an address, the function returns with the kOTNoAddressErr result.

If the endpoint is in synchronous mode, the function returns when the bind is complete. If the endpoint is in asynchronous mode and you have installed a notification routine, the OTBind function returns kOTNoError and sends the T_BINDCOMPLETE event to your notifier when the bind completes. For more information on notifier functions and event codes, see MyNotifierCallback function and "Event Codes". If you have not installed a notifier function, the only way to determine when the function completes is to poll the endpoint using the OTGetEndpointState function. This function returns a kOTStateChangeErr until the bind completes. When the endpoint is bound, the state is either T_UNBND if the bind failed, or T_IDLE if it succeeded. You can cancel an asynchronous bind that is still in progress by calling the OTUnbind function.

If you are binding a connection-oriented endpoint, you must use the reqAddr->qlen field to specify the number of connection requests that may be outstanding for this endpoint. You can set this field to 0 if you are only going to be initiating outgoing connections. The retAddr->qlen field specifies, on return, the actual number of connection requests allowed for the endpoint. This number might be smaller than the number you requested. Note that when the endpoint is actually connected, the number might be further decreased by negotiations taking place at that time.

You must not bind more than one connectionless endpoint to a single address. If you attempt to bind a second endpoint to the an address that is already bound, the OTBind function will return the result kOTAddressBusyErr. Some connection-oriented protocols let you bind two or more endpoints to the same address. In such instances, you must use only one of the endpoints to listen for connection requests for that address. When binding the endpoint listening for a connection, you must set the reqAddr->qlen field of the OTBind function to a value greater than or equal to 1. When binding the other endpoints, you must set the reqAddr->qlen field to 0.

If you accept a connection on an endpoint that is also listening for connection requests, the address of that endpoint is deemed "busy" for the duration of the connection, and you must not bind another endpoint for listening to that same address. This requirement prevents more than one endpoint bound to the same address from accepting connection requests. If you have to bind another listening endpoint to the same address, you must first use the OTUnbind function to unbind the first endpoint or use the OTCloseProvider function to close it.

SPECIAL CONSIDERATIONS

In asynchronous mode, the endpoint provider might call your notifier function before the function's initial return.

An endpoint may not allow an explicit binding of more than one endpoint to the same protocol address, although it allows more than one connection to be accepted for the same protocol address. To ensure portability, do not bind endpoints that are used as responding endpoints in a call to the OTAccept function if the responding address is to be the same as the called address.

SEE ALSO

The OTCloseProvider function.

Table 4-4.

"Processing Multiple Connection Requests".

The OTConnect function.

The OTAccept function.

"TCP/IP Services".

"AppleTalk Data Stream Protocol (ADSP)"

"Datagram Delivery Protocol (DDP)" .

"Printer Access Protocol (PAP)" .