Inside Macintosh: Open Transport /

Chapter 6 - Configuration Management / Configuration Management Reference

Functions / Creating, Cloning, and Removing 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.

DESCRIPTION

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

The simplest possible value of the path parameter is a single protocol module name of the highest-level protocol you want to use; for example, "tcp." If you do not specify a complete communications path, the Open Transport software 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 DataStream Protocol (ADSP) protocol module layered above the Datagram Delivery Protocol (DDP) protocol module and with LocalTalk on the default port, which is the printer port.

If you want to identify a particular port in the configuration string, you use the port name to do so (described in the section "About Port Information," beginning on page 6-5). More typically, however, you leave this value blank--for example, using a string with only "adsp" or "adsp, ddp," which configures the provider with whatever port is specified in the 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 checksum option
is enabled.

If Open Transport cannot parse the list that you pass in the path parameter,
the OTCreateConfiguration function returns ((OTConfiguration*)-1L).
If there is insufficient memory to create an OTConfiguration structure, the OTCreateConfiguration function returns NULL.

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 (discussed in the chapters "Endpoints" and Mappers" in this book).

SPECIAL CONSIDERATIONS

Functions that open providers delete 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

For more information about creating configuration structures, see the sections "About Provider Configurations" (page 6-3) and "Creating and Reusing Provider Configurations" (page 6-10).

To copy an OTConfiguration structure, call the OTCloneConfiguration function (page 6-29).

To delete an OTConfiguration structure, call the OTDestroyConfiguration function (page 6-30).

You can use the functions in "Obtaining Port Information" (page 6-11) to get the names of any or all of the hardware ports on the system.

To create and open an endpoint, call the OTOpenEndpoint function or the OTAsyncOpenEndpoint function, both described in the chapter "Endpoints" in this book.

To create and open a mapper, call the OTOpenMapper function or the OTAsyncOpenMapper function, both described in the chapter "Mappers"
in this book.

To create and open an AppleTalk service provider, call the OTOpenAppleTalkServices function or the OTAsyncOpenAppleTalkServices function, both described in the chapter "AppleTalk Services" in this book.

To create and open a TCP/IP service provider, call the OTOpenInternetServices function or the OTAsyncOpenInternetServices function, both described in the chapter "TCP/IP Services" in this book.