The NWDSAddObject function is used to add nodes to an NDS™ directory. If those nodes are container class objects, they can subsequently have objects attached to them. When calling this function, it is important to know the context of the object and the name you are going to give it, and to have a buffer prepared containing all required data for the object. The NWDSAddObject function has the following syntax:
NWDSCCODE N_API NWDSAddObject(
NWDSContextHandle context, /* (IN) Indicates the
eDirectory context
for the request.*/
pnstr8 *objectName, /* (IN) Points to the name
of the object to be
added.*/
pnint_ptr *iterationHandle, /* (IN) */
nbool8 more, /* (IN) */
pBuf_T objectInfo); /* (IN) Points to a request
buffer containing the
attributes and values for
the new object. */
The context and objectName parameters are fairly self-explanatory. The objectInfo parameter points to a buffer, which is set up using NWDSAllocBuf and NWDSInitBuf.
The NWDSAllocBuf function is used to allocate an eDirectory buffer. This buffer can be of varying sizes, depending on your needs and preferences. However, Novell® has defined in nwdsdc.h two constants that are typically used with the size parameter of this function: DEFAULT_MESSAGE_LEN (4069) and MAX_MESSAGE_LEN (64512). The NWDSAllocBuf function has the following syntax:
NWDSCCODE N_API NWDSAllocBuf(
size_t size, /* (IN) Indicates the number of bytes to
allocate to the buffer.*/
ppBuf_T buf); /* (OUT) Points to an Buf_T containing the
memory allocated for the buffer.*/
The NWDSInitBuf function is used to initialize an eDirectory buffer for an eDirectory request. Output buffers do not need to be initialized. For example, if you were calling NWDSRead and wanted all of the information for a particular object, you would not need to initialize a buffer. If, however, you wanted to request only specific information (a specific attribute), you would have to initialize a request buffer.
The NWDSInitBuf function has the following syntax:
NWDSCCODE N_API NWDSInitBuf(
NWDSContextHandle context, /*(IN) Indicates the eDirectory
context for the request.*/
nuint32 operation, /*(IN) Indicates the eDirectory
operation for which
the buffer is being
initialized.*/
pBuf_T buf); /*(IN) Points to the buffer being
initialized.*/
When calling NWDSInitBuf, you must specify the context handle and the buffer. You must also specify the intended use (allocation type) of the buffer in the operation parameter. See Section 5.3, Buffer Operation Types and Related Functions for a list of operation types. For the NWDSAddObject function, the operation type is DSV_ADD_ENTRY.
After the buffer has been created and initialized, you are ready to add the information to the buffer to create the new object. This is done by calling the NWDSPutAttrName and NWDSPutAttrVal functions. When you fill the buffer, you create a structure that logically looks something like this: attribute name — attribute value — attribute name — attribute value —.... Use alternating calls to NWDSPutAttrName and NWDSPutAttrVal. The following code segment demonstrates how you might use these functions before adding a new user.
ccode=NWDSPutAttrName(dContext,inBuf,"Object Class");
/* error checking goes here */
ccode=NWDSPutAttrVal(dContext,inBuf,SYN_DIST_NAME,"User");
/* error checking goes here */
ccode=NWDSPutAttrName(dContext,inBuf,"Surname");
/* error checking goes here */
ccode=NWDSPutAttrVal(dContext,inBuf,SYN_CI_STRING,"Smith");
/* error checking goes here */
The NWDSPutAttrName function has the following syntax:
NWDSCCODE N_API NWDSPutAttrName(
NWDSContextHandle context, /*(IN) Indicates the NDS context
for the request.*/
pBuf_T buf, /*(IN) Points to the request
buffer in which to store
the attribute name.*/
pnstr8 attrName); /*(IN) Points to the attribute
name to store in the
request buffer.*/
The NWDSPutAttrVal function has the following syntax:
NWDSCCODE N_API NWDSPutAttrVal(
NWDSContextHandle context, /* (IN) Indicates the NDS context
for the request.*/
pBuf_T buf, /* (IN) Points to the request
buffer being prepared.*/
nuint32 syntaxID, /* (IN) Indicates the data type
of the attribute value.*/
nptr attrVal); /* (IN) Points to the attribute
value to be stored in the
request buffer.*/
The syntaxID parameter contains the data type of the attribute value. This data type is defined for each attribute in Base Attribute Definitions
. For instance, for the Object Class attribute, the sample code inputs the value User and the type SYN_DIST_NAME. The attribute values and syntax IDs are found in the Attribute Syntax Definitions
. If you are trying to add a User, for example, Base Object Class Definitions
defines the object User
. These definitions (in NDK: Novell eDirectory Schema Reference) list all of the mandatory attributes as well as the optional attributes.
Next, for each of the attributes you want to set, go to Base Attribute Definitions
which contains an entry for each attribute type; for example, the CN (Common Name)
attribute. The definitions specify the syntax (for CN, this is Case Ignore String).
Attribute Syntax Definitions
defines the Case Ignore String
syntax. This gives you not only the information for the syntaxID, or SYN_CI_STRING, but also the form that this attribute takes; in this case, a character pointer. Some attributes take the form of more complex structures.
The buffer must include the attribute name and its value for all mandatory attributes. Names and values for optional attributes can be added to the buffer or added after the object is created.
NOTE:Although the naming attribute for the object is always a mandatory attribute, do not add this attribute to the buffer. The objectName parameter of the NWDSAddObject function takes the value for one naming attribute. If the object has multiple naming attributes, use the objectName parameter for one attribute and add the others to the buffer.
Once you have the buffer set up with the appropriate attributes and values, you are ready to call NWDSAddObject.