For the sake of simplicity, the readStream function reads a "Login Script" attribute value, which is a common, optional attribute that can be added to User objects. However, the readStream function is an example of how to read any SYN_STREAM type of attribute value. To read another attribute type (SYN_STREAM syntax), just change the attribute name in the NWDSOpenStream below.

All NDAP NDS C APIs require a reference to a context data structure as a parameter. The application-defined routine getRootContext( ) is called to obtain a context pointing to the root of the target tree and initialized to communicate over the authenticated connection that was obtained at login. Because the context points to root, it allows us to fully specify the object to be acted upon with the objectName parameter in our NDS calls. See Managing Contexts for more information on the code used in these examples to initialize client context.

All attributes whose syntax is SYN_STREAM must be accessed by first calling NWDSOpenStream to retrieve a file handle, used for accessing the attribute's value. The returned handle is a file handle that is appropriate for the platform on which the application is running. This file handle can be used to access the attribute value through the platform's standard file I/O functions.

If the attribute has never been initialized, NWDSOpenStream will return ERR_NO_SUCH_VALUE. The attribute can be initialized when the object is created (NWDSAddObject) or afterwards with the NWDSModifyObject function. Set the attribute's value to NULL.

Close the file handle by calling the platform's file close function.

You must use the file I/O functions that are appropriate for the platform on which the application is running. For DOS, call read, write, close, and seek. For Windows, call _lread, _lwrite, _lclose, and _llseek.

Note: The normal method of reading attribute values is to use the NWDSGetAttrVal function. However, attribute values that are of syntax SYN_STREAM are not accessed by NWDSGetAttrVal. When reading the attributes of an object that has a stream attribute (such as Login Script), NWDSGetAttrVal returns a zero-length octet string for the value of the stream attribute.

The prototype for NWDSOpenStream is shown below:

 (NWDSCCODE) NWDSOpenStream (NWDSContextHandle context, pnstr8 objectName, pnstr8 attrName, nflag32 flags, NWFILE_HANDLE streamBfr);

context Specifies the NDS context for the request.

objectName The name of the object possessing the attribute to be read.

attrName The name of the attribute to be read.

flags Specifies the mode in which the stream should be opened:

0x00000001L - DS_READ_STREAM

0x00000002L - DS_WRITE_STREAM

streamBfr Obtains the file handle appropriate for the platform from which the API is being called.

Note: Non-zero return values from NWDSOpenStream indicate an error. To understand handling client side NDS errors, refer to handling_errors.