Legacy Document

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

Chapter 22 - Endpoints Reference / Functions

Creating Endpoints /

OTAsyncOpenEndpoint

Opens an endpoint and installs a notifier callback function for the endpoint.

C INTERFACE

OSStatus OTAsyncOpenEndpoint( OTConfiguration* config, 
                     OTOpenFlags oflag, 
                     TEndpointInfo* info, 
                     OTNotifyProcPtr proc, 
                     void* contextPtr);

C++ INTERFACE

None. C++ applications use the C interface to this function.

PARAMETERS

config

A pointer to an endpoint configuration structure that specifies the endpoint's characteristics. You obtain a value for the config parameter by calling the OTCreateConfiguration function. The OTAsyncOpenEndpoint function disposes of the configuration structure before returning.

oflag

Reserved; must be set to 0.

info

A pointer to a TEndpointInfo structure to be filled in by the OTAsyncOpenEndpoint function. Specify NULL for this parameter if you do not want the OTAsyncOpenEndpoint function to return endpoint information.

proc

A pointer to a notifier callback function for this endpoint. If you do not provide a notifier function, your application cannot receive completion events, including the event advising you that the endpoint has been created. Never pass a universal procedure pointer as the proc parameter.

contextPtr

A pointer for your use. The endpoint passes this pointer value when calling the notifier function you specify in the proc parameter. You might use the contextPtr parameter to pass your notifier function information about the endpoint, for example.

function result

An error code. See Discussion.

DISCUSSION

The OTAsyncOpenEndpoint function opens an endpoint having the characteristics specified by the config parameter. How processing proceeds depends on this result code.

If the result code is any except kOTNoError, an error occurred and Open Transport does not queue the function for execution. The OTAsyncOpenEndpoint function creates no endpoint and does not call the notifier function that you specified in the proc parameter.

If the result code is kOTNoError, the OTAsyncOpenEndpoint function has queued the operation for execution. When it completes it calls the notifier function that you specified in the proc parameter, passing the event T_OPENCOMPLETE for the code parameter, a result code in the result parameter, and the endpoint reference for the newly created endpoint in the cookie parameter. For information about notifier functions, see "Application-Defined Notifier Functions" and "Event Codes".

An endpoint created by the OTAsyncOpenEndpoint function operates in asynchronous mode, does not block, and does not acknowledge sends. To change these default settings, you can call the OTSetSynchronous function, OTSetBlocking function and the OTAckSends function.

The initial state of an endpoint is T_UNBND, meaning that the endpoint is not bound to a protocol address. Before using the endpoint to transfer data, you must bind it to a protocol address by calling the OTBind function.

SPECIAL CONSIDERATIONS

The first time you open a provider of any kind, Open Transport allocates needed resources at system task time, calling the ScheduleSystemTask function to do this. To allow this processing to take place, you need to call SystemTask or WaitNextEvent from a foreground task while waiting for the endpoint to be created.

The OTAsyncOpenEndpoint function disposes of the configuration structure returned by the OTCreateConfiguration function. If you want to use the same configuration to open additional endpoints, you must obtain a valid copy of the configuration structure by calling the OTCloneConfiguration function before you call the OTAsyncOpenEndpoint function. For more information, see "Configuring and Opening a Provider".

SEE ALSO

The OTOpenEndpoint function.

Table 4-4.