Inside Macintosh: Open Transport /

Chapter 4 - Mappers / Mappers Reference

Functions / Creating Mappers

OTOpenMapper

Creates a mapper provider and returns a mapper reference. This function is synchronous and creates a mapper that operates synchronously.

C INTERFACE

MapperRef OTOpenMapper (OTConfiguration* config, OTOpenFlags oflag, 
                        OSErr* err)

C++ INTERFACES

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

PARAMETERS

config

A pointer to a configuration structure that specifies the mapper's characteristics. You obtain a value for the config parameter by calling the OTCreateConfiguration function. The OTOpenMapper function deletes the configuration structure when creating the mapper or attempting to create it.

oflag

Reserved; must be set to 0.

err

A pointer to the result code for this function.

DESCRIPTION

The OTOpenMapper function opens a mapper having the configuration specified by the config parameter. For additional information see the chapter "Configuration Management" and the documentation provided for the name-binding protocol you are using. The function returns a mapper reference, by which you refer to the created mapper when calling mapper functions. If the OTOpenMapper function fails, its return value is NULL.

A mapper created by the OTOpenMapper function operates in synchronous mode, unless you change the mapper's mode of execution by calling the OTSetAsynchronous function. When a mapper is in synchronous mode, all mapper provider functions execute synchronously.

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

You can open multiple mappers using identical or different configurations, although if you use identical configurations, you must read the "Special Considerations" section, next. The different mappers can be distinguished by the mapper reference.

SPECIAL CONSIDERATIONS

Because the OTOpenMapper function executes synchronously, your application should not call this function at interrupt time.

The OTOpenMapper function destroys the configuration structure returned by the OTCreateConfiguration function. If you want to use the same configuration to open additional mappers, you must obtain a valid copy of the configuration structure by calling the OTCloneConfiguration function.

SEE ALSO

The OTCreateConfiguration function used to create the configuration structure that defines the protocols underlying the mapper is discussed in the chapter "Configuration Management" in this book.

To create a mapper asynchronously, call the OTAsyncOpenMapper function (page 4-16).

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

For additional information about a mapper's mode of operations, see "Setting Modes of Operation for Mappers" on page 4-5.

The OTSetAsynchronous function, the OTSetBlocking function, and the OTIsAckingSends function are described in the chapter "Providers" in this book.