RegisterForEvent

Registers an operation to be called when the specified event occurs

Local Servers:blocking

Remote Servers:N/A

Classification:3.x, 4.x, 5.x, 6.x

Service:Advanced

Syntax

  #include <nwadv.h>  
   
  extern LONG RegisterForEvent  (  
     LONG   eventType,   
     void (*reportProcedure) 
     (  
        LONG   parameter,  
        LONG   userParameter 
     ), 
     LONG (*warnProcedure) 
    (  
        void (*OutputRoutine) 
        (  
            void  *controlString,  ... 
        ), 
        LONG   parameter, 
        LONG   userParameter) 
    ));

Parameters

eventType: (IN) Specifies an event type.
reportProcedure: (IN) Points to the events that occurred.
warnProcedure: (IN) Points to a warn procedure (optional).

Return Values

RegisterForEvent returns a nonzero event handle if successful. Otherwise, it returns EFAILURE (-1).

Remarks

The warning procedure pointed to by warnProcedure returns zero or nonzero. If nonzero, you are given a choice to unload.

The function registered by RegisterForEvent runs as a callback-an OS Thread-and is not able to call most of the NetWare APIs (unless it is given a CLIB context).

For 3.11 NLM applications, you must manually create the thread group context in your command parser by calling SetThreadGroupID and passing a valid thread group ID. Before this thread returns, you should reset its context to its original context, by setting the thread group ID back to its original value.

For 4.x, 5.x, and 6.x NLM applications, the context that is given to the callbacks when they are registered is determined by the value in the registering thread’s context specifier:

NO_CONTEXT The registered callback function is not given a CLIB context. Without a CLIB context, the callback function is able only to call NetWare APIs that manipulate data or manage local semaphores.
USE_CURRENT_CONTEXT The registered callback function have the thread group context of the registering thread.
A valid thread group ID is used when you want the callbacks to have a different thread group context than the thread that schedules them.

When a new thread is started by calling BeginThread, BeginThreadGroup or ScheduleWorkToDo, its context specifier is set to USE_CURRENT_CONTEXT by default.

You can determine the current setting of the registering thread’s context specifier by calling GetThreadContextSpecifier. Call SetThreadContextSpecifier to set the registering thread’s context specifier to one of the above options.

What parameter is set to, whether the event calls a warn routine, whether or not the event can sleep, and each event's description follow:

#	Event: Description	Warn routine	Sleep
0	EVENT_VOL_SYS_MOUNT: parameter is undefined. Report Routine is called immediately after the SYS: volume has been mounted.	No	Yes
1	EVENT_VOL_SYS_DISMOUNT: parameter is undefined. Warn Routine and Report Routine are called before the SYS:volume is dismounted.	Yes	Yes
2	EVENT_ANY_VOL_MOUNT: parameter is a volume number. Report Routine is called immediately after any volume is mounted.	No	Yes
3	EVENT_ANY_VOL_DISMOUNT: parameter is a volume number. Warn Routine and Report Routine are called before any volume is dismounted.	Yes	Yes
4	EVENT_DOWN_SERVER: parameter is undefined. Warn Routine and Report Routine are called before the server is shut down.	Yes	Yes
7	EVENT_EXIT_TO_DOS: parameter is undefined. Report Routine is called before the server exits to DOS (NetWare 4.x, 5.x, and 6.x only).	No	Yes
8	EVENT_MODULE_UNLOAD: parameter is a module handle. Warn Routine and Report Routine are called when a module is unloaded from the console command line. Only Report Routine is called when a module unloads itself (see Using the MODULE_UNLOAD Event: Example (NDK: Sample Code)).	Yes	Yes
9	EVENT_CLEAR_CONNECTION: parameter is a connection number. Report Routine is called before the connection is cleared.	No	Yes
10	EVENT_LOGIN_USER: parameter is a connection number. Report Routine is called after the connection has been allocated.	No	Yes
11	EVENT_CREATE_BINDERY_OBJ: parameter is an object ID. Report Routine is called after the object is created and entered in the bindery.	No	No
12	EVENT_DELETE_BINDERY_OBJ: parameter is an object ID. Report Routine is called before the object is removed from the bindery.	No	No
13	EVENT_CHANGE_SECURITY: parameter is a pointer to EventSecurityChangeStruct. Report Routine is called after a security equivalence change has occurred.	No	No
14	EVENT_ACTIVATE_SCREEN: parameter is a screen ID. Report routine is called after the screen becomes the active screen (NetWare 4.x, 5.x, 6.x only).	No	No
15	EVENT_UPDATE_SCREEN: parameter is a screen ID. Report routine is called after a change is made to the screen image (NetWare 4.x, 5.x, and 6.x only).	No	No
16	EVENT_UPDATE_CURSOR: parameter is a screen ID. Report routine is called after a change to the cursor position or state occurs (NetWare 4.x, 5.x, and 6.x only).	No	No
17	EVENT_KEY_WAS_PRESSED: parameter is undefined. Report routine is called at interrupt time whenever a key on the keyboard is pressed (including shift/alt/control).	No	No
18	EVENT_DEACTIVATE_SCREEN: parameter is a screen ID. Report routine is called when the screen becomes inactive (NetWare 4.x, 5.x, and 6.x only).	No	No
19	EVENT_TRUSTEE_CHANGE: parameter is a pointer to EventTrusteeChangeStruct. Report Routine is called everytime there is a change to a trustee in the file system.	No	No
20	EVENT_OPEN_SCREEN: parameter is the screen ID for the newly created screen. Report Routine is called after the screen is created (NetWare 4.x, 5.x, and 6.x only).	No	Yes
21	EVENT_CLOSE_SCREEN: parameter is the screen ID for the screen that is to be closed. Report Routine is called before the screen is closed (NetWare 4.x, 5.x, and 6.x only).	No	Yes
22	EVENT_MODIFY_DIR_ENTRY: parameter is a pointer to EventModifyDirEntryStruct which contains the modify information. Report Routine is called right after the entry is changed and before the directory entry is unlocked.	No	No
23	EVENT_NO_RELINQUISH_CONTROL: parameter is the running process. Report Routine is called when the timer detects that a process is hogging the processor (NetWare 4.x, 5.x, and 6.x only).	No	No
25	EVENT_THREAD_SWITCH: parameter is the thread's ID that was executing when the thread switch occurred. Report Routine is called when the new thread begins executing (applies only to threads in the calling NLM).	No	No
27	EVENT_MODULE_LOAD: parameter is module handle. Report Routine is called after a module has loaded (NetWare 4.x, 5.x, and 6.x only).	No	Yes
28	EVENT_CREATE_PROCESS: parameter is the PID of the process being created. Report Routine is called after the process is created (NetWare 4.x, 5.x, and 6.x only).	No	No
29	EVENT_DESTROY_PROCESS: parameter is the PID of the process being destroyed. Report Routine is called before the process is actually destroyed (NetWare 4.x, 5.x, and 6.x only).	No	No
32	EVENT_NEW_PUBLIC: parameter is a pointer to a length preceded string containg the name of the new public entry point (NetWare 4.x, 5.x, and 6.x only).	No	No
33	EVENT_PROTOCOL_BIND: parameter is a pointer to EventProtocolBindStruct. This event is generated every time a board is bound to a protocol (NetWare 4.x, 5.x, and 6.x only).	No	Yes
34	EVENT_PROTOCOL_UNBIND: parameter is a pointer to EventProtocolBindStruct. This event is generated every time a board is unbound from a protocol (NetWare 4.x, 5.x, and 6.x only).	No	Yes
37	EVENT_ALLOCATE_CONNECTION: parameter is a connection number. Report Routine is called after the connection is allocated (NetWare 4.x, 5.x, and 6.x only).	No	Yes
38	EVENT_LOGOUT_CONNECTION: parameter is a connection number. After NetWare 5.1, any NLM that is registered for EVENT_LOGOUT_CONNECTION will still be called; but the connection will be logged out at that point.	No	Yes
39	EVENT_MLID_REGISTER: parameter is a board number. Report Routine is called after the MLID software is registered (NetWare 4.x, 5.x, and 6.x only).	No	No
40	EVENT_MLID_DEREGISTER: parameter is a board number. Report Routine is called before the MLID is deregistered (NetWare 4.x, 5.x, and 6.x only).	No	No
41	EVENT_DATA_MIGRATION: parameter is a pointer to EventDateMigrationInfo. This event is generated when a file’s data has been migrated (NetWare 4.x, 5.x, and 6.x only).	No	No
42	EVENT_DATA_DEMIGRATION: parameter is a pointer to EventDateMigrationInfo. This event is generated when a file’s data has been de-migrated (NetWare 4.x, 5.x, and 6.x only).	No	No
43	EVENT_QUEUE_ACTION: parameter is a pointer to EventQueueNote. This event is generated when a queue is activated, deactivated, created, or deleted (NetWare 4.x, 5.x, and 6.x only).	No	No
44	EVENT_NETWARE_ALERT: parameter is a pointer to EventNetwareAlertStruct. SystemAlert, QueueSystemAlert, INWSystemAlert, and INWQueueSystemAlert (all NetWare 3.x only) call NetWareAlert which generates this NetWare 4.x, 5.x, and 6.x event.	No	Yes
50	EVENT_CLOSE_FILE: parameter is a pointer to EventCloseFileInfo (NetWare 4.x, 5.x, and 6.x only).	No	No
51	EVENT_CHANGE_TIME	No	No
56	EVENT_MODULE_UNLOADED	No	Yes
57	EVENT_REMOVE_PUBLIC	No	Yes
60	EVENT_SFT3_SERVER_STATE	No	No
61	EVENT_SFT3_IMAGE_STATE	No	No
62	EVENT_SFT3_PRESYNC_STATE	No	Yes

Use event 44, EVENT_NETWARE_ALERT, in place of event 24, EVENT_SYS_ALERT.

To register for NDS events, call NWDSERegisterForEvent (NDK: eDirectory Event Services).

RegisterForEvent

Syntax

Parameters

Return Values

Remarks

See Also