Legacy Document

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

Chapter 24 - Mappers Reference / Functions

Creating Mappers /

OTAsyncOpenMapper

Creates an asynchronous mapper and installs a notifier function for the mapper provider.

C INTERFACE

OSStatus OTAsyncOpenMapper (OTConfiguration* config, 
                                         OTOpenFlags oflag, 
                                         OTNotifyProcPtr proc,
                                        

C++ INTERFACE

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 disposes of the configuration before returning.

oflag

Reserved; must be set to 0.

proc

A pointer to a notifier function for this mapper.

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 parametert o pass to your notifier function information about your mapper.

function result

An error code. See Appendix B for more information.

DISCUSSION

The OTAsyncOpenMapper function opens a mapper having the configuration specified by the config parameter. For additional information on mappers and configurations see "Getting Started With Open Transport" and the documentation provided for the mapper protocol you are using. The OTAsyncOpenMapper function runs asynchronously, returning 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. For more information on notifier functions and event codes see "Using Notifier Functions" and "Event Codes".

A mapper created by the OTAsyncOpenMapper function operates in asynchronous mode and does not block. For more information about a mapper's mode of operations, see the section "Setting Modes of Operation for Mappers".

You can open multiple mappers using identical or different configurations. 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.

To close a mapper use the function OTCloseProvider.

SPECIAL CONSIDERATIONS

The OTAsyncOpenMapper function destroys the configuration value passed in the config parameter. You cannot use the same configuration to open multiple mappers. To copy the configuration for use when opening another mapper, you must call the OTCloneConfiguration function.

SEE ALSO

The OTOpenMapper function.