NWDSERegisterForEventWithResult

Registers a function to be used as a callback when a specific eDirectory event occurs. Passes in the current state of the event it is registering for.

Local Servers:blocking
Remote Servers:N/A
Classification:4.x, 5.x, 6.x
Platform:NLM
Service:eDirectory Event

Syntax

    #include <nwdsdsa.h> 
    #include <nwdsevnt.h> 
     
    N_EXTERN_LIBRARY (NWDSCCODE)  NWDSERegisterForEventResult  ( 
       nint      priority,  
       nuint32   type, 
       nint      (*handler)( 
           nuint32   type, 
           nuint     size, 
           nptr     *data, 
           nint     *result), 
       nint     *flags);

Parameters

priority
(IN) Specifies the state the eDirectory event will be in when it is reported (see Section 5.1, Event Priorities).
type
(IN) Specifies the type of the event for which the callback is being registered (see Section 5.2, Event Types).
handler
(IN) Points to a function to be used as a callback when the event specified by type occurs.
flags
(IN) Points to a function to be used as a callback when the event specified by type occurs.

Return Values

0x0000

Successful

Negative Value

Negative values indicate errors. For error values, see NDS Return Values (NDK: Novell eDirectory Core Services).

Remarks

The handler parameter is a pointer to a function that is to be called when the specified eDirectory event occurs. The function is defined as follows:

type
(IN) Identifies the type of the event that has occurred. (See the type parameter above.)
size
(IN) Specifies the size of the data that is returned for the event.
data
(IN) Points to the location of the data that contains information related to the event. See Section 5.2, Event Types for a list of the events and the structures associated with them.
result
(IN) Points to the location of the data that contains information related to the result of the event, whether an error code or success.

flags can be one of the following values:

HF_ALL 0x0000

Invoke handler regardless of event status.

HF_DEAD 0x0001

This handler is dead (not passed by the user).

HF_AUDIT 0x0002

This handler is the audit handler.

HF_SUCCESS_ONLY 0x0004

Invoke handler if event is successful.

HF_FAIL_ONLY 0x0008

Invoke handler if event fails.

HF_SUCCESS_ONLY and HF_FAIL_ONLY are mutually exclusive. If they are used together, no events will be passed to this handler.

The value returned by the callback must be 0 for success and any other value for failure. If the callback returns a nonzero value during a EP_INLINE priority event, the event will be aborted. The callback’s return values for the EP_JOURNAL and EP_WORK priority events are ignored.

WARNING:Your application must not modify the data at the location pointed to by data. Multiple callbacks can be registered for each event, and all of the callbacks receive that same data. When a callback returns, the information pointed to by data is passed into the next callback, if one is registered. Changing the information pointed to by data can produce unpredictable behavior in other callbacks. If you are going to modify the information pointed to by data, make a local copy of the information.

The callbacks are run on threads that do not have CLIB context. If you are using functions that need CLIB context, you must establish the context by calling SetThreadGroupID (NLM Threads Management).

See Also

NWDSEUnRegisterForEvent, NWDSERegisterForEvent