Legacy Document

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

Chapter 22 - Endpoints Reference / Functions

Establishing Connection /

OTConnect

Requests a connection to a remote peer.

C INTERFACE

OSStatus OTConnect(EndpointRef ref, 
                     TCall* sndCall, 
                     TCall* rcvCall);

C++ INTERFACE

OSStatus TEndpoint::Connect(TCall* sndCall, 
                     TCall* rcvCall);

PARAMETERS

ref

The endpoint reference of the endpoint initiating the connection.

sndCall

A pointer to a structureTCall structure. You must allocate buffers, store the appropriate address, option, and data in them, and specify their length.

The sndCall->addr.buf field points to a buffer that specifies the address of the passive peer. The sndCall->addr.len field specifies the size of the address in bytes.

The sndCall->opt.buf field points to a buffer that specifies the options you want to negotiate. The sndCall->opt.len field specifies the size of the buffer in bytes.

The sndCall->udata.buf field points to a buffer that contains data you want to send with the connection request. The sndCall->udata.len field specifies the size of the data in bytes.

rcvCall

A pointer to a TCall structure that stores information about the connection when the function returns. You can set this parameter to nil, inwhich case no information is returned to you.

This parameter is only meaningful for synchronous calls to the OTConnect function. In this case, you must allocate the buffers for address, options, and data returned, and you must specify their maximum length. You can set this to nil if you'e not interested in the result.

The rcvCall->addr.buf field points to a buffer that is used to store the address to which you are actually connected. Set the rcvCall->addr.maxlen field to the size of the buffer in bytes.

The rcvCall->opt.buf field points to a buffer in which the options that have actually been negotiated are stored. Set the rcvCall->opt.maxlen field to the size of the buffer in bytes.

The rcvCall->udata.buf field points to a buffer that contains data sent by the peer accepting the connection. Set the rcvCall->udata.maxlen field to the size of the buffer in bytes.

function result

An error code. See Discussion.

DISCUSSION

If the endpoint is in synchronous mode, the OTConnect function returns after the connection is established and fills in the fields of the rcvCall parameter with the actual values associated with this connection. These might be different from the values you specified using the sndCall parameter.

If the OTConnect function returns with the kOTLookErr result, this might be either because of a pending T_LISTEN or T_DISCONNECT event. That is, either a connection request from another endpoint has interrupted execution of the function, or the remote endpoint has rejected the connection. If you don't have a notifier installed, you can call the OTLook function to identify the event that caused the kOTLookErr result. If the event is T_LISTEN, you must accept or reject the incoming request and then continue processing the OTConnect function by calling the function OTRcvConnect. If the event is T_DISCONNECT, you must call the OTRcvDisconnect functionto clear the error condition--that is, to deallocate memory and place the endpoint in the correct state.

If the endpoint is in asynchronous mode, the OTConnect function returns before the connection is established with a kOTNoDataErr result to indicate that the connection is in progress. When the connection is established, the endpoint provider calls your notifier, passing T_CONNECT for the code parameter. In response, you must call the OTRcvConnect function to read the connection parameters that would have been returned in the rcvCall parameter if the endpoint were in synchronous mode.

It is possible that the remote address returned in the addr.buf field of the rcvCall parameter is not the same as the address you requested using the sndCall->addr field. This happens when the remote peer accepts the connection on a different endpoint than the one receiving the connection request.

If the OTConnect function returns a result other than kOTNoDataErr, then the connection attempt has not been initiated and no events will be received.

SPECIAL CONSIDERATIONS

Not all endpoints support the sending of data with a connection request. Examine the connect field of the TEndpointInfo structure for the endpoint to determine if the endpoint supports the sending of data and to determine the maximum size of the data.

SEE ALSO

"AppleTalk Reference".

Table 4-4 .