Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials

Chapter 2 - Getting Started With Open Transport

Configuring and Opening a Provider

After initializing Open Transport but before you can send or receive data, you must configure and open a provider. Providers supply data-oriented services, and are implemented by modules that can be layered to provide the services in which you are interested. To create a provider configuration, you call the function OTCreateConfiguration, passing it a configuration string that describes this layering. The following two sections explain this process in greater detail.

Creating a Configuration Structure

The OTCreateConfiguration function creates a configuration structure and returns a pointer to it. The configuration string can be the name of a single protocol, such as "adsp", "tcp", or "dnr", or it can be a comma-separated list of protocol and port names. For instance, the string

"adsp,ddp,ltlkB" 

describes an AppleTalk Data Stream Protocol (ADSP) endpoint provider using the Datagram Delivery Protocol (DDP) with LocalTalk link access provided through the LocalTalk B (Printer) port.

Open Transport has internally defined defaults for how protocols can be layered upon each other. If you give Open Transport a single protocol name, it checks its defaults to determine which lower layers are missing. Thus, the shorter string

"adsp" 

also describes an identical ADSP endpoint provider (if you have the Printer port configured in the AppleTalk control panel). Likewise, if you skip a protocol layer in the string, Open Transport uses its defaults to try to complete it. For instance, the specification "tcp,enet" is incomplete because the Transmission Control Protocol (TCP) does not have direct access to Ethernet, so Open Transport puts the default Internet Protocol (IP) between TCP and Ethernet.

You can also specify options as part of the configuration string. To do this, you need to know which protocols use which options and how to translate the option's constant name, given in the header files, into a string that the configuration functions can parse. See the TCP/IP and AppleTalk chapters for lists of their protocol-specific options and their equivalent string values. But for a simple example, the following configuration string

"adsp,ddp(Checksum=1)" 

describes an ADSP endpoint provider with the DDP checksum option enabled.

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

Most protocols have a literal string value that you can use to configure providers. For example, DDP uses "ddp" and ADSP uses "adsp". There are also constants that identify each protocol, such as kDDPName and kADSPName. For a complete list of the AppleTalk constant-string equivalents, see the chapter "Introduction to AppleTalk" in this book. For information on specifying TCP/IP services, see the chapter "TCP/IP Services".

You can use either a constant or a literal value to create a provider that does not use options and that adheres to the default protocol layering. For example, to configure a DDP endpoint, you could use either of the following lines of code:

ep = OTOpenEndpoint(OTCreateConfiguration("ddp"), 0, NULL, &err); 
ep = OTOpenEndpoint(OTCreateConfiguration(kDDPName), 0, NULL, &err);

To configure more complex providers, it is easier to use the literal strings. Using the constant can be confusing, shown by a comparison of the following lines of code:

ep = OTOpenEndpoint(OTCreateConfiguration
      ("adsp(EnableEOM=1),ddp,ltlkB"), 0, NULL, &err) 
ep = OTOpenEndpoint(OTCreateConfiguration
      (kADSPName"(EnableEOM=1),"kDDPName",ltlkB"), 0, NULL, &err);

Some configurations are not valid and the OTCreateConfiguration function will return an error if you try to create one. For example, trying to layer ADSP on top of IP will not work.

Opening a Provider

You can pass the pointer returned by the function OTCreateConfiguration to the function that opens the provider, for example, the OTOpenEndpoint function. Typically, you call the OTCreateConfiguration function inline while calling the function that creates and opens a provider. Here is an example

ep = OTOpenEndpoint(OTCreateConfiguration("ddp"), 0, NULL, &err); 

The function you use to open a provider returns a provider reference. You must specify that provider reference whenever you call a function for that provider. For example, if you open an endpoint provider, you must specify its provider reference when you call a function that sends or receives data.

Reusing Provider Configurations

The functions used to open providers take a pointer to the configuration structure as input, but as part of their processing, they dispose of the original configuration structure. Since typically you use the OTCreateConfiguration function to create a single provider at a time, this does not present a problem. Occasionally, however, you may want to reuse a configuration structure to create a second identical provider, or you may want to reuse a configuration for which you do not have the configuration string.

The only way to reuse a configuration structure is to clone it with the OTCloneConfiguration function before opening your first provider. Cloning allows you to make multiple copies of the same configuration. For example, you might have only a pointer to a configuration structure, but you want to create ten endpoints, and so you need ten configuration structures. The moment you use the original pointer to create an endpoint, the configuration structure is gone. You can't call the OTCreateConfiguration function because you don't have the original configuration string; you were only passed the configuration structure. However, you can clone the original configuration structure before opening each endpoint. For additional information, see "Streamlining Endpoint Creation".

---

Subtopics

Creating a Configuration Structure

Opening a Provider

Reusing Provider Configurations