Legacy Document

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

Chapter 21 - Providers Reference / Functions

Opening and Closing Providers /

OTTransferProviderOwnership

Transfers a provider's ownership to a new client.

C INTERFACE

ProviderRef OTTransferProviderOwnership(
                     ProviderRef ref,
                     OTClient prevOwner,
                     OSStatus* errPtr);

C++ INTERFACE

ProviderRef TProvider::OTTransferProviderOwnership(
                     OSStatus* errPtr);

PARAMETERS

ref

The provider reference for the provider to be transferred.

prevOwner

The previous owner of the provider.

errPtr

A pointer to a result code.

function result

A new provider reference that replaces the original.

DISCUSSION

The OTTransferProviderOwnership function transfers the ownership of the provider indicated by the ref parameter from whoever created the provider, specified by the prevOwner parameter, to the current Open Transport client. The new owner must obtain the client ID and the provider ref from the current owner before calling this function. You must use this function whenever some other entity (typically a shared library) opens an endpoint on behalf of the client.

Under Open Transport, a provider allocates a small amount of memory from the client's heap. In addition, Open Transport automatically cleans up behind clients that call the CloseOpenTransport function. If a shared library creates a provider on your behalf and that shared library subsequently unloads while you are still using the provider, two things will happen: The memory for the provider is no longer valid, and the provider is closed. By using the OTTransferProviderOwnership function, you can gain ownership of the provider. Once you do, Open Transport allocates a new provider reference in your memory pool and the provider is marked as belonging to the calling client. The old provider reference is then invalid and should not be used.

SPECIAL CONSIDERATIONS

When installing a notifier for a provider, Open Transport assumes that the OTNotifyProcPtr pointer is in the same architecture as the call being made. After transferring ownership, remove any already installed notifiers and install your own, unless you are sure that the provider's existing notifier is of the correct architecture and makes sense for you

WARNING

If you do not use the OTTransferProviderOwnership function, it is vital that the provider be closed under the same architecture that opened the provider.

SEE ALSO

The OTWhoAmI function.