Legacy Document

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

Chapter 21 - Providers Reference / Application-Defined Notifier Functions

/

MyNotifierCallbackFunction

After you install a notifier function on a provider, the provider calls the notifier function each time a provider event occurs. The declaration for the procedure is

typedef pascal void (*OTNotifyProcPtr)(void *contextPtr,
                  OTEventCode code, 
                  OTResult result, 
                  void *cookie);

C INTERFACE

pascal void MyNotifierCallbackFunction(void* contextPtr, 
                     OTEventCode code,
                                         OTResult result,
                     void* cookie)

C++ INTERFACE

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

PARAMETERS

contextPtr

The value you specified for the contextPtr parameter when installing this notifier function. You can use this parameter in any way that is useful to you.

code

An event code indicating the event that occurred. Possible values for event codes are given in the event code enumeration.

result

For completion events, the result code of the completed provider function, identified by the code parameter. For asynchronous events, the meaning of the result parameter is event specific. (For most asynchronous events, the result parameter has no meaning and can be ignored.) For additional information, see the description of the individual event code.

cookie

A pointer to data. The meaning and type of the data vary, depending on the event code returned in the code parameter. For additional information, see the event codes enumeration.

DISCUSSION

Using a notifier function is the recommended way for your application to handle provider events. After you install a notifier function for a provider, the function is called by the provider each time a provider event occurs for that provider. For a completion event, the provider passes the function result in the result parameter, the event code in the code parameter, and any additional information in the cookie parameter. For an asynchronous event, the provider usually passes the event code in the code parameter and passes no other information.

To install a notifier function for an existing provider, call the OTInstallNotifier function. You can also install a notifier when you open a provider asynchronously by passing a pointer to the notifier function as a parameter to the function used to open the provider. For additional information, see the reference section of the chapter describing the provider of interest.

You can install the same notifier function for two or more providers and use the contextPtr parameter to distinguish among them. Typically the data structure referenced by the contextPtr parameter includes a provider reference or some other identifier that uniquely identifies the provider for which the notifier is called.

Open Transport attempts to minimize re-entrancy and stack overflow problems by queueing calls to a notification routine, but this behavior is not guaranteed. Open Transport does guarantee that the notification routine will not be reentered if you are processing a completion event (the event code ends in _COMPLETE) or an asynchronous event (T_LISTEN, T_CONNECT, T_DATA, T_EXDATA, T_DISCONNECT, T_UDERR, T_ORDREL, T_REQUEST, T_REPLY, T_PASSCON). Other events, principally kOTProviderWillClose and T_MEMORYRELEASED may cause your notifier to be reentered. You can use the functions OTEnterNotifier and OTLeaveNotifier to allow your foreground code to limit interruption by notification events.

WARNING

For 68000 code it is vital you use the pascal keyword when declaring your notifier function.

SPECIAL CONSIDERATIONS

Open Transport can call your notifier function at deferred task time. For this reason, your notifier function is subject to the same rules and restrictions as are all Macintosh functions that can be called at deferred task time; these restrictions are summarized in the section "Using Notifier Functions to Handle Provider Events". Because your notifier can be called at deferred task time, you can only call a limited set of Open Transport functions from your notifier; Table C-3 lists the Open Transport functions that you can call at deferred task time.

The following information applies to 68000-based code--whether it runs in emulated mode or on 680x0 machines. Before calling your notifier function, Open Transport restores the A5 register to the value it had when you installed the notifier function. Thus, for applications, your notifier function need not restore its A5 world. But if you're developing a code resource and your development environment references your globals from a register other than A5, your notifier function must save and restore that register.

SPECIAL CONSIDERATIONS

You cannot call any Thread Manager function that will cause the current thread to yield immediately (YieldToThread or YieldToAnyThread) from within your notification function unless the event code to the notifier is the kOTSyncIdleEvent code. Use the OTUseSyncIdleEvents function to allow synchronous idle events to be sent to your notifier.

SEE ALSO

The OTRemoveNotifier function.

The event codes enumeration.

Listing 3-1.