Legacy Document

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

Chapter 20 - Initializing and Closing Open Transport Reference / Functions

Creating, Cloning, and Disposing of a Configuration Structure /

OTCreateConfiguration

Creates a structure defining a provider's configuration.

C INTERFACE

OTConfiguration* OTCreateConfiguration(const char* path);

C++ INTERFACES

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

PARAMETERS

path

A pointer to a character string describing the provider.

function result

A pointer to a private OTConfiguration structure. If the value specified with the path parameter was invalid, the function returns the result kOTInvalidConfigurationPtr. If there was not enough memory to create the structure, the function returns the result kOTNoMemoryConfigurationPtr.

DISCUSSION

The OTCreateConfiguration function creates a configuration structure that defines the software modules, hardware ports, and options that Open Transport uses when you open a provider. This is a private structure, defined by the OTConfiguration data type . To create a configuration structure, use the path parameter to pass a string describing the provider service desired to the OTCreateConfiguration function.

The simplest possible value of the path parameter is the name of the highest-level protocol you want to use; for example, "tcp". If you do not specify a complete communications path, Open Transport uses default settings to construct the rest of the path. For example, if you specify "adsp" for the path parameter, Open Transport defaults to using the AppleTalk Data Stream Protocol (ADSP) protocol module layered above the Datagram Delivery Protocol (DDP) protocol module, which is, in turn, layered on the default port configured in the AppleTalk control panel.

If you want to identify a particular port in the configuration string, you use the port name to do so, described in the chapter "Ports". More typically, however, you leave this value blank--for example, using a string with only "adsp", which configures the provider with whatever port is specified in the AppleTalk control panel.

To specify more than one protocol module, separate the module names with commas. You can also specify values for options by putting them in parentheses after the protocol name; for example, "adsp, ddp(Checksum=1)" specifies that ADSP is to run on top of DDP and that the DDP checksum option is enabled. For a list of valid options for each protocol, see the corresponding protocol reference chapter.

The OTCreateConfiguration function returns a pointer to the configuration structure it creates. You pass this pointer as a parameter to the open-provider functions such as the OTOpenEndpoint or OTOpenMapper functions. If the function returns an error code, it is safe to pass the error code as the OTOpenEndpoint OTConfiguration* parameter. OTOpenEndpoint will return the appropriate error.

SPECIAL CONSIDERATIONS

Functions that open providers dispose of the OTConfiguration structure that they use, so you need to use the OTCloneConfiguration function to clone a configuration structure if you want to open multiple providers with the same configuration.

SEE ALSO

"Reusing Provider Configurations".

The OTCloneConfiguration function.

The OTDestroyConfiguration function.

The OTOpenEndpoint function. The OTAsyncOpenEndpoint function.