Legacy Document

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

Chapter 21 - Providers Reference / Functions

Using Notifier Functions /

OTInstallNotifier

Installs a notifier function.

C INTERFACE

OSStatus OTInstallNotifier(ProviderRef ref,
                     OTNotifyProcPtr proc, 
                                         void* contextPtr);

C++ INTERFACE

OSStatus TProvider::InstallNotifier(OTNotifyProcPtr proc, 
                                         void* contextPtr);

PARAMETERS

ref

The provider reference of the provider for which you are installing a notifier.

proc

A pointer to a notifier function that you provide. (This is a function pointer not a universal proc pointer, consequently no mixed mode glue is required. You must never pass a universal procedure pointer for this parameter.)

For C++ applications, the proc parameter may point to either a C function or, depending on your development environment, a static member function.

contextPtr

A context pointer for your use. The provider passes this value unchanged to your notifier function when it calls the function. If you don't need context information, pass NIL for this parameter.

function result

An error code. See Appendix B for more information.

DISCUSSION

The OTInstallNotifier function installs a notifier function for the provider that you specify. The notifier function remains installed until you remove it using the OTRemoveNotifier function or until you close the provider. (Setting a provider to synchronous mode, does not remove the notifier.)

Before calling the OTInstallNotifier function, you must open the provider for which you want to install the notifier. If you open a provider asynchronously (for example, with the OTAsyncOpenEndpoint function), you must pass a pointer to a notifier function as a parameter to the function used to open the provider.

Opening a provider synchronously (for example, with the OTOpenEndpoint function) opens the provider but does not install a notifier function for it. If you need a notifier function for a provider opened synchronously, you must call the OTInstallNotifier function. This notifier would not return completion events, but would return asynchronous events advising you of the arrival of data, of changes in flow-control restrictions, and so on.

You should not call the OTInstallNotifier function when provider functions are executing for the provider that you specify. Otherwise, the OTInstallNotifier function returns the result code kOTStateChangeErr.

If you try to install a notifier function for a provider that already has a notifier, the OTInstallNotifier function returns with the kOTAccessErr result.

IMPORTANT

For 68000-based code, the OTInstallNotifier function saves the current value of the A5 register. Open Transport restores the A5 register to this saved value when calling the notifier function you install. If your environment stores context information in a register other than A5, your notifier function must save and restore the value of that register.

SEE ALSO

"Application-Defined Notifier Functions" .