Novell Directory Services Q & A

Articles and Tips: article

KEVIN BURNETT
Developer Support Engineer
Developer Support

01 Jul 1997

Q & A

Q. I am using Novell's Directory Services (NDS) Event Services. I realize that NDS Event Services are services that allow NLM applications to request notification of specific NDS events. I also realize that these services will allow NLM applications to register one or more functions that will be called a s callbacks when specific events occur. What are the actual Application Programming Interfaces (APIs) that are available for doing these Event Services?

A. The following APIs are some of the more important functions that can be used for registering NDS Events:

API	Description
NWDSERegisterForEvent	Registers a function to be used as a callback when a specific NDS event occurs.
NWDSEUnRegisterForEvent	Unregisters a callback that has been registered to be called when a specific NDS event occurs.
NWDSEConvertEntryName	Converts the object names returned in the DSEEntryInfo structure to a form that is consistent with the NWDS... functions.
NWDSEGetLocalAttrID	Retrieves the local ID of a specified Schema attribute.
NWDSEGetLocalClassID	Retrieves the local ID for the specified object class.
NWDSEGetLocalClassName	Retrieves the name of the Schema object class that is associated with the supplied local ID.
NWDSEGetLocalEntryID	Retrieves the local ID for the specified Directory object.
NWDSEGetLocalEntryName	Retrieves the name of the Directory object that is associated with the supplied local ID.

Q. Along these same lines, I have never programmed using Novell's NDS Event Services. Since I know the required NLMs ship with the Novell SDK Release 9 and later, what are the steps are required to use NDS Event Services?

A. The following steps are a high-level perspective of the steps that an NDS event-monitoring application will take:

Before registering for any events, the NLM application should use the appropriate helper functions to determine the IDs for the desired objects, object classes and attributes that will be monitored.
The NLM application calls NWDSERegisterForEvent to register a function that will be used as a callback when a specific event occurs. The application calls NWDSERegisterForEvent for each event it wants to monitor.
When the specified event occurs, such as the creation of an object, the callback is called and given data about the event.
The callback determines if it wants to use the data. If it does, it either immediately processes the data, or makes a local copy of the data and stores the local copy. Then the callback returns.
If the callback has saved a local copy of the data so it can be processed by another thread, the processing thread processes the event's data.
When the NLM application no longer wants information about an event, it uses NWDSEUnRegisterForEvent to remove its callbacks from the notification lists. The application must call NWDSEUnRegistereForEvent for each event for which it has registered.

Q. What are some of the NDS Events that I can monitor from my NLM application?

A. The list of events that can be monitored are as follows:

Event	Description
DSE_CREATE_ENTRY	Creation of a new Directory object.
DSE_DELETE_ENTRY	Deletion of an existing Directory object.
DSE_RENAME_ENTRY	Renaming of an existing Directory object.
DSE_MOVE_SOURCE_ENTRY	This is the second of two events reported for a move operation. This event specifies the deletion of a Directory object from its original location in the Directory tress. (See DSE_MOVE_DEST_ENTRY.)
DSE_ADD_VALUE	Addition of a value to an object attribute.
DSE_DELETE_VALUE	Deletion of a value from an object attribute.
DSE_CLOSE_STREAM	Closing of a Stream attribute
DSE_DELETE_ATTRIBUTE	Deletion of an attribute. This generates DSE_DELETE_VALUE events for values associated with the attribute. The DSE_DELETE_VALUE events occur after the DSE_DETELE_ATTRIBUTE event.
DSE_SET_BINDERY_CONTEXT	Setting of the bindery context on the server.
DSE_CERATE_BINDERY_OBJECT	Creation of a bindery object.
DSE_DELETE_BINDERY_OBJECT	Deletion of a bindery object.
DSE_MOVE_DEST_ENTRY	This is the first of two events reported for a move operation. This event specifies the placement of the Directory object into its new location in the Directory tree. (See DSE_MOVE_SOURCE_ENTRY.) This generates DSE_ADD_VALUE events for all of the values associated with the object.
DSE_DELETE_UNUSED_EXTREF	Deletion of an unused external reference.
DSE_TRACE	Occurrence of an NDS Trace event.
DSE_REMOTE_SERVER_DOWN	Remote server, where request was destined, is down.
DSE_NCP_RETRY_EXPENDED	Request could not be completed due to NCP timeout.
DSE_REMOTE_CONN_CLEARED	A remote connection has been cleared.

Q. Since all of NDS's request data is carried out in Unicode format, I have had to useNWLocalToUnicode and NWUnicodeToLocalto work with the data I receive from calling NDS Event Services APIs. I have noticed that NWLocalToUnicodeand NWUnicodeToLocalare documented in Novell's SDK Release 11 as having a seventh parameter called allowNoMapFlag. allowNoMapFlagis documented as being able to be set to two values. It specifies whether to use the map character. You can pass in either USE_NOMAP_CHARor DONT_USE_NOMAP_CHAR. What I am seeing is that regardless of which flag I pass in, the value is always set to USE_NOMAP_CHAR. What is happening?

A. The seventh parameter for NWLocalToUnicode and NWUnicodeToLocal should never have been published. This was an oversight on Novell's part. The history about this is as follows: a Novell Engineer needed specific functionality for the NetWare Operating System. He modified the internal procedures that NWLocalToUnicodeand NWUnicodeToLocal call to include the seventh parameter for the NetWare Operating System's exclusive use. This seventh parameter governs what happens when an error occurs during the conversion of a Unicode string to ASCII and vice-versa. The flag allows either an error to be returned (DONT_USE_NOMAP_CHAR) or no error to be returned and a special character to be placed, in the string, where the error was encountered (USE_NOMAP_CHAR). This functionality was intended for internal Novell use only.

Novell's Cross-Platform libraries convert the internal seven parameters of NWLocalToUnicodeand NWUnicodeToLocal to the original six parameters via a macro found in UNICODE.H:

#if !defined(EXCLUDE_UNICODE_NLM_COMPATIBILITY_MACROS)
#define NWLocalToUnicode(P1,P2,P3,P4,P5,P6) NWLocalToUnicode(P1,P2,P3,P4,P5,P6, 1)
#define NWUnicodeToLocal(P1,P2,P3,P4,P5,P6) NWUnicodeToLocal(P1,P2,P3,P4,P5,P6, 1)
#endif

This macro hard-codes the seventh parameter to 1 causing the USE_NOMAP_CHAR flag to be used all the time.

Note: The Novell SDK documentation will be fixed to reflect these changes.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.