Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Creating Endpoints

OTOpenEndpoint

Opens an endpoint. This function is synchronous, and creates an endpoint that operates synchronously. It is strongly recommended that you use endpoints in asynchronous mode whenever possible.

C INTERFACE

EndpointRef OTOpenEndpoint (OTConfiguration* config, 
                            OTOpenFlags oflag, 
                            TEndpointInfo* info, 
                            OSStatus* err);

C++ INTERFACES

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 OTOpenEndpoint function deletes the configuration structure when creating the endpoint or attempting to create it.

oflag

Reserved; must be set to 0.

info

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

err

A pointer to the result code for this function.

DESCRIPTION

The OTOpenEndpoint function opens an endpoint having the configuration specified by the config parameter. The function returns an endpoint reference, by which you refer to the created endpoint when calling provider functions. If the OTOpenEndpoint function fails, its return value is NULL.

An endpoint created by the OTOpenEndpoint function operates in synchronous mode, unless you change the endpoint's mode of execution by calling the OTSetAsynchronous function. When an endpoint is in synchronous mode, all provider functions that use the endpoint execute synchronously.

By default, a newly created endpoint does not block and does not acknowledge sends. To change the endpoint's default mode of operation, you can call the OTSetBlocking function and the OTIsAckingSends function.

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

SPECIAL CONSIDERATIONS

The OTOpenEndpoint function changes the contents of memory and writes information to disk; your application should not call the OTOpenEndpoint function at interrupt time.

The OTOpenEndpoint function destroys 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 before calling the OTOpenEndpoint function, by calling the OTCloneConfiguration function.

SEE ALSO

To create an OTConfiguration structure, use the OTCreateConfiguration function described in the chapter "Configuration Management" in this book.

To obtain a copy of the OTConfiguration structure, use the OTCloneConfiguration function described in the chapter "Configuration Management" in this book.

To create an endpoint that operates asynchronously, call the OTAsyncOpenEndpoint function (page 3-71).

Modes of execution are defined in the section "Modes of Operation," beginning on page 3-11. For information about changing an endpoint's mode of execution, see the chapter "Providers" in this book.

When you open an endpoint, Open Transport also creates the TEndpointInfo structure, which contains important information about the endpoint (page 3-48).

Endpoint states are defined and listed in"Endpoint States," beginning on page 3-13.

To close and delete an endpoint, call the OTCloseProvider function described in the chapter "Providers" in this book.

To bind a protocol address to an endpoint, call the OTBind function (page 3-77).

The OTSetAsync, OTSetBlocking, and OTIsAckingSends functions are described in the chapter "Providers" in this book.