Inside Macintosh: Open Transport /

Chapter 4 - Mappers / Mappers Reference

Functions / Creating Mappers

OTAsyncOpenMapper

Creates a mapper and installs a notifier function for the mapper provider. The OTAsyncOpenMapper function is asynchronous and creates a mapper that operates asynchronously by default.

C INTERFACE

OSErr OTAsyncOpenMapper (OTConfiguration* config, OTOpenFlags oflag, 
                         OTNotifyProcPtr proc, void* contextPtr);

C++ INTERFACES

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

PARAMETERS

config

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

oflag

Reserved; must be set to 0.

proc

A pointer to a notifier function for this mapper. If you do not provide a notifier function, your application cannot receive Open Transport events, including the event advising you that the mapper has been created.

contextPtr

A context pointer for your use. The mapper provider passes this pointer value when calling the notifier function you specify in the proc parameter. You might use the contextPtr parameter, for example, to pass to your notifier function information about your application's current context.

DESCRIPTION

The OTAsyncOpenMapper 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 OTAsyncOpenMapper function runs asynchronously, returning a result code as soon as the function has been queued for execution.

The OTAsyncOpenMapper function attempts to create a mapper, and then calls the notifier function that you specified in the proc parameter, passing T_OPENCOMPLETE for the code parameter, a result code in the result parameter, and the mapper reference for the newly created mapper in the cookie parameter.

A mapper created by the OTAsyncOpenMapper function operates in asynchronous mode, unless you change the mapper's mode of execution by calling the OTSetSynchronous function. When a mapper is in asynchronous mode, all provider functions that use the mapper execute asynchronously.

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. The different mappers can be distinguished by the mapper reference. You can set the contextPtr parameter to point to the mapper reference or to a structure containing the mapper reference; this allows your notifier function to determine to which mapper a completion event belongs.

SPECIAL CONSIDERATIONS

The OTAsyncOpenMapper function destroys the configuration value returned by the OTCreateConfiguration function. You cannot use the same configuration to open multiple mappers. To obtain a valid copy of the configuration for use when opening another mapper, you must call the OTCloneConfiguration function.

COMPLETION EVENT CODES

T_OPENCOMPLETE

0x20000007

The OTAsyncOpenMapper function has completed. The cookie parameter of the notifier function points to the mapper reference for the new mapper.

SEE ALSO

To open a mapper in synchronous mode, use the OTOpenMapper function (page 4-19).

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

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

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.

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