5.1 Event Priorities

The functions for registering and unregistering eDirectory events are NWDSERegisterForEvent and NWDSEUnRegisterForEvent, both of which require values for the priority, type, and handler parameters. The priority parameter can have one of the following values:

EP_INLINE

Provides synchronous pre-event reporting because the callback can determine whether or not the event is allowable. If the callback returns a nonzero value, the transaction is aborted and the callback’s return value is returned to the module that created the event.

Since the module that created the event waits for a response while the callback processes, callbacks need to return as quickly as possible.

The callback can sleep, but usually only sleeps to allocate memory.

A zero (0) return value indicates success. A nonzero value indicates failure.

This priority is the most difficult one to use for chained event handlers. You cannot assume that an eDirectory event will complete if your callback returns zero. The next callback in the chain could abort the transaction. To verify changes occurred, register a callback for the DSEP_JOURNAL or DSEP_WORK priorities.

Warning: While inside this callback, use discretion in calling functions that create more eDirectory events. This is a closed loop where the growth of the journal queue could be uncontrollable.

EP_JOURNAL

Provides synchronous post-event reporting because event information is stored in a journal queue that records the events in the order they occurred.

A single thread services all of the callbacks for the events, so the callback’s execution time should be minimized. One method is to have the callback determine if the data should be used. If it should be used, the callback stores the data in a list that another thread processes.

If multiple callbacks are registered for the same event, the current callback must be processed before the next callback is called.

The callback can sleep.

EP_WORK

Provides asynchronous post-event reporting because events are reported after they occur, but not necessarily in the order they occurred. They are reported only after all of the event’s callbacks registered for the EP_JOURNAL priority have completed.

Each callback is run on a separate thread. This frees the event handler from the time constraints of the other two priorities.

The callback can sleep.

Time is not a critical issue with this priority.