The Novell Directory Services (NDS) NCPs enable clients to communicate with the server, send or receive fragments, and manage connection status information.
This introduction is divided into the following sections:
The Attribute structure shown below and referred to repeatedly throughout this document contains a parameter attrValue[] whose type definition is the any_t base type.
struct Attribute
{
unicode AttrName;
any_t AttrValue[];
};
This type means that an attribute value is encoded based on the syntax of the attribute. For example, as shown in the section of this chapter entitled Attribute Syntaxes: NCP Encoding Rules, the syntax of the Back Link attribute is the following:
int32 length; int32 remoteID; unicode serverName;
Each syntax (Back Link, Boolean, Case Exact String, etc.) has its own encoding. Therefore, any_t denotes one of the defined encoded syntaxes. For example, a developer who fills in the Attribute structure (shown earlier) with the Back Link attribute, would produce the following:
struct Attribute
{
unicode Back Link; //attribute name
int32 length; //this and all fields below make up attrValue
int32 remoteID;
unicode serverName;
};
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (7) byte
Reply Format
Offset Content Type (reply header)
Completion Codes
0 0x00 Success 254 0xFE BAD_PACKET
Remarks
This NCP clears the statistics that can be reported by the NCP Return Statistics (0x2222 104 06)
See Also
Return Statistics (0x2222 104 06)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (7) byte 8 FraggerHandle LONG (Lo-Hi)
Reply Format
Offset Content Type (reply header)
Completion Codes
0 0x00 Success 255 0xFF FAILURE
Remarks
This NCP closes the FraggerHandle obtained by calling NCP (Send NDS Fragmented Request/Reply 0x2222 104 02)
See Also
Send NDS Fragmented Request/Reply 0x2222 104 02
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (5) byte
Reply Format
Offset Content Type (reply header)
Completion Code
0 0x00 Success 251 0xFB 254 0xFE BAD_PACKET
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (1) byte 8 Reserved (0) byte[3]
Reply Format
Offset Content Type (reply header) 8 PingVersion long (Lo-Hi) 12 TreeName unicode xx RootMostEntryDepth long (Lo-Hi)
Completion Code
0 0x00 SUCCESS 251 0xFB NDS NCP not AVAILABLE 254 0xFE BAD_PACKET
Remarks
This NCP allows a client to query the server. The caller gets back a the ping version number, the tree name, the DS version, and the distance from the root of the root most entry on that server.
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (8) byte
Reply Format
Offset Content Type (reply header) 8 Status Int4 12 Flags (0) Int4
Completion Codes
0 0x00 Success 254 0xFE BAD_PACKET
Remarks
This NCP allows a supervisor with sufficient privileges to reload and restart the NDS software. There is no interruption of service. The Status field returned is zero for success; otherwise, it is nonzero.
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (4) byte
Reply Format
Offset Content Type (reply header) 8 length long 12 binderyContext unicode (Lo-Hi)
Completion Code
0 0x00 SUCCESS 254 0xFE BAD_PACKET
Remarks
This NCP allows you to get the bindery context. The reply format includes two fields: a length field (that precedes and specifies the length of the bindery context) and the binderyContext field (of type unicode). The type unicode means that each character in the string of characters that compose the binderyContext are each 16 bits. The first of the 16 bits holds the character itself and the second byte holds the NULL terminator. For example, if the bindery context were the following:
O=Novell
the content of the binderyContext field (of type unicode) would be the following:
O=NOVELL
Note that each character is NULL terminated, and that the string as a whole is NULL terminated. The NULL termination for the string as a whole is 16 bits; therefore, each byte of the last 16 bits is filled with a NULL.
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (6) byte 8 RequestFlags (see below) Int4
Reply Format
Offset Content Type (reply header) 8 Statistics (variable) Int4
Request Flags
Each flag corresponds to a statistic that is available to be returned.
| 0x00000001 | Output Fields |
|---|---|
| 0x00000002 | No Such Entry |
| 0x00000004 | Local Entry |
| 0x00000008 | Type Referral |
| 0x00000010 | Alias Referral |
| 0x00000020 | Request Count |
| 0x00000040 | Request Data Size |
| 0x00000080 | Reply Data Size |
| 0x00000100 | Transport Referral |
| 0x00000200 | Transport Referral |
| 0x00000400 | Up Referral |
| 0x00000800 | Down Referral |
Completion Code
0 0x00 SUCCESS 254 0xFE BAD_PACKET
Remarks
This NCP reports a number of useful statistics about NDS operation.
Each Request Flag that is set to 1 (one) requests a particular statistic. Each statistic is an Int4. The reply indicates in the Output Fields statistic which Request Flags are being returned. The items both requested and supported appear contiguaously in the reply. The request is invalid if both a) the Request Flags do not include a request for the Output Fields and b) the responding server does not support a requested statistic. Request Flags and statistics can be added in the future.
See Also
Clear Statistics (0x2222 104 07)
| v2.x | v3.x | v4.x | v5.x |
Request Format
Offset Content Type (request header) 6 FunctionCode (104) byte 7 SubFunctionCode (2) byte 8 FraggerHandle long (Lo-Hi) 12 FragSize long (Lo-Hi) 16 TotalRequest long (Lo-Hi) 20 Flags long (Lo-Hi) 24 Verb long (Lo-Hi) 28 ReplyBufferSize long (Lo-Hi) 32 RequestData long (Lo-Hi)
Reply Format
Offset Content Type (reply header) 8 ReplySize long (Lo-Hi) 12 FraggerHandle long (Lo-Hi) 16 ReplyData byte[]
Completion Code
0 0x00 SUCCESS 226 0xE2 TOO_FEW_FRAGMENTS 227 0xE3 TOO_MANY_FRAGMENTS 228 0xE4 PROTOCOL_VIOLATION 229 0xE5 SIZE_LIMIT_EXCEEDED 254 0xFE BAD_PACKET 251 0xFB UNKNOWN_REQUEST 150 0x96 SERVER_OUT_OF_MEMORY 253 0xFD INVALID_PACKET_LENGTH 255 0xFF FAILURE
Remarks
This NCP allows you to send fragmented requests to a server and to receive fragmented replies. As with all NCP requests, the request to Send NDS Fragmented Request/Reply (0x2222 104 02) is composed of the NCP request header information followed by the information for this specific NCP filled in by the developer.
The following request parameters are defined:
The FraggerHandle parameter is intially set to -1.
The FragSize parameter is the number of data bytes that the client is expecting.
The TotalRequest parameter is the total number of bytes in the message.
The Flags field is always set to 0.
The Verb field is the number of the NDS verb that is to be executed.
The ReplyBufferSize is the number of bytes in the reply buffer.
The following reply parameters are defined:
The ReplySize parameter is the size of the reply packet.
The FraggerHandle parameter is the unique identifier assigned by the server. The FraggerHandle parameter could change with each fragment received, so make sure this number is copied to the next request header. When FraggerHandle is -1L, there is no more data to receive.
The ReplyData depends on the verb.
These Encoding Rules define the format used to pass an attribute syntax over the network. The following Attribute Syntaxes are described:
NCP encoding rules define the format used to pass an attribute syntax over the network.
Syntax
int32 length; int32 remoteID; tdr_str serverName;
Remarks
The Directory uses the Back Link syntax for the Back Link attribute, which the Directory uses for its internal management.
Syntax
int32 length; int8 boolean;
Remarks
The Directory uses the Boolean syntax when an attribute's values represent true or false. To Directory Services, one (1) represents true and and zero represents false.
Syntax
tdr_str caseExactString;
Remarks
The Directory uses the Case Exact String syntax when an attribute's value is a string for which the case (upper or lower) is significant when performing comparisons.
Two case exact strings match for equality when they have the same length and their corresponding characters are identical. Leading spaces, trailing spaces, and multiple consecutive internal spaces are not treated as significant. (Multiple consective internal spaces are treated as a single space character.) The Directory may omit insignificant spaces when storing an attribute value.
Syntax
tdr_str caseIgnoreStringList[];
Remarks
The Directory uses the Case Ignore List syntax when the attribute's value is a sequence of case ignore strings.
Two case ignore lists match for equality if and only if the number of case ignore strings in each list is the same and their corresponding strings match according to the rules of equality for case ignore strings.
Syntax
tdr_str caseIgnoreString;
Remarks
The Directory uses the Case Ignore String syntax when an attribute's value is a string for which the case (upper or lower) is not significant when performing comparisons.
Two case ignore strings match for equality when they have the same length and their corresponding characters are identical in all respects except that of case. Leading spaces, trailing spaces, and multiple consecutive internal spaces are not treated as significant. (Multiple consective internal spaces are treated as a single space character.) The Directory may omit insignificant spaces when storing an attribute value.
Syntax
tdr_str className;
Remarks
The Directory uses the Class Name syntax when an attribute's value is an object class name. The matching rule for a Class Name value is the same as the one for Case Ignore String.
Counter
Syntax
int32 length; int32 integer;
Remarks
The Directory uses the Counter syntax for attributes that are used to count. For example, the Counter syntax is used to keep track of the number of grace logins used.
Attributes defined using the Counter syntax are singled-valued. The difference between the Counter syntax and the Integer syntax is that the values increase or decrease th total of that attribute (rather than simply zeroing out the old value and changing it to the new value.)
Syntax
tdr_str distinguishedName;
Remarks
The Directory uses the Distinguished Name syntax when an attribute's value is the name of an object in the directory tree.
Syntax
int8 octetString[];
Remarks
The Directory uses the Email Address syntax when an attribute's value is an email address on the network.
Syntax
int32 length; //total length tdr_str telephoneNumber; int32 bitcount; //bitcount / 8 = number of parameter bytes int32 parameterLen[]; int8 parameters[]; //number of bytes determined using previous formula
Remarks
The Directory uses the Facsimile Telephone Number syntax when an attribute's value is a string that complies with the internationally desginated format for showing telphone numbers, E.123, and an optional bit string formatted according to Recommendation T.30.
The Directory matches Facsimile (Fax) Telephone Numbers based on the telephone number field. The rules for matching fax telephone numbers are identical to those for the Case Exact String syntax except that the Directory skips all space and hyphen (-) characters during the comparison.
Syntax
int32 length; int32 amount; tdr_str dn;
Remarks
The Directory uses the Hold syntax when an attribute's value represents an object name/level amount.
Syntax
int32 length; int32 integer;
Remarks
The Directory uses the Integer syntax when an attribute's value is an integer (unless you need a counter; if so, use the Counter syntax). Two Integer attribute values match for equality if they are the same. The ordering rules for integers apply.
Syntax
int32 length; int32 integer;
Remarks
The Directory uses the Interval syntax when an attribute's value represents an interval of time.
Syntax
int32 length; //length of address + 4 int32 addressType; int8 address[];
Remarks
The Directory uses the Net Address syntax for network addresses in the NetWare environment. The address type indicates the type of communications protocol used (for example, IPX or AppleTalk).
Two Net Address attribute values match for equality if the type, length, and value of the network address match. The address length is expressed in bytes. Since the address itself is stored as a binary string, each 4-bit nibble must be converted to the correct hexadecimal character before the address can be displayed as a hexidecimal address.
Syntax
tdr_str numericString;
Remarks
The Directory uses the Numeric String syntax when an attribute's value is a numeric string as defined in CCITT X.208.
Two Numeric String attribute values match for equality if the strings are the same length and their corresponding characters are identical. The numeric string character set consists of the digits 0 through 9 and the space character.
During comparisons of numeric strings, the Directory skips all spaces. Since spaces are insignificant for these comparisons, the Directory may omit them when storing a Numeric String attribute value.
Syntax
int32 length; //total length of ACL entry tdr_str protectedAttrName; tdr_str subjectName; int32 privileges;
Remarks
The Directory uses the Object ACL syntax when an attribute's value is an access control list entry.
An object ACL value can protect either an object or an attribute. The protected object is always the one which contains the ACL attribute.
The Object ACL syntax supports both matching for equality and approximate matching. The difference between matching for equality and approximate matching concerns the privileges field of the comparison value. When matching for equality, the privilege set must match exactly for the comparison to succeed. When matching approximately, any bits in the privilege field in the filter which are set must also be set in the target. The comparison ignores other bits in the target.
Values with the same protectedAttrName and subjectName are considered to be duplicate values and so are not permitted.
Syntax
octectString octetStringlist[];
Remarks
The Directory uses the Octet List syntax when the attribute's value is an ordered sequence of octet strings. A presented octet list matches a stored list if the presented list is a subset of the stored list.
Syntax
int8 octetString[];
Remarks
The Directory uses the Octet String syntax when the attribute's value is an octet string.
Two octet strings match if they are the same length and their corresponding bit sequences (octets) are identical. The comparison operation uses the first pair of octets that do not match to determine the order of the strings.
Syntax
int32 totalLength; int32 nameSpaceType; tdr_str volumeDN; int8 address[];
Remarks
The Directory uses the Path syntax when an attribute's value is a file system path. The Directory compares the string represented by address using the same rules as those for the Case Exact String syntax.
Syntax
tdr_str caseIgnoreStringList[];
Remarks
The Directory uses the Postal Address syntax when an attribute's value is a postal address. An attribute value for a Postal Address attribute typically includes selected attributes from the MHS Unformatted Postal O/R Address version 1 according to Recommendation f.401. The value is limited to six lines of 30 characters each, including a Postal Country name. Normally the information contained in such an address could include the following elements:
The items included in the address depend on the specific requirements of the named object.
The matching rules for Postal Address values are the same as those for Case Ignore List.
The count of the string must equal 6.
Syntax
tdr_str printableString;
Remarks
The Directory uses the Printable String syntax when an attribute's value is a printable string as defined in CCITT X.208. The case (upper or lower) is significant when comparing printable strings.
Two printable strings match for equality when they have the same length and their corresponding characters are identical. Leading spaces, trailing spaces, and multiple consecutive internal spaces are not treated as significant. (Multiple consective internal spaces are treated as a single space character.) The Directory may omit insignificant spaces when storing an attribute value.
The printable string character set contains the following characters:
Syntax
int32 length; //total length of replica pointer in bytes
tdr_str replicaServerName;
int32 replicaType;
int32 replicaNumber;
Referral address[];
struct Referral
{
int32 type;
int8 address[];
}
Remarks
The Directory uses the Replica Pointer syntax when an attribute's value represents a partition replica.
Each value of this syntax is composed of four parts:
When the Directory matches Replica Pointer values, it compares only the replicaServerName field.
Syntax
int8 octetString[];
Remarks
The Directory uses the Stream syntax for attributes whose values might exceed the maximum allowed value size. Any attribute defined with this syntax is single-valued.
Syntax
tdr_str telephoneNumberString;
Remarks
The Directory uses Telephone Number syntax when an attribute's value is a telephone number. The rules for matching telephone number are identical to those for the Case Exact attribute syntax except that all space and hyphen (-) characters are skipped during the comparison.
Syntax
int32 length; int32 integer;
Remarks
The Directory uses the Time syntax when an attribute's value represents time.
A Time value consists of a whole number of seconds, where zero equals 12:00 midnight (a.m.), Janauary 1, 1970, GMT.
The Directory compares two Time values by comparing the integer values.
Syntax
int32 length; //length = 8 int32 seconds; int16 replicaNumber; int16 event;
Remarks
The Directory uses the Timestamp attribute when an attribute's value marks the time when a particular event occurred or will occur.
A Timestamp value consists of a whole number of seconds, where zero equals 12:00 midnight (a.m.), January 1, 1970, GMT. The event is an integer which further orders events occurring within the same whole-second interval.
The Directory compares two Timestamp fields by comparing first the second fields and then the event fields. If the seconds are unequal, the Directory determines order by that field alone. The order of comparison is as follows:
The Directory compares until one of these fields is not equal.
Syntax
int32 length; int32 level; int32 interval; tdr_str dn;
Remarks
The Directory uses the Typed Name syntax when an attribute's values represent a level and an interval associated with an object.
The level of the attribute indicates its priority. The interval indicates the frequency of reference.
The level and interval values are user assigned and interpreted. To be effective they must be implemented by the user, who can use them to implement iterative intervals or enforce priority.
Syntax
int8 octetString[];
Remarks
The Directory uses the Unknown syntax for attributes whose attribute definition was deleted from the schema. An Unknown syntax cannot be matched.