-
-
-
-
Network Working Group M. Smith, Editor
INTERNET-DRAFT Netscape Communications Corp.
Intended Category: Standards Track T. Howes
-Obsoletes: RFC 1823 Netscape Communications Corp.
-Expires: 23 August 1999 A. Herron
+Obsoletes: RFC 1823 Loudcloud, Inc.
+Expires: May 2001 A. Herron
Microsoft Corp.
M. Wahl
- Innosoft International, Inc.
+ Sun Microsystems, Inc.
A. Anantha
Microsoft Corp.
- 23 February 1999
+ 17 November 2000
The C LDAP Application Program Interface
- <draft-ietf-ldapext-ldap-c-api-02.txt>
+ <draft-ietf-ldapext-ldap-c-api-05.txt>
1. Status of this Memo
-Expires: 23 August 1999 [Page 1]
+Expires: May 2001 [Page 1]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
2. Introduction
LDAPv3 features such as controls. In addition, other LDAP API changes
were made to support information hiding and thread safety.
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in RFC 2119[1].
+
The C LDAP API is designed to be powerful, yet simple to use. It defines
compatible synchronous and asynchronous interfaces to LDAP to suit a
wide variety of applications. This document gives a brief overview of
2. Introduction...................................................2
3. Table of Contents..............................................2
4. Overview of the LDAP Model.....................................4
-5. Overview of LDAP API Use.......................................4
-6. Header File Requirements.......................................6
-7. Common Data Structures.........................................7
-8. Retrieving Information About the API Implementation............8
-8.1. Retrieving Information at Compile Time......................8
-8.2. Retrieving Information During Execution.....................10
-9. LDAP Error Codes...............................................13
-10. Performing LDAP Operations.....................................14
-10.1. Initializing an LDAP Session................................14
-10.2. LDAP Session Handle Options.................................15
-10.3. Working With Controls.......................................21
-10.3.1. A Client Control That Governs Referral Processing........22
-10.4. Authenticating to the directory.............................22
-10.5. Closing the session.........................................25
-10.6. Searching...................................................26
-10.7. Reading an Entry............................................30
-10.8. Listing the Children of an Entry............................30
-10.9. Comparing a Value Against an Entry..........................30
-10.10. Modifying an entry..........................................32
-10.11. Modifying the Name of an Entry..............................34
-10.12. Adding an entry.............................................36
-
-
-
-Expires: 23 August 1999 [Page 2]
+5. Overview of LDAP API Use and General Requirements..............4
+6. Header Requirements............................................6
+7. Common Data Structures and Types...............................7
+8. Memory Handling Overview.......................................9
+9. Retrieving Information About the API Implementation............9
+9.1. Retrieving Information at Compile Time......................10
+9.2. Retrieving Information During Execution.....................11
+10. Result Codes...................................................14
+11. Performing LDAP Operations.....................................16
+11.1. Initializing an LDAP Session................................16
+11.2. LDAP Session Handle Options.................................17
+11.3. Working With Controls.......................................23
+11.3.1. A Client Control That Governs Referral Processing........24
+11.4. Authenticating to the directory.............................25
+11.5. Closing the session.........................................27
+11.6. Searching...................................................28
+11.7. Reading an Entry............................................32
+
+
+
+Expires: May 2001 [Page 2]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
-10.13. Deleting an entry...........................................38
-10.14. Extended Operations.........................................40
-11. Abandoning An Operation........................................41
-12. Obtaining Results and Peeking Inside LDAP Messages.............42
-13. Handling Errors and Parsing Results............................44
-14. Stepping Through a List of Results.............................47
-15. Parsing Search Results.........................................48
-15.1. Stepping Through a List of Entries or References............48
-15.2. Stepping Through the Attributes of an Entry.................49
-15.3. Retrieving the Values of an Attribute.......................50
-15.4. Retrieving the name of an entry.............................51
-15.5. Retrieving controls from an entry...........................52
-15.6. Parsing References..........................................53
-16. Encoded ASN.1 Value Manipulation...............................54
-16.1. General.....................................................54
-16.2. Encoding....................................................55
-16.3. Encoding Example............................................58
-16.4. Decoding....................................................59
-16.5. Decoding Example............................................61
-17. Security Considerations........................................64
-18. Acknowledgements...............................................64
-19. Copyright......................................................64
-20. Bibliography...................................................65
-21. Authors' Addresses.............................................66
-22. Appendix A - Sample C LDAP API Code............................67
-23. Appendix B - Namespace Consumed By This Specification..........68
-24. Appendix C - Summary of Requirements for API Extensions........69
-24.1. Compatibility...............................................69
-24.2. Style.......................................................69
-24.3. Dependence on Externally Defined Types......................69
-24.4. Compile Time Information....................................69
-24.5. Runtime Information.........................................70
-24.6. Values Used for Session Handle Options......................70
-25. Appendix D - Known Incompatibilities with RFC 1823.............70
-25.1. Opaque LDAP Structure.......................................70
-25.2. Additional Error Codes......................................70
-25.3. Freeing of String Data with ldap_memfree()..................71
-25.4. Changes to ldap_result()....................................71
-25.5. Changes to ldap_first_attribute() and ldap_next_attribute...71
-25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......71
-25.7. API Specification Clarified.................................72
-25.8. Deprecated Functions........................................72
-26. Appendix E - Changes Made Since Last Document Revision.........72
-26.1. API Changes.................................................73
-26.2. Editorial changes...........................................74
-
-
-
-
-
-
-Expires: 23 August 1999 [Page 3]
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+
+11.8. Listing the Children of an Entry............................32
+11.9. Comparing a Value Against an Entry..........................33
+11.10. Modifying an entry..........................................35
+11.11. Modifying the Name of an Entry..............................37
+11.12. Adding an entry.............................................39
+11.13. Deleting an entry...........................................41
+11.14. Extended Operations.........................................43
+12. Abandoning An Operation........................................44
+13. Obtaining Results and Peeking Inside LDAP Messages.............45
+14. Handling Errors and Parsing Results............................47
+15. Stepping Through a List of Results.............................51
+16. Parsing Search Results.........................................51
+16.1. Stepping Through a List of Entries or References............52
+16.2. Stepping Through the Attributes of an Entry.................53
+16.3. Retrieving the Values of an Attribute.......................54
+16.4. Retrieving the name of an entry.............................55
+16.5. Retrieving controls from an entry...........................56
+16.6. Parsing References..........................................57
+17. Encoded ASN.1 Value Manipulation...............................58
+17.1. BER Data Structures and Types...............................58
+17.2. Memory Disposal and Utility Functions.......................60
+17.3. Encoding....................................................60
+17.4. Encoding Example............................................63
+17.5. Decoding....................................................64
+17.6. Decoding Example............................................67
+18. Security Considerations........................................70
+19. Acknowledgements...............................................70
+20. Copyright......................................................70
+21. Bibliography...................................................71
+22. Authors' Addresses.............................................72
+23. Appendix A - Sample C LDAP API Code............................73
+24. Appendix B - Namespace Consumed By This Specification..........74
+25. Appendix C - Summary of Requirements for API Extensions........75
+25.1. Compatibility...............................................75
+25.2. Style.......................................................75
+25.3. Dependence on Externally Defined Types......................75
+25.4. Compile Time Information....................................76
+25.5. Runtime Information.........................................76
+25.6. Values Used for Session Handle Options......................76
+26. Appendix D - Known Incompatibilities with RFC 1823.............76
+26.1. Opaque LDAP Structure.......................................76
+26.2. Additional Result Codes.....................................77
+26.3. Freeing of String Data with ldap_memfree()..................77
+26.4. Changes to ldap_result()....................................77
+26.5. Changes to ldap_first_attribute() and ldap_next_attribute...77
+26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......78
+26.7. Changes to the berval structure.............................78
+26.8. API Specification Clarified.................................78
+
+
+Expires: May 2001 [Page 3]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+26.9. Deprecated Functions........................................78
+27. Appendix E - Data Types and Legacy Implementations.............79
+28. Appendix F - Changes Made Since Last Document Revision.........80
+28.1. API Changes.................................................80
+28.2. Editorial Changes and Clarifications........................81
4. Overview of the LDAP Model
LDAP is the lightweight directory access protocol, described in [2] and
-[6]. It can provide a lightweight frontend to the X.500 directory [1],
+[3]. It can provide a lightweight frontend to the X.500 directory [4],
or a stand-alone service. In either mode, LDAP is based on a client-
server model in which a client makes a TCP connection to an LDAP server,
over which it sends requests and receives responses.
to the root of the tree. For example, if Babs worked for the University
of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
o=University of Michigan, c=US". The DN format used by LDAP is defined
-in [4].
+in [5].
Operations are provided to authenticate, search for and retrieve infor-
mation, modify information, and add and delete entries from the tree.
tions.
-5. Overview of LDAP API Use
+5. Overview of LDAP API Use and General Requirements
An application generally uses the C LDAP API in four simple steps.
+
+
+Expires: May 2001 [Page 4]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
1. Initialize an LDAP session with a primary LDAP server. The
ldap_init() function returns a handle to the session, allowing
multiple connections to be open at once.
2. Authenticate to the LDAP server. The ldap_sasl_bind() function
and friends support a variety of authentication methods.
-
-
-Expires: 23 August 1999 [Page 4]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
3. Perform some LDAP operations and obtain some results.
ldap_search() and friends return results which can be parsed by
ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc.
search can be completed by calling ldap_search_s(). An asynchronous
search can be initiated by calling ldap_search(). All synchronous rou-
tines return an indication of the outcome of the operation (e.g, the
-constant LDAP_SUCCESS or some other error code). The asynchronous rou-
+constant LDAP_SUCCESS or some other result code). The asynchronous rou-
tines make available to the caller the message id of the operation ini-
tiated. This id can be used in subsequent calls to ldap_result() to
obtain the result(s) of the operation. An asynchronous operation can be
-abandoned by calling ldap_abandon() or ldap_abandon_ext().
+abandoned by calling ldap_abandon() or ldap_abandon_ext(). Note that
+there is no requirement that an LDAP API implementation not block when
+handling asynchronous API functions; the term "asynchronous" as used in
+this document refers to the fact that the sending of LDAP requests can
+be separated from the receiving of LDAP responses.
Results and errors are returned in an opaque structure called LDAPMes-
sage. Routines are provided to parse this structure, step through
interpret errors. Later sections of this document describe these rou-
tines in more detail.
-LDAP version 3 servers may return referrals and references to other
+LDAP version 3 servers can return referrals and references to other
servers. By default, implementations of this API will attempt to follow
referrals automatically for the application. This behavior can be dis-
abled globally (using the ldap_set_option() call) or on a per-request
All DN and string attribute values passed into or produced by this C
LDAP API are represented using the character set of the underlying LDAP
protocol version in use. When this API is used with LDAPv3, DN and
-string values are represented as UTF-8[10] characters. When this API is
-used with LDAPv2, the US-ASCII[12] or T.61[12] character set are used.
-Future documents may specific additional APIs supporting other character
+string values are represented as UTF-8[6] characters. When this API is
+used with LDAPv2, the US-ASCII[7] or T.61[7] character set are used.
+Future documents MAY specify additional APIs supporting other character
sets.
+
+
+Expires: May 2001 [Page 5]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
For compatibility with existing applications, implementations of this
API will by default use version 2 of the LDAP protocol. Applications
that intend to take advantage of LDAP version 3 features will need to
use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
switch to version 3.
+Unless otherwise indicated, conformant implementations of this specifi-
+cation MUST implement all of the C LDAP API functions as described in
+this document, and they MUST use the function prototypes, macro defini-
+tions, and types defined in this document.
+
Note that this API is designed for use in environments where the 'int'
type is at least 32 bits in size.
+6. Header Requirements
-
-
-Expires: 23 August 1999 [Page 5]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
-6. Header File Requirements
-
-To promote portability of applications, implementations of this C LDAP
-API must conform to the following requirements of the header files used
-by applications to access the services of this API:
+To promote portability of applications, the following requirements are
+imposed on the headers used by applications to access the services of
+this API:
Name and Inclusion
- Applications are only required to include a single header file
- named ldap.h to access all of the API services described in this
- document. Therefore, the following C source program must com-
- pile without errors:
+ Applications only need to include a single header named ldap.h
+ to access all of the API services described in this document.
+ Therefore, the following C source program MUST compile and exe-
+ cute without errors:
#include <ldap.h>
return 0;
}
- Note that it is permissible for the ldap.h header file to
- include other implementation-specific header files.
+ The ldap.h header MAY include other implementation-specific
+ headers.
-Implementations SHOULD also provide a header file named lber.h to faci-
-late development of applications desiring compatibility with older LDAP
-implementations. The lber.h header file may be empty.
+Implementations SHOULD also provide a header named lber.h to facilitate
+development of applications desiring compatibility with older LDAP
+implementations. The lber.h header MAY be empty. Old applications that
+include lber.h in order to use BER facilities will need to include
+ldap.h.
Idempotence
- All header files should be idempotent; that is, if they are
- included more than once the effect is as if they had only been
- included once.
+ All headers SHOULD be idempotent; that is, if they are included
+ more than once the effect is as if they had only been included
+
+
+
+Expires: May 2001 [Page 6]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ once.
Must Be Included Before API Is Used
- An application must include the ldap.h header file before
- referencing any of the function or type definitions described in
- this API specification.
+ An application MUST include the ldap.h header before referencing
+ any of the function or type definitions described in this API
+ specification.
Mutual Independence
- If possible, header files should be mutually independent with
- minimal dependence on system or any other header files.
+ Headers SHOULD be mutually independent with minimal dependence
+ on system or any other headers.
Use of the 'const' Keyword
- This API specification is defined in terms of ISO C[13]. It
+ This API specification is defined in terms of ISO C[8]. It
makes use of function prototypes and the 'const' keyword. The
use of 'const' in this specification is limited to simple, non-
array function parameters to avoid forcing applications to
declare parameters and variables that accept return values from
-
-
-
-Expires: 23 August 1999 [Page 6]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAP API functions as 'const.' Implementations specifically
- designed to be used with non-ISO C translators may provide func-
- tion declarations without prototypes or function prototypes
+ designed to be used with non-ISO C translators SHOULD provide
+ function declarations without prototypes or function prototypes
without specification of 'const' arguments.
Definition of 'struct timeval'
This API specification uses the 'struct timeval' type. Imple-
- mentations of this API should ensure that the struct timeval
- type is by default defined as a consequence of including the
- ldap.h header file. Because struct timeval is usually defined
- in one or more system header files, it is possible for header
- file conflicts to occur if ldap.h also defines it or arranges
- for it to be defined by including another header file. There-
- fore, applications may want to arrange for struct timeval to be
- defined before they include ldap.h. To support this, the ldap.h
- header file must not itself define struct timeval if the prepro-
- cessor symbol LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h
- is included.
+ mentations of this API MUST ensure that the struct timeval type
+ is by default defined as a consequence of including the ldap.h
+ header. Because struct timeval is usually defined in one or
+ more system headers, it is possible for header conflicts to
+ occur if ldap.h also defines it or arranges for it to be defined
+ by including another header. Therefore, applications MAY want
+ to arrange for struct timeval to be defined before they include
+ ldap.h. To support this, the ldap.h header MUST NOT itself
+ define struct timeval if the preprocessor symbol
+ LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h is included.
-7. Common Data Structures
+7. Common Data Structures and Types
-Some data structures that are common to several LDAP API functions are
-defined here:
+Data structures and types that are common to several LDAP API functions
+are defined here:
- typedef struct ldap LDAP;
+ typedef struct ldap LDAP;
- typedef struct ldapmsg LDAPMessage;
+ typedef struct ldapmsg LDAPMessage;
- typedef struct berelement BerElement;
+ typedef struct berelement BerElement;
- struct berval {
- unsigned long bv_len;
- char *bv_val;
- };
+ typedef <impl_len_t> ber_len_t;
- struct timeval {
- long tv_sec;
- long tv_usec;
- };
-The LDAP structure is an opaque data type that represents an LDAP ses-
-sion Typically this corresponds to a connection to a single server, but
-it may encompass several server connections in the face of LDAPv3 refer-
-rals.
-The LDAPMessage structure is an opaque data type that is used to return
-entry, reference, result, and error information. An LDAPMessage
+Expires: May 2001 [Page 7]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+ typedef struct berval {
+ ber_len_t bv_len;
+ char *bv_val;
+ } BerValue;
-Expires: 23 August 1999 [Page 7]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ struct timeval {
+ <impl_sec_t> tv_sec;
+ <impl_usec_t> tv_usec;
+ };
+The LDAP structure is an opaque data type that represents an LDAP ses-
+sion Typically this corresponds to a connection to a single server, but
+it MAY encompass several server connections in the face of LDAPv3 refer-
+rals.
-structure may represent the beginning of a list, or chain of messages
-that consists of a series of entries, references, and result messages as
+The LDAPMessage structure is an opaque data type that is used to return
+entry, reference, result, and error information. An LDAPMessage struc-
+ture can represent the beginning of a list, or chain of messages that
+consists of a series of entries, references, and result messages as
returned by LDAP operations such as search. LDAP API functions such as
-ldap_parse_result() that operate on message chains that may contain more
+ldap_parse_result() that operate on message chains that can contain more
than one result message always operate on the first result message in
the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
section of this document for more information.
detail in the section "Encoded ASN.1 Value Manipulation" later in this
document.
-The berval structure is used to represent arbitrary binary data and its
-fields have the following meanings:
+The `ber_len_t' type is an unsigned integral data type that is large
+enough to contain the length of the largest piece of data supported by
+the API implementation. The `<impl_len_t>' in the `ber_len_t' typedef
+MUST be replaced with an appropriate type. The width (number of signi-
+ficant bits) of `ber_len_t' MUST be at least 32 and no larger than that
+of `unsigned long'. See the appendix "Data Types and Legacy Implementa-
+tions" for additional considerations.
+
+The BerValue structure is used to represent arbitrary binary data and
+its fields have the following meanings:
bv_len Length of data in bytes.
The timeval structure is used to represent an interval of time and its
fields have the following meanings:
+
+
+Expires: May 2001 [Page 8]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
tv_sec Seconds component of time interval.
tv_usec Microseconds component of time interval.
-See the earlier section "Header File Requirements" for more information
-on struct timeval.
+Note that because the struct timeval definition typically is derived
+from a system header, the types used for the tv_sec and tv_usec com-
+ponents are implementation-specific integral types. Therefore,
+`<impl_sec_t>' and `<impl_usec_t>' in the struct timeval definition MUST
+be replaced with appropriate types. See the earlier section "Header
+Requirements" for more information on struct timeval.
+
+
+8. Memory Handling Overview
+
+All memory that is allocated by a function in this C LDAP API and
+returned to the caller SHOULD be disposed of by calling the appropriate
+"free" function provided by this API. The correct "free" function to
+call is documented in each section of this document where a function
+that allocates memory is described.
+Memory that is allocated through means outside of the C LDAP API MUST
+NOT be disposed of using a function provided by this API.
-8. Retrieving Information About the API Implementation
+If a pointer value passed to one of the C LDAP API "free" functions is
+NULL, graceful failure (i.e, ignoring of the NULL pointer) MUST occur.
+
+The complete list of "free" functions that are used to dispose of allo-
+cated memory is:
+
+ ber_bvecfree()
+ ber_bvfree()
+ ber_free()
+ ldap_control_free()
+ ldap_controls_free()
+ ldap_memfree()
+ ldap_msgfree()
+ ldap_value_free()
+ ldap_value_free_len()
+
+
+9. Retrieving Information About the API Implementation
Applications developed to this specification need to be able to deter-
mine information about the particular API implementation they are using
both at compile time and during execution.
-8.1. Retrieving Information at Compile Time
-All conformant implementations MUST include the following five defini-
-tions in a header file so compile time tests can be done by LDAP
-software developers:
-
- #define LDAP_API_VERSION level
- #define LDAP_VERSION_MIN min-version
- #define LDAP_VERSION_MAX max-version
-Expires: 23 August 1999 [Page 8]
+Expires: May 2001 [Page 9]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+9.1. Retrieving Information at Compile Time
+
+All conformant implementations MUST include the following five defini-
+tions in a header so compile time tests can be done by LDAP software
+developers:
+
+ #define LDAP_API_VERSION level
+ #define LDAP_VERSION_MIN min-version
+ #define LDAP_VERSION_MAX max-version
#define LDAP_VENDOR_NAME "vend-name"
#define LDAP_VENDOR_VERSION vend-version
ported by the implementation.
max-version is replaced with the highest LDAP protocol version sup-
- ported by the implementation. This should be 3.
+ ported by the implementation. This SHOULD be 3.
"vend-name" is replaced with a text string that identifies the
party that supplies the API implementation.
"vend-version" is a supplier-specific version number multiplied
times 100.
-Note that the LDAP_VENDOR_NAME macro may be defined as "" if no vendor
-name is available and the LDAP_VENDOR_VERSION macro may be defined as 0
-if no vendor-specific version information is available.
+Note that the LDAP_VENDOR_NAME macro SHOULD be defined as "" if no ven-
+dor name is available and the LDAP_VENDOR_VERSION macro SHOULD be
+defined as 0 if no vendor-specific version information is available.
For example, if this specification is published as RFC 88888, Netscape
Communication's version 4.0 implementation that supports LDAPv2 and v3
#if (LDAP_API_VERSION >= 88888)
/* use features supported in RFC 88888 or later */
+
+
+
+Expires: May 2001 [Page 10]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
#endif
Until such time as this document is published as an RFC, implementations
-should use the value 2000 plus the revision number of this draft for
+SHOULD use the value 2000 plus the revision number of this draft for
LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION
-for revision 03 of this draft is 2003.
+for revision 05 of this draft is 2005.
Documents that extend this specification SHOULD define a macro of the
form:
-
-
-Expires: 23 August 1999 [Page 9]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
#define LDAP_API_FEATURE_x level
where "x" is replaced with a name (textual identifier) for the feature
#define LDAP_API_FEATURE_TLS 99999
-Private or experimental API extensions may be indicated by defining a
+Private or experimental API extensions SHOULD be indicated by defining a
macro of this same form where "x" (the extension's name) begins with the
string "X_" and "level" is replaced with a integer number that is
specific to the extension.
+It is RECOMMENDED that private or experimental API extensions use only
+the following prefixes for macros, types, and function names:
+ LDAP_X_
+ LBER_X_
+ ldap_x_
+ ber_x_
+and that these prefixes not be used by standard extensions.
+
-8.2. Retrieving Information During Execution
+9.2. Retrieving Information During Execution
The ldap_get_option() call (described in greater detail later in this
document) can be used during execution in conjunction with an option
information about the API and about the specific implementation being
used. The ld parameter to ldap_get_option() can be either NULL or a
valid LDAP session handle which was obtained by calling ldap_init().
-The optdata parameter to ldap_get_option() MUST be the address of an
+The optdata parameter to ldap_get_option() SHOULD be the address of an
LDAPAPIInfo structure which is defined as follows:
+
+
+
+Expires: May 2001 [Page 11]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
typedef struct ldapapiinfo {
int ldapai_info_version; /* version of this struct (1) */
int ldapai_api_version; /* revision of API supported */
#define LDAP_API_INFO_VERSION 1
Note that the ldapai_info_version field of the LDAPAPIInfo structure
-should be set to the value LDAP_API_INFO_VERSION (1) before calling
+SHOULD be set to the value LDAP_API_INFO_VERSION (1) before calling
ldap_get_option() so that it can be checked for consistency. All other
fields are set by the ldap_get_option() function.
-
-
-Expires: 23 August 1999 [Page 10]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
The members of the LDAPAPIInfo structure are:
ldapai_info_version
A number that identifies the version of the LDAPAPIInfo struc-
- ture. This should be set to the value LDAP_API_INFO_VERSION
+ ture. This SHOULD be set to the value LDAP_API_INFO_VERSION
(1) before calling ldap_get_option(). If the value received
is not recognized by the API implementation, the
ldap_get_option() function sets ldapai_info_version to a valid
ldapai_api_version
A number that matches that assigned to the C LDAP API RFC sup-
- ported by the API implementation. This should match the value
+ ported by the API implementation. This SHOULD match the value
of the LDAP_API_VERSION macro defined earlier.
ldapai_protocol_version
tion. For example, if LDAPv3 is the highest version supported
then this field will be set to 3.
+ldapai_vendor_name
+ A zero-terminated string that contains the name of the party
+ that produced the LDAP API implementation. This field may be
+ set to NULL if no name is available. If non-NULL, the caller
+ is responsible for disposing of the memory occupied by passing
+ this pointer to ldap_memfree() which is described later in
+ this document. This value SHOULD match the value of the
+
+
+
+Expires: May 2001 [Page 12]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ LDAP_VENDOR_NAME macro described earlier in this document.
+
+ldapai_vendor_version
+ An implementation-specific version number multiplied by 100.
+ For example, if the implementation version is 4.0 then this
+ field will be set to 400. If no version information is avail-
+ able, this field will be set to 0. This value SHOULD match
+ the value of the LDAP_VENDOR_VERSION macro described earlier
+ in this document.
+
ldapai_extensions
A NULL-terminated array of character strings that lists the
names of the API extensions supported by the LDAP API imple-
ment. To retrieve more information about a particular exten-
sion, the ldap_get_option() call can be used with an option
parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt-
- data parameter to the ldap_get_option() MUST be the address of
- an LDAPAPIFeatureInfo structure which is defined as follows:
+ data parameter to the ldap_get_option() SHOULD be the address
+ of an LDAPAPIFeatureInfo structure which is defined as fol-
+ lows:
typedef struct ldap_apifeature_info {
int ldapaif_info_version; /* version of this struct (1) */
In addition, API implementations MUST include the following
macro definition:
-
-
-
-Expires: 23 August 1999 [Page 11]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
#define LDAP_FEATURE_INFO_VERSION 1
Note that the ldapaif_info_version field of the LDAPAPI-
- FeatureInfo structure should be set to the value
+ FeatureInfo structure SHOULD be set to the value
LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field
- should be set to the extension name string as described below
+ SHOULD be set to the extension name string as described below
before ldap_get_option() is called. The call will fill in the
ldapaif_version field of the LDAPAPIFeatureInfo structure.
The members of the LDAPAPIFeatureInfo structure are:
+
+
+
+Expires: May 2001 [Page 13]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
ldapaif_info_version
A number that identifies the version of the LDAPAPI-
- FeatureInfo structure. This should be set to the value
+ FeatureInfo structure. This SHOULD be set to the value
LDAP_FEATURE_INFO_VERSION (1) before calling
ldap_get_option(). If the value received is not recognized
by the API implementation, the ldap_get_option() function
assigned to the C LDAP API extension RFC supported for this
extension. For private or experimental API extensions, the
value is extension-specific. In either case, the value of
- ldapaxi_ext_version should be identical to the value of the
+ ldapaxi_ext_version SHOULD be identical to the value of the
LDAP_API_FEATURE_x macro defined for the extension
(described above).
-ldapai_vendor_name
- A zero-terminated string that contains the name of the party
- that produced the LDAP API implementation. This field may be
- set to NULL if no name is available. If non-NULL, the caller
- is responsible for disposing of the memory occupied by passing
- this pointer to ldap_memfree() which is described later in
- this document. This value SHOULD match the value of the
- LDAP_VENDOR_NAME macro described earlier in this document.
-
-ldapai_vendor_version
- An implementation-specific version number multiplied by 100.
- For example, if the implementation version is 4.0 then this
-
-
-
-Expires: 23 August 1999 [Page 12]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
- field will be set to 400. If no version information is avail-
- able, this field will be set to 0. This value SHOULD match
- the value of the LDAP_VENDOR_VERSION macro described earlier
- in this document.
+10. Result Codes
-9. LDAP Error Codes
-
-Many of the LDAP API routines return LDAP error codes, some of which
-indicate local errors and some of which may be returned by servers. All
-of the LDAP error codes returned will be positive integers. Supported
-error codes are (hexadecimal values are given in parentheses after the
-constant):
+Many of the LDAP API routines return result codes, some of which indi-
+cate local API errors and some of which are LDAP resultCodes that are
+returned by servers. All of the result codes are non-negative integers.
+Supported result codes are as follows (hexadecimal values are given in
+parentheses after the constant):
LDAP_SUCCESS (0x00)
LDAP_OPERATIONS_ERROR (0x01)
LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3
LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3
LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3
+
+
+
+Expires: May 2001 [Page 14]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
LDAP_NO_SUCH_ATTRIBUTE (0x10)
LDAP_UNDEFINED_TYPE (0x11)
LDAP_INAPPROPRIATE_MATCHING (0x12)
LDAP_LOOP_DETECT (0x36)
LDAP_NAMING_VIOLATION (0x40)
LDAP_OBJECT_CLASS_VIOLATION (0x41)
-
-
-
-Expires: 23 August 1999 [Page 13]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
LDAP_NOT_ALLOWED_ON_RDN (0x43)
LDAP_ALREADY_EXISTS (0x44)
LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
-10. Performing LDAP Operations
-This section describes each LDAP operation API call in detail. All func-
-tions take a "session handle," a pointer to an LDAP structure containing
-per-connection information. Many routines return results in an LDAPMes-
-sage structure. These structures and others are described as needed
-below.
-10.1. Initializing an LDAP Session
-ldap_init() initializes a session with an LDAP server. The server is not
-actually contacted until an operation is performed that requires it,
-allowing various options to be set after initialization.
- LDAP *ldap_init(
- const char *hostname,
- int portno
- );
+Expires: May 2001 [Page 15]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
-Use of the following routine is deprecated:
+11. Performing LDAP Operations
+This section describes each LDAP operation API call in detail. Most
+functions take a "session handle," a pointer to an LDAP structure con-
+taining per-connection information. Many routines return results in an
+LDAPMessage structure. These structures and others are described as
+needed below.
-Expires: 23 August 1999 [Page 14]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+11.1. Initializing an LDAP Session
+ldap_init() initializes a session with an LDAP server. The server is not
+actually contacted until an operation is performed that requires it,
+allowing various options to be set after initialization.
+
+ LDAP *ldap_init(
+ const char *hostname,
+ int portno
+ );
+
+Use of the following routine is deprecated:
+
+ LDAP *ldap_open(
+ const char *hostname,
+ int portno
+ );
- LDAP *ldap_open(
- const char *hostname,
- int portno
- );
Unlike ldap_init(), ldap_open() attempts to make a server connection
-before returning to the caller.
+before returning to the caller. A more complete description can be
+found in RFC 1823.
Parameters are:
hostname Contains a space-separated list of hostnames or dotted strings
representing the IP address of hosts running an LDAP server to
- connect to. Each hostname in the list can include an optional
- port number which is separated from the host itself with a
- colon (:) character. The hosts will be tried in the order
- listed, stopping with the first one to which a successful con-
- nection is made.
+ connect to. Each hostname in the list MAY include a port number
+ which is separated from the host itself with a colon (:) char-
+ acter. The hosts will be tried in the order listed, stopping
+ with the first one to which a successful connection is made.
- Note: A suitable representation for including a literal IPv6[11]
+ Note: A suitable representation for including a literal IPv6[10]
address in the hostname parameter is desired, but has not yet been
determined or implemented in practice.
portno Contains the TCP port number to connect to. The default LDAP
- port of 389 can be obtained by supplying the constant
- LDAP_PORT. If a host includes a port number then this parame-
- ter is ignored.
+ port of 389 can be obtained by supplying the value zero (0) or
+ the macro LDAP_PORT (389). If a host includes a port number
+ then this parameter is ignored.
+
+
+
+Expires: May 2001 [Page 16]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
ldap_init() and ldap_open() both return a "session handle," a pointer to
-an opaque structure that should be passed to subsequent calls pertaining
+an opaque structure that MUST be passed to subsequent calls pertaining
to the session. These routines return NULL if the session cannot be ini-
tialized in which case the operating system error reporting mechanism
can be checked to see why the call failed.
Note that if you connect to an LDAPv2 server, one of the LDAP bind calls
-described below must be completed before other operations can be per-
+described below SHOULD be completed before other operations can be per-
formed on the session. LDAPv3 does not require that a bind operation be
completed before other operations can be performed.
the routines described in the next section.
-10.2. LDAP Session Handle Options
+11.2. LDAP Session Handle Options
The LDAP session handle returned by ldap_init() is a pointer to an
opaque data type representing an LDAP session. In RFC 1823 this data
structure could be set to control aspects of the session, such as size
and time limits on searches.
-
-
-Expires: 23 August 1999 [Page 15]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
In the interest of insulating callers from inevitable changes to this
structure, these aspects of the session are now accessed through a pair
of accessor functions, described below.
LDAP *ld,
int option,
const void *invalue
+
+
+
+Expires: May 2001 [Page 17]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
);
- #define LDAP_OPT_ON ((void *)1)
- #define LDAP_OPT_OFF ((void *)0)
+ #define LDAP_OPT_ON (<impl_void_star_value>)
+ #define LDAP_OPT_OFF ((void *)0)
+ LDAP_OPT_ON MUST be defined as a non-null pointer to void; that is,
+ <impl_void_star_value> MUST be replaced with a non-null pointer to
+ void, e.g., one could use:
+ #define LDAP_OPT_ON ((void *)1)
+ if that value is safe to use on the architecture where the API is
+ implemented.
Parameters are:
defaults.
option The name of the option being accessed or set. This parameter
- should be one of the following constants, which have the indi-
+ SHOULD be one of the following constants, which have the indi-
cated meanings. After the constant the actual hexadecimal value
of the constant is listed in parentheses.
Type for outvalue parameter: LDAPAPIInfo *
-
-
-Expires: 23 August 1999 [Page 16]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
Description:
Used to retrieve some basic information about the LDAP API
implementation at execution time. See the section "Retriev-
ing Information About the API Implementation" above for more
information. This option is READ-ONLY and cannot be set.
- LDAP_OPT_DESC (0x01)
- Type for invalue parameter: not applicable (option is READ-
- ONLY)
+ LDAP_OPT_DEREF (0x02)
+ Type for invalue parameter: int *
+
+ Type for outvalue parameter: int *
+
+ Description:
+ Determines how aliases are handled during search. It SHOULD
+ have one of the following values: LDAP_DEREF_NEVER (0x00),
+ LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
+ LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value
+ means aliases are dereferenced during the search but not when
+ locating the base object of the search. The
+
- Type for outvalue parameter: int *
- Description:
- The underlying socket descriptor corresponding to the pri-
- mary LDAP connection. This option is READ-ONLY and cannot
- be set.
+Expires: May 2001 [Page 18]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
- LDAP_OPT_DEREF (0x02)
- Type for invalue parameter: int *
- Type for outvalue parameter: int *
+ LDAP_DEREF_FINDING value means aliases are dereferenced when
+ locating the base object but not during the search. The
+ default value for this option is LDAP_DEREF_NEVER.
- Description:
- Determines how aliases are handled during search. It can
- have one of the following values: LDAP_DEREF_NEVER (0x00),
- LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
- LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value
- means aliases should be dereferenced during the search but
- not when locating the base object of the search. The
- LDAP_DEREF_FINDING value means aliases should be derefer-
- enced when locating the base object but not during the
- search.
+ LDAP_OPT_SIZELIMIT (0x03)
+ Type for invalue parameter: int *
- LDAP_OPT_SIZELIMIT (0x03)
- Type for invalue parameter: int *
+ Type for outvalue parameter: int *
- Type for outvalue parameter: int *
+ Description:
+ A limit on the number of entries to return from a search. A
+ value of LDAP_NO_LIMIT (0) means no limit. The default value
+ for this option is LDAP_NO_LIMIT.
- Description:
- A limit on the number of entries to return from a search.
- A value of LDAP_NO_LIMIT (0) means no limit.
+ LDAP_OPT_TIMELIMIT (0x04)
+ Type for invalue parameter: int *
- LDAP_OPT_TIMELIMIT (0x04)
- Type for invalue parameter: int *
+ Type for outvalue parameter: int *
- Type for outvalue parameter: int *
+ Description:
+ A limit on the number of seconds to spend on a search. A
+ value of LDAP_NO_LIMIT (0) means no limit. The default value
+ for this option is LDAP_NO_LIMIT. This value is passed to
+ the server in the search request only; it does not affect how
+ long the C LDAP API implementation itself will wait locally
+ for search results. Note that the timeout parameter passed
+ to the ldap_search_ext_s() or ldap_result() functions can be
+ used to specify a limit on how long the API implementation
+ will wait for results.
- Description:
+ LDAP_OPT_REFERRALS (0x08)
+ Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
+ Type for outvalue parameter: int *
+ Description:
+ Determines whether the LDAP library automatically follows
+ referrals returned by LDAP servers or not. It MAY be set to
+ one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-
+ NULL pointer value passed to ldap_set_option() enables this
+ option. When reading the current setting using
+ ldap_get_option(), a zero value means OFF and any non-zero
+ value means ON. By default, this option is ON.
-Expires: 23 August 1999 [Page 17]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ LDAP_OPT_RESTART (0x09)
+ Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
+ Type for outvalue parameter: int *
- A limit on the number of seconds to spend on a search. A
- value of LDAP_NO_LIMIT (0) means no limit. This value is
- passed to the server in the search request only; it does
- not affect how long the C LDAP API implementation itself
- will wait locally for search results. The timeout parame-
- ter passed to ldap_search_ext_s() or ldap_result() -- both
- of which are described later in this document -- can be
- used to specify both a local and server side time limit.
- LDAP_OPT_REFERRALS (0x08)
- Type for invalue parameter: void * (LDAP_OPT_ON or
- LDAP_OPT_OFF)
- Type for outvalue parameter: int *
+Expires: May 2001 [Page 19]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
- Description:
- Determines whether the LDAP library automatically follows
- referrals returned by LDAP servers or not. It can be set
- to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any
- non-NULL pointer value passed to ldap_set_option() enables
- this option. When reading the current setting using
- ldap_get_option(), a zero value means off and any non-zero
- value means on.
- LDAP_OPT_RESTART (0x09)
- Type for invalue parameter: void * (LDAP_OPT_ON or
- LDAP_OPT_OFF)
+ Description:
+ Determines whether LDAP I/O operations are automatically res-
+ tarted if they abort prematurely. It MAY be set to one of the
+ constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer
+ value passed to ldap_set_option() enables this option. When
+ reading the current setting using ldap_get_option(), a zero
+ value means OFF and any non-zero value means ON. This option
+ is useful if an LDAP I/O operation can be interrupted prema-
+ turely, for example by a timer going off, or other interrupt.
+ By default, this option is OFF.
- Type for outvalue parameter: int *
+ LDAP_OPT_PROTOCOL_VERSION (0x11)
+ Type for invalue parameter: int *
- Description:
- Determines whether LDAP I/O operations should automati-
- cally be restarted if they abort prematurely. It should be
- set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF;
- any non-NULL pointer value passed to ldap_set_option()
- enables this option. When reading the current setting
- using ldap_get_option(), a zero value means off and any
- non-zero value means on. This option is useful if an LDAP
- I/O operation may be interrupted prematurely, for example
- by a timer going off, or other interrupt.
+ Type for outvalue parameter: int *
- LDAP_OPT_PROTOCOL_VERSION (0x11)
- Type for invalue parameter: int *
+ Description:
+ This option indicates the version of the LDAP protocol used
+ when communicating with the primary LDAP server. It SHOULD be
+ one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3).
+ If no version is set the default is LDAP_VERSION2 (2).
- Type for outvalue parameter: int *
+ LDAP_OPT_SERVER_CONTROLS (0x12)
+ Type for invalue parameter: LDAPControl **
- Description:
- This option indicates the version of the LDAP protocol
+ Type for outvalue parameter: LDAPControl ***
+ Description:
+ A default list of LDAP server controls to be sent with each
+ request. See the Working With Controls section below.
+ LDAP_OPT_CLIENT_CONTROLS (0x13)
+ Type for invalue parameter: LDAPControl **
-Expires: 23 August 1999 [Page 18]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ Type for outvalue parameter: LDAPControl ***
+ Description:
+ A default list of client controls that affect the LDAP ses-
+ sion. See the Working With Controls section below.
- used when communicating with the primary LDAP server. It
- must be one of the constants LDAP_VERSION2 (2) or
- LDAP_VERSION3 (3). If no version is set the default is
- LDAP_VERSION2 (2).
+ LDAP_OPT_API_FEATURE_INFO (0x15)
+ Type for invalue parameter: not applicable (option is READ-ONLY)
- LDAP_OPT_SERVER_CONTROLS (0x12)
- Type for invalue parameter: LDAPControl **
+ Type for outvalue parameter: LDAPAPIFeatureInfo *
- Type for outvalue parameter: LDAPControl ***
+ Description:
+ Used to retrieve version information about LDAP API extended
+ features at execution time. See the section "Retrieving
- Description:
- A default list of LDAP server controls to be sent with
- each request. See the Working With Controls section
- below.
- LDAP_OPT_CLIENT_CONTROLS (0x13)
- Type for invalue parameter: LDAPControl **
- Type for outvalue parameter: LDAPControl ***
+Expires: May 2001 [Page 20]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
- Description:
- A default list of client controls that affect the LDAP
- session. See the Working With Controls section below.
+ Information About the API Implementation" above for more
+ information. This option is READ-ONLY and cannot be set.
- LDAP_OPT_API_FEATURE_INFO (0x15)
- Type for invalue parameter: not applicable (option is READ-
- ONLY)
+ LDAP_OPT_HOST_NAME (0x30)
+ Type for invalue parameter: char *
- Type for outvalue parameter: LDAPAPIFeatureInfo *
+ Type for outvalue parameter: char **
- Description:
- Used to retrieve version information about LDAP API
- extended features at execution time. See the section
- "Retrieving Information About the API Implementation"
- above for more information. This option is READ-ONLY and
- cannot be set.
+ Description:
+ The host name (or list of hosts) for the primary LDAP server.
+ See the definition of the hostname parameter to ldap_init()
+ for the allowed syntax. Note that if the portno parameter
+ passed to ldap_init() is a value other than 0 or 389
+ (LDAP_PORT), this value SHOULD include a string like
+ ":portno" after each hostname or IP address that did not have
+ one in the original hostname parameter that was passed to
+ ldap_init(). For example, if this hostname value was passed
+ to ldap_init():
- LDAP_OPT_HOST_NAME (0x30)
- Type for invalue parameter: char *
+ "ldap.example.com:389 ldap2.example.com"
- Type for outvalue parameter: char **
+ and the portno parameter passed to ldap_init() was 6389, then
+ the value returned for the LDAP_OPT_HOST_NAME option SHOULD
+ be:
- Description:
- The host name (or list of hosts) for the primary LDAP
- server. See the definition of the hostname parameter to
- ldap_init() for the allowed syntax.
+ "ldap.example.com:389 ldap2.example.com:6389"
- LDAP_OPT_ERROR_NUMBER (0x31)
+ LDAP_OPT_RESULT_CODE (0x31)
+ Type for invalue parameter: int *
+ Type for outvalue parameter: int *
-Expires: 23 August 1999 [Page 19]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ Description:
+ The most recent local (API generated) or server returned LDAP
+ result code that occurred for this session.
+ LDAP_OPT_ERROR_STRING (0x32)
+ Type for invalue parameter: char *
- Type for invalue parameter: int *
+ Type for outvalue parameter: char **
- Type for outvalue parameter: int *
+ Description:
+ The message returned with the most recent LDAP error that
+ occurred for this session.
- Description:
- The code of the most recent LDAP error that occurred for
- this session.
+ LDAP_OPT_MATCHED_DN (0x33)
+ Type for invalue parameter: char *
- LDAP_OPT_ERROR_STRING (0x32)
- Type for invalue parameter: char *
- Type for outvalue parameter: char **
- Description:
- The message returned with the most recent LDAP error that
- occurred for this session.
+Expires: May 2001 [Page 21]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
- outvalue The address of a place to put the value of the option. The
- actual type of this parameter depends on the setting of the
- option parameter. For outvalues of type char ** and LDAP-
- Control **, a copy of the data that is associated with the
- LDAP session ld is returned; callers should dispose of the
- memory by calling ldap_memfree() or ldap_controls_free().
+ Type for outvalue parameter: char **
- invalue A pointer to the value the option is to be given. The actual
- type of this parameter depends on the setting of the option
- parameter. The data associated with invalue is copied by the
- API implementation to allow callers of the API to dispose of
- or otherwise change their copy of the data after a success-
- ful call to ldap_set_option(). If a value passed for
- invalue is invalid or cannot be accepted by the implementa-
- tion, ldap_set_option() should return -1 to indicate an
- error.
+ Description:
+ The matched DN value returned with the most recent LDAP error
+ that occurred for this session.
+
+
+outvalue The address of a place to put the value of the option. The
+ actual type of this parameter depends on the setting of the
+ option parameter. For outvalues of type char ** and LDAPCon-
+ trol **, a copy of the data that is associated with the LDAP
+ session ld is returned; callers should dispose of the memory by
+ calling ldap_memfree() or ldap_controls_free(), depending on
+ the type of data returned.
+
+invalue A pointer to the value the option is to be given. The actual
+ type of this parameter depends on the setting of the option
+ parameter. The data associated with invalue is copied by the
+ API implementation to allow callers of the API to dispose of or
+ otherwise change their copy of the data after a successful call
+ to ldap_set_option(). If a value passed for invalue is invalid
+ or cannot be accepted by the implementation, ldap_set_option()
+ should return -1 to indicate an error.
Both ldap_get_option() and ldap_set_option() return 0 if successful and
--1 if an error occurs.
+-1 if an error occurs. If -1 is returned by either function, a specific
+result code MAY be retrieved by calling ldap_get_option() with an option
+value of LDAP_OPT_RESULT_CODE. Note that there is no way to retrieve a
+more specific result code if a call to ldap_get_option() with an option
+value of LDAP_OPT_RESULT_CODE fails.
+
+When a call to ldap_get_option() succeeds, the API implementation MUST
+NOT change the state of the LDAP session handle or the state of the
+underlying implementation in a way that affects the behavior of future
+LDAP API calls. When a call to ldap_get_option() fails, the only ses-
+sion handle change permitted is setting the LDAP result code (as
+returned by the LDAP_OPT_RESULT_CODE option).
+
+When a call to ldap_set_option() fails, it MUST NOT change the state of
+the LDAP session handle or the state of the underlying implementation in
+a way that affects the behavior of future LDAP API calls.
Standards track documents that extend this specification and specify new
-options MUST use values for option macros that are between 0x1000 and
-0x3FFF inclusive. Private and experimental extensions MUST use values
+options SHOULD use values for option macros that are between 0x1000 and
+0x3FFF inclusive. Private and experimental extensions SHOULD use values
for the option macros that are between 0x4000 and 0x7FFF inclusive. All
values below 0x1000 and above 0x7FFF that are not defined in this docu-
-ment are reserved and MUST NOT be used.
-
+ment are reserved and SHOULD NOT be used. The following macro MUST be
+Expires: May 2001 [Page 22]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+defined by C LDAP API implementations to aid extension implementors:
+ #define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */
-Expires: 23 August 1999 [Page 20]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-10.3. Working With Controls
+11.3. Working With Controls
LDAPv3 operations can be extended through the use of controls. Controls
-may be sent to a server or returned to the client with any LDAP message.
+can be sent to a server or returned to the client with any LDAP message.
These controls are referred to as server controls.
The LDAP API also supports a client-side extension mechanism through the
char *ldctl_oid;
struct berval ldctl_value;
char ldctl_iscritical;
- } LDAPControl, *PLDAPControl;
+ } LDAPControl;
The fields in the ldapcontrol structure have the following meanings:
void ldap_control_free( LDAPControl *ctrl );
void ldap_controls_free( LDAPControl **ctrls );
+If the ctrl or ctrls parameter is NULL, these calls do nothing.
+
+
+
+
+Expires: May 2001 [Page 23]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
A set of controls that affect the entire session can be set using the
ldap_set_option() function (see above). A list of controls can also be
ldap_set_option() are ignored. Control lists are represented as a NULL-
terminated array of pointers to ldapcontrol structures.
-
-
-Expires: 23 August 1999 [Page 21]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
Server controls are defined by LDAPv3 protocol extension documents; for
example, a control has been proposed to support server-side sorting of
-search results [7].
+search results [11].
One client control is defined in this document (described in the follow-
-ing section). Other client controls may be defined in future revisions
+ing section). Other client controls MAY be defined in future revisions
of this document or in documents that extend this API.
-10.3.1. A Client Control That Governs Referral Processing
+11.3.1. A Client Control That Governs Referral Processing
As described previously in the section "LDAP Session Handle Options,"
applications can enable and disable automatic chasing of referrals on a
#define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616"
/* Flags for referrals client control value */
- #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020
- #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040
+ #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U
+ #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U
To create a referrals client control, the ldctl_oid field of an LDAPCon-
-trol structure should be set to LDAP_CONTROL_REFERRALS
-("1.2.840.113556.1.4.616") and the ldctl_value field should be set to a
-4-octet value that contains a set of flags. The ldctl_value.bv_len
-field should always be set to 4. The ldctl_value.bv_val field should
-point to a 4-octet integer flags value. This flags value can be set to
-zero to disable automatic chasing of referrals and LDAPv3 references
-altogether. Alternatively, the flags value can be set to the value
-LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020) to indicate that only
-LDAPv3 search continuation references should be automatically chased by
-the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS
-(0x00000040) to indicate that only LDAPv3 referrals should be automati-
-cally chased, or the logical OR of the two flag values (0x00000060) to
-indicate that both referrals and references should be automatically
-chased.
-
-
-10.4. Authenticating to the directory
+trol structure MUST be set to LDAP_CONTROL_REFERRALS
+("1.2.840.113556.1.4.616") and the ldctl_value field MUST be set to a
+value that contains a set of flags. The ldctl_value.bv_len field MUST
+be set to sizeof(ber_uint_t), and the ldctl_value.bv_val field MUST
+point to a ber_uint_t which contains the flags value." The ber_uint_t
+type is define in the section "BER Data Structures and Types" below.
-The following functions are used to authenticate an LDAP client to an
-LDAP directory server.
+The flags value can be set to zero to disable automatic chasing of
+referrals and LDAPv3 references altogether. Alternatively, the flags
+value can be set to the value LDAP_CHASE_SUBORDINATE_REFERRALS
+(0x00000020U) to indicate that only LDAPv3 search continuation refer-
+ences are to be automatically chased by the API implementation, to the
+value LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U) to indicate that only
+LDAPv3 referrals are to be automatically chased, or the logical OR of
+the two flag values (0x00000060U) to indicate that both referrals and
-The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
-
-Expires: 23 August 1999 [Page 22]
+Expires: May 2001 [Page 24]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+references are to be automatically chased.
+
+11.4. Authenticating to the directory
+
+The following functions are used to authenticate an LDAP client to an
+LDAP directory server.
+
+The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
general and extensible authentication over LDAP through the use of the
-Simple Authentication Security Layer [8]. The routines both take the dn
-to bind as, the method to use, as a dotted-string representation of an
-OID identifying the method, and a struct berval holding the credentials.
-The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to
-request simple authentication, or the simplified routines
+Simple Authentication Security Layer [12]. The routines both take the
+dn to bind as, the method to use, as a dotted-string representation of
+an OID identifying the method, and a struct berval holding the creden-
+tials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed
+to request simple authentication, or the simplified routines
ldap_simple_bind() or ldap_simple_bind_s() can be used.
int ldap_sasl_bind(
const char *passwd
);
- The use of the following routines is deprecated:
- int ldap_bind( LDAP *ld, const char *dn, const char *cred,
- int method );
-
- int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
- int method );
+Expires: May 2001 [Page 25]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+ The use of the following routines is deprecated and more complete
+ descriptions can be found in RFC 1823:
-Expires: 23 August 1999 [Page 23]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ int ldap_bind( LDAP *ld, const char *dn, const char *cred,
+ int method );
+ int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
+ int method );
int ldap_kerberos_bind( LDAP *ld, const char *dn );
ld The session handle.
-dn The name of the entry to bind as.
+dn The name of the entry to bind as. If NULL, a zero length
+ DN is sent to the server.
mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica-
tion, or a text string identifying the SASL method.
cred The credentials with which to authenticate. Arbitrary
credentials can be passed using this parameter. The format
and content of the credentials depends on the setting of
- the mechanism parameter.
+ the mechanism parameter. If the cred parameter is NULL and
+ the mechanism is LDAP_SASL_SIMPLE, a zero-length octet
+ string is sent to the server in the simple credentials
+ field of the bind request. If the cred parameter is NULL
+ and the mechanism is anything else, no credentials are sent
+ to the server in the bind request.
-passwd For ldap_simple_bind(), the password to compare to the
- entry's userPassword attribute.
+passwd For ldap_simple_bind(), the password that is sent to the
+ server in the simple credentials field of the bind request.
+ If NULL, a zero length password is sent to the server.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_sasl_bind() call succeeds.
+ request if the ldap_sasl_bind() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+
+
+
+Expires: May 2001 [Page 26]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
servercredp This result parameter will be filled in with the creden-
tials passed back by the server for mutual authentication,
if given. An allocated berval structure is returned that
- should be disposed of by calling ber_bvfree(). NULL may be
- passed to ignore this field.
+ SHOULD be disposed of by calling ber_bvfree(). NULL SHOULD
+ be passed to ignore this field. If an API error occurs or
+ the server did not return any credentials, *servercredp is
+ set to NULL.
Additional parameters for the deprecated routines are not described.
Interested readers are referred to RFC 1823.
The ldap_sasl_bind() function initiates an asynchronous bind operation
and returns the constant LDAP_SUCCESS if the request was successfully
-sent, or another LDAP error code if not. See the section below on error
-handling for more information about possible errors and how to interpret
-them. If successful, ldap_sasl_bind() places the message id of the
-request in *msgidp. A subsequent call to ldap_result(), described below,
-can be used to obtain the result of the bind.
+sent, or another LDAP result code if not. See the section below on
+error handling for more information about possible errors and how to
+interpret them. If successful, ldap_sasl_bind() places the message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the bind.
The ldap_simple_bind() function initiates a simple asynchronous bind
operation and returns the message id of the operation initiated. A sub-
sequent call to ldap_result(), described below, can be used to obtain
-
-
-
-Expires: 23 August 1999 [Page 24]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
the result of the bind. In case of error, ldap_simple_bind() will return
-1, setting the session error parameters in the LDAP structure appropri-
ately.
The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
both return the result of the operation, either the constant
-LDAP_SUCCESS if the operation was successful, or another LDAP error code
-if it was not. See the section below on error handling for more informa-
-tion about possible errors and how to interpret them.
+LDAP_SUCCESS if the operation was successful, or another LDAP result
+code if it was not. See the section below on error handling for more
+information about possible errors and how to interpret them.
Note that if an LDAPv2 server is contacted, no other operations over the
-connection should be attempted before a bind call has successfully com-
+connection can be attempted before a bind call has successfully com-
pleted.
Subsequent bind calls can be used to re-authenticate over the same con-
sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
-10.5. Closing the session
+11.5. Closing the session
The following functions are used to unbind from the directory, close
open connections, and dispose of the session handle.
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
- LDAPControl **clientctrls );
+ LDAPControl **clientctrls );
+
+
+
+Expires: May 2001 [Page 27]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
int ldap_unbind( LDAP *ld );
ld The session handle.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn-
chronously in the sense that they send an unbind request to the server,
dispose of all resources associated with the session handle before
returning. Note, however, that there is no server response to an LDAP
unbind operation. All three of the unbind functions return LDAP_SUCCESS
-(or another LDAP error code if the request cannot be sent to the LDAP
+(or another LDAP result code if the request cannot be sent to the LDAP
server). After a call to one of the unbind functions, the session han-
dle ld is invalid and it is illegal to make any further LDAP API calls
-
-
-
-Expires: 23 August 1999 [Page 25]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
using ld.
The ldap_unbind() and ldap_unbind_s() functions behave identically. The
-10.6. Searching
+11.6. Searching
The following functions are used to search the LDAP directory, returning
a requested set of attributes for each entry matched. There are five
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
+
+
+
+Expires: May 2001 [Page 28]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
struct timeval *timeout,
int sizelimit,
int *msgidp
LDAP *ld,
const char *base,
int scope,
-
-
-
-Expires: 23 August 1999 [Page 26]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
const char *filter,
char **attrs,
int attrsonly
LDAPMessage **res
);
+
+
+Expires: May 2001 [Page 29]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
Parameters are:
ld The session handle.
-base The dn of the entry at which to start the search.
+base The dn of the entry at which to start the search. If NULL,
+ a zero length DN is sent to the server.
scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
search.
-filter A character string as described in [3], representing the
+filter A character string as described in [13], representing the
search filter. The value NULL can be passed to indicate
that the filter "(objectclass=*)" which matches all entries
- should be used. Note that if the caller of the API is
- using LDAPv2, only a subset of the filter functionality
- described in [3] can be successfully used.
+ is to be used. Note that if the caller of the API is using
+ LDAPv2, only a subset of the filter functionality described
+ in [13] can be successfully used.
attrs A NULL-terminated array of strings indicating which attri-
butes to return for each matching entry. Passing NULL for
this parameter causes all available user attributes to be
retrieved. The special constant string LDAP_NO_ATTRS
- ("1.1") can be used as the only string in the array to
-
-
-
-Expires: 23 August 1999 [Page 27]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
- indicate that no attribute types should be returned by the
+ ("1.1") MAY be used as the only string in the array to
+ indicate that no attribute types are to be returned by the
server. The special constant string LDAP_ALL_USER_ATTRS
("*") can be used in the attrs array along with the names
of some operational attributes to indicate that all user
- attributes plus the listed operational attributes should be
+ attributes plus the listed operational attributes are to be
returned.
-attrsonly A boolean value that should be zero if both attribute types
- and values are to be returned, non-zero if only types are
- wanted.
+attrsonly A boolean value that MUST be zero if both attribute types
+ and values are to be returned, and non-zero if only types
+ are wanted.
timeout For the ldap_search_st() function, this specifies the local
search timeout value (if it is NULL, the timeout is infin-
- ite). For the ldap_search_ext() and ldap_search_ext_s()
- functions, this specifies both the local search timeout
- value and the operation time limit that is sent to the
- server within the search request. For the
- ldap_search_ext() and ldap_search_ext_s() functions, pass-
- ing a NULL value for timeout causes the global default
- timeout stored in the LDAP session handle (set by using
- ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter) to
- be sent to the server with the request but an infinite
- local search timeout to be used.
+ ite). If a zero timeout (where tv_sec and tv_usec are both
+ zero) is passed, API implementations SHOULD return
+ LDAP_PARAM_ERROR.
+
+ For the ldap_search_ext() and ldap_search_ext_s() func-
+ tions, the timeout parameter specifies both the local
+ search timeout value and the operation time limit that is
+ sent to the server within the search request. Passing a
+ NULL value for timeout causes the default timeout stored in
+ the LDAP session handle (set by using ldap_set_option()
+ with the LDAP_OPT_TIMELIMIT parameter) to be sent to the
+ server with the request but an infinite local search
+
+
+
+Expires: May 2001 [Page 30]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ timeout to be used. If a zero timeout (where tv_sec and
+ tv_usec are both zero) is passed in, API implementations
+ SHOULD return LDAP_PARAM_ERROR. If a zero value for tv_sec
+ is used but tv_usec is non-zero, an operation time limit of
+ 1 SHOULD be passed to the LDAP server as the operation time
+ limit. For other values of tv_sec, the tv_sec value itself
+ SHOULD be passed to the LDAP server.
sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls,
this is a limit on the number of entries to return from the
- search. A value of LDAP_NO_LIMIT (0) means no limit.
+ search. A value of LDAP_NO_LIMIT (0) means no limit. A
+ value of LDAP_DEFAULT_SIZELIMIT (-1) means use the default
+ timeout from the LDAP session handle (which is set by cal-
+ ling ldap_set_option() with the LDAP_OPT_SIZELIMIT parame-
+ ter).
res For the synchronous calls, this is a result parameter which
will contain the results of the search upon completion of
- the call. If no results are returned, *res is set to NULL.
+ the call. If an API error occurs or no results are
+ returned, *res is set to NULL.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_search_ext() call succeeds.
+ request if the ldap_search_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
There are three options in the session handle ld which potentially
affect how the search is performed. They are:
-LDAP_OPT_SIZELIMIT
- A limit on the number of entries to return from the search.
- A value of LDAP_NO_LIMIT (0) means no limit. Note that the
- value from the session handle is ignored when using the
- ldap_search_ext() or ldap_search_ext_s() functions.
-
-
-
-
-Expires: 23 August 1999 [Page 28]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
-LDAP_OPT_TIMELIMIT
- A limit on the number of seconds to spend on the search. A
- value of LDAP_NO_LIMIT (0) means no limit. Note that the
- value from the session handle is ignored when using the
- ldap_search_ext() or ldap_search_ext_s() functions.
+ LDAP_OPT_SIZELIMIT
+ LDAP_OPT_TIMELIMIT
+ LDAP_OPT_DEREF
-LDAP_OPT_DEREF
- One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
- (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
- (0x03), specifying how aliases should be handled during the
- search. The LDAP_DEREF_SEARCHING value means aliases should
- be dereferenced during the search but not when locating the
- base object of the search. The LDAP_DEREF_FINDING value
- means aliases should be dereferenced when locating the base
- object but not during the search.
+These options are fully described in the earlier section "LDAP Session
+Handle Options."
The ldap_search_ext() function initiates an asynchronous search opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not. See the section below on
-error handling for more information about possible errors and how to
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
interpret them. If successful, ldap_search_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
+
+
+
+Expires: May 2001 [Page 31]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
below, can be used to obtain the results from the search. These results
can be parsed using the result parsing routines described in detail
later.
The synchronous ldap_search_ext_s(), ldap_search_s(), and
ldap_search_st() functions all return the result of the operation,
either the constant LDAP_SUCCESS if the operation was successful, or
-another LDAP error code if it was not. See the section below on error
+another LDAP result code if it was not. See the section below on error
handling for more information about possible errors and how to interpret
them. Entries returned from the search (if any) are contained in the
res parameter. This parameter is opaque to the caller. Entries, attri-
-butes, values, etc., should be extracted by calling the parsing routines
-described below. The results contained in res should be freed when no
+butes, values, etc., can be extracted by calling the parsing routines
+described below. The results contained in res SHOULD be freed when no
longer in use by calling ldap_msgfree(), described later.
The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
server controls, client controls, and allow varying size and time limits
to be easily specified for each search operation. The ldap_search_st()
-function is identical to ldap_search_s() except that it takes an
-
+function is identical to ldap_search_s() except that it takes an addi-
+tional parameter specifying a local timeout for the search. The local
+search timeout is used to limit the amount of time the API implementa-
+tion will wait for a search to complete. After the local search timeout
+expires, the API implementation will send an abandon operation to abort
+the search operation.
-
-Expires: 23 August 1999 [Page 29]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
-additional parameter specifying a local timeout for the search. The
-local search timeout is used to limit the amount of time the API imple-
-mentation will wait for a search to complete. After the local search
-timeout expires, the API implementation will send an abandon operation
-to abort the search operation.
-
-10.7. Reading an Entry
+11.7. Reading an Entry
LDAP does not support a read operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to read,
NULL. attrs contains the list of attributes to return.
-10.8. Listing the Children of an Entry
+11.8. Listing the Children of an Entry
LDAP does not support a list operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to list,
NULL. attrs contains the list of attributes to return for each child
entry.
-10.9. Comparing a Value Against an Entry
+
+
+
+Expires: May 2001 [Page 32]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+11.9. Comparing a Value Against an Entry
The following routines are used to compare a given attribute value
assertion against an LDAP entry. There are four variations:
int ldap_compare_ext(
- LDAP *ld,
- const char *dn,
- const char *attr,
- struct berval *bvalue
- LDAPControl **serverctrls,
- LDAPControl **clientctrls,
- int *msgidp
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const struct berval *bvalue,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
);
int ldap_compare_ext_s(
- LDAP *ld,
- const char *dn,
- const char *attr,
- struct berval *bvalue,
- LDAPControl **serverctrls,
- LDAPControl **clientctrls
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const struct berval *bvalue,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls
);
int ldap_compare(
- LDAP *ld,
-
-
-
-Expires: 23 August 1999 [Page 30]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
- const char *dn,
- const char *attr,
- const char *value
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const char *value
);
int ldap_compare_s(
- LDAP *ld,
- const char *dn,
- const char *attr,
- const char *value
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const char *value
);
Parameters are:
ld The session handle.
-dn The name of the entry to compare against.
+dn The name of the entry to compare against. If NULL, a zero
+ length DN is sent to the server.
attr The attribute to compare against.
bvalue The attribute value to compare against those found in the
+
+
+
+Expires: May 2001 [Page 33]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
given entry. This parameter is used in the extended rou-
tines and is a pointer to a struct berval so it is possible
to compare binary values.
ldap_compare_ext() or ldap_compare_ext_s() if you need to
compare binary values.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_compare_ext() call succeeds.
+ request if the ldap_compare_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
The ldap_compare_ext() function initiates an asynchronous compare opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not. See the section below on
-error handling for more information about possible errors and how to
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
interpret them. If successful, ldap_compare_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the compare.
Similar to ldap_compare_ext(), the ldap_compare() function initiates an
asynchronous compare operation and returns the message id of the opera-
tion initiated. As for ldap_compare_ext(), a subsequent call to
-
-
-
-Expires: 23 August 1999 [Page 31]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
ldap_result(), described below, can be used to obtain the result of the
bind. In case of error, ldap_compare() will return -1, setting the ses-
sion error parameters in the LDAP structure appropriately.
The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
-return the result of the operation, either the constant LDAP_SUCCESS if
-the operation was successful, or another LDAP error code if it was not.
-See the section below on error handling for more information about pos-
-sible errors and how to interpret them.
+return the result of the operation: one of the constants
+LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the operation was successful,
+or another LDAP result code if it was not. See the section below on
+error handling for more information about possible errors and how to
+interpret them.
The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
server controls and client controls.
-10.10. Modifying an entry
+
+
+
+
+
+Expires: May 2001 [Page 34]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+11.10. Modifying an entry
The following routines are used to modify an existing LDAP entry. There
are four variations:
+ typedef union mod_vals_u {
+ char **modv_strvals;
+ struct berval **modv_bvals;
+ } mod_vals_u_t;
+
typedef struct ldapmod {
int mod_op;
char *mod_type;
- union {
- char **modv_strvals;
- struct berval **modv_bvals;
- } mod_vals;
+ mod_vals_u_t mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals
#define mod_bvalues mod_vals.modv_bvals
);
int ldap_modify(
-
-
-
-Expires: 23 August 1999 [Page 32]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAP *ld,
const char *dn,
LDAPMod **mods
Parameters are:
+
+
+Expires: May 2001 [Page 35]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
ld The session handle.
-dn The name of the entry to modify.
+dn The name of the entry to modify. If NULL, a zero length DN
+ is sent to the server.
mods A NULL-terminated array of modifications to make to the
entry.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_modify_ext() call succeeds.
+ request if the ldap_modify_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
The fields in the LDAPMod structure have the following meanings:
-mod_op The modification operation to perform. It should be one of
+mod_op The modification operation to perform. It MUST be one of
LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
LDAP_MOD_REPLACE (0x02). This field also indicates the
type of values included in the mod_vals union. It is logi-
mod_type The type of the attribute to modify.
mod_vals The values (if any) to add, delete, or replace. Only one of
- the mod_values or mod_bvalues variants should be used,
+ the mod_values or mod_bvalues variants can be used,
selected by ORing the mod_op field with the constant
LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
zero-terminated strings and mod_bvalues is a NULL-
For LDAP_MOD_ADD modifications, the given values are added to the
entry, creating the attribute if necessary.
-
-
-Expires: 23 August 1999 [Page 33]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
For LDAP_MOD_DELETE modifications, the given values are deleted from the
entry, removing the attribute if no values remain. If the entire attri-
-bute is to be deleted, the mod_vals field should be set to NULL.
+bute is to be deleted, the mod_vals field can be set to NULL.
For LDAP_MOD_REPLACE modifications, the attribute will have the listed
values after the modification, having been created if necessary, or
removed if the mod_vals field is NULL. All modifications are performed
+
+
+
+Expires: May 2001 [Page 36]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
in the order in which they are listed.
The ldap_modify_ext() function initiates an asynchronous modify opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not. See the section below on
-error handling for more information about possible errors and how to
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
interpret them. If successful, ldap_modify_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the modify.
The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
return the result of the operation, either the constant LDAP_SUCCESS if
-the operation was successful, or another LDAP error code if it was not.
+the operation was successful, or another LDAP result code if it was not.
See the section below on error handling for more information about pos-
sible errors and how to interpret them.
server controls and client controls.
-10.11. Modifying the Name of an Entry
+11.11. Modifying the Name of an Entry
In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and
ldap_modrdn2_s() routines were used to change the name of an LDAP entry.
int ldap_rename(
LDAP *ld,
-
-
-
-Expires: 23 August 1999 [Page 34]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
const char *dn,
const char *newrdn,
const char *newparent,
LDAPControl **clientctrls,
int *msgidp
+
+
+Expires: May 2001 [Page 37]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
);
int ldap_rename_s(
LDAP *ld,
LDAPControl **clientctrls
);
- Use of the following routines is deprecated.
+ The use of the following routines is deprecated and more complete
+ descriptions can be found in RFC 1823:
int ldap_modrdn(
LDAP *ld,
ld The session handle.
+dn The name of the entry whose DN is to be changed. If NULL,
+ a zero length DN is sent to the server.
+newrdn The new RDN to give the entry.
+newparent The new parent, or superior entry. If this parameter is
+ NULL, only the RDN of the entry is changed. The root DN
-Expires: 23 August 1999 [Page 35]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-dn The name of the entry whose DN is to be changed.
+Expires: May 2001 [Page 38]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
-newrdn The new RDN to give the entry.
-newparent The new parent, or superior entry. If this parameter is
- NULL, only the RDN of the entry is changed. The root DN
- may be specified by passing a zero length string, "". The
- newparent parameter should always be NULL when using ver-
- sion 2 of the LDAP protocol; otherwise the server's
+ SHOULD be specified by passing a zero length string, "".
+ The newparent parameter SHOULD always be NULL when using
+ version 2 of the LDAP protocol; otherwise the server's
behavior is undefined.
deleteoldrdn This parameter only has meaning on the rename routines if
newrdn is different than the old RDN. It is a boolean
- value, if non-zero indicating that the old RDN value(s)
- should be removed, if zero indicating that the old RDN
- value(s) should be retained as non-distinguished values of
- the entry.
+ value, if non-zero indicating that the old RDN value(s) is
+ to be removed, if zero indicating that the old RDN value(s)
+ is to be retained as non-distinguished values of the entry.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_rename() call succeeds.
+ request if the ldap_rename() call succeeds. The value is
+ undefined if a value other than LDAP_SUCCESS is returned.
The ldap_rename() function initiates an asynchronous modify DN operation
and returns the constant LDAP_SUCCESS if the request was successfully
-sent, or another LDAP error code if not. See the section below on error
-handling for more information about possible errors and how to interpret
-them. If successful, ldap_rename() places the DN message id of the
-request in *msgidp. A subsequent call to ldap_result(), described below,
-can be used to obtain the result of the rename.
+sent, or another LDAP result code if not. See the section below on
+error handling for more information about possible errors and how to
+interpret them. If successful, ldap_rename() places the DN message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the rename.
The synchronous ldap_rename_s() returns the result of the operation,
either the constant LDAP_SUCCESS if the operation was successful, or
-another LDAP error code if it was not. See the section below on error
+another LDAP result code if it was not. See the section below on error
handling for more information about possible errors and how to interpret
them.
server controls and client controls.
-10.12. Adding an entry
+11.12. Adding an entry
The following functions are used to add entries to the LDAP directory.
There are four variations:
+ int ldap_add_ext(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **attrs,
-Expires: 23 August 1999 [Page 36]
+Expires: May 2001 [Page 39]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
- int ldap_add_ext(
- LDAP *ld,
- const char *dn,
- LDAPMod **attrs,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
ld The session handle.
-dn The name of the entry to add.
+dn The name of the entry to add. If NULL, a zero length DN is
+ sent to the server.
attrs The entry's attributes, specified using the LDAPMod struc-
ture defined for ldap_modify(). The mod_type and mod_vals
- fields should be filled in. The mod_op field is ignored
+ fields MUST be filled in. The mod_op field is ignored
unless ORed with the constant LDAP_MOD_BVALUES, used to
select the mod_bvalues case of the mod_vals union.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_add_ext() call succeeds.
+ request if the ldap_add_ext() call succeeds. The value is
+ undefined if a value other than LDAP_SUCCESS is returned.
-Expires: 23 August 1999 [Page 37]
+Expires: May 2001 [Page 40]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
Note that the parent of the entry being added must already exist or the
The ldap_add_ext() function initiates an asynchronous add operation and
returns the constant LDAP_SUCCESS if the request was successfully sent,
-or another LDAP error code if not. See the section below on error han-
+or another LDAP result code if not. See the section below on error han-
dling for more information about possible errors and how to interpret
them. If successful, ldap_add_ext() places the message id of the
request in *msgidp. A subsequent call to ldap_result(), described below,
The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
the result of the operation, either the constant LDAP_SUCCESS if the
-operation was successful, or another LDAP error code if it was not. See
-the section below on error handling for more information about possible
-errors and how to interpret them.
+operation was successful, or another LDAP result code if it was not.
+See the section below on error handling for more information about pos-
+sible errors and how to interpret them.
The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
controls and client controls.
-10.13. Deleting an entry
+11.13. Deleting an entry
The following functions are used to delete a leaf entry from the LDAP
directory. There are four variations:
-Expires: 23 August 1999 [Page 38]
+Expires: May 2001 [Page 41]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
ld The session handle.
-dn The name of the entry to delete.
+dn The name of the entry to delete. If NULL, a zero length DN
+ is sent to the server.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
msgidp This result parameter will be set to the message id of the
- request if the ldap_delete_ext() call succeeds.
+ request if the ldap_delete_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
Note that the entry to delete must be a leaf entry (i.e., it must have
no children). Deletion of entire subtrees in a single operation is not
The ldap_delete_ext() function initiates an asynchronous delete opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not. See the section below on
-error handling for more information about possible errors and how to
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
interpret them. If successful, ldap_delete_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the delete.
delete. In case of error, ldap_delete() will return -1, setting the ses-
sion error parameters in the LDAP structure appropriately.
-The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
-return the result of the operation, either the constant LDAP_SUCCESS if
-the operation was successful, or another LDAP error code if it was not.
-See the section below on error handling for more information about pos-
-sible errors and how to interpret them.
-Expires: 23 August 1999 [Page 39]
+Expires: May 2001 [Page 42]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
+return the result of the operation, either the constant LDAP_SUCCESS if
+the operation was successful, or another LDAP result code if it was not.
+See the section below on error handling for more information about pos-
+sible errors and how to interpret them.
+
The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
server controls and client controls.
-10.14. Extended Operations
+11.14. Extended Operations
The ldap_extended_operation() and ldap_extended_operation_s() routines
allow extended LDAP operations to be passed to the server, providing a
general protocol extensibility mechanism.
int ldap_extended_operation(
- LDAP *ld,
- const char *exoid,
- struct berval *exdata,
- LDAPControl **serverctrls,
- LDAPControl **clientctrls,
- int *msgidp
+ LDAP *ld,
+ const char *requestoid,
+ const struct berval *requestdata,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
);
int ldap_extended_operation_s(
- LDAP *ld,
- const char *exoid,
- struct berval *exdata,
- LDAPControl **serverctrls,
- LDAPControl **clientctrls,
- char **retoidp,
- struct berval **retdatap
+ LDAP *ld,
+ const char *requestoid,
+ const struct berval *requestdata,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ char **retoidp,
+ struct berval **retdatap
);
Parameters are:
requestoid The dotted-OID text string naming the request.
-requestdata The arbitrary data required by the operation (if NULL, no
+requestdata The arbitrary data needed by the operation (if NULL, no
data is sent to the server).
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
-msgidp This result parameter will be set to the message id of the
- request if the ldap_extended_operation() call succeeds.
-retoidp Pointer to a character string that will be set to an allo-
- cated, dotted-OID text string returned by the server. This
- string should be disposed of using the ldap_memfree()
+Expires: May 2001 [Page 43]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
-Expires: 23 August 1999 [Page 40]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ to be used.
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_extended_operation() call succeeds. The
+ value is undefined if a value other than LDAP_SUCCESS is
+ returned.
- function. If no OID was returned, *retoidp is set to NULL.
+retoidp Pointer to a character string that will be set to an allo-
+ cated, dotted-OID text string returned by the server. This
+ string SHOULD be disposed of using the ldap_memfree() func-
+ tion. If an API error occurs or no OID is returned by the
+ server, *retoidp is set to NULL.
retdatap Pointer to a berval structure pointer that will be set an
allocated copy of the data returned by the server. This
- struct berval should be disposed of using ber_bvfree(). If
- no data is returned, *retdatap is set to NULL.
+ struct berval SHOULD be disposed of using ber_bvfree(). If
+ an API error occurs or no data is returned by the server,
+ *retdatap is set to NULL.
The ldap_extended_operation() function initiates an asynchronous
extended operation and returns the constant LDAP_SUCCESS if the request
-was successfully sent, or another LDAP error code if not. See the sec-
+was successfully sent, or another LDAP result code if not. See the sec-
tion below on error handling for more information about possible errors
and how to interpret them. If successful, ldap_extended_operation()
places the message id of the request in *msgidp. A subsequent call to
The synchronous ldap_extended_operation_s() function returns the result
of the operation, either the constant LDAP_SUCCESS if the operation was
-successful, or another LDAP error code if it was not. See the section
+successful, or another LDAP result code if it was not. See the section
below on error handling for more information about possible errors and
how to interpret them. The retoid and retdata parameters are filled in
-with the OID and data from the response. If no OID or data was
-returned, these parameters are set to NULL.
+with the OID and data from the response.
The ldap_extended_operation() and ldap_extended_operation_s() functions
both support LDAPv3 server controls and client controls.
-11. Abandoning An Operation
+12. Abandoning An Operation
The following calls are used to abandon an operation in progress:
LDAP *ld,
int msgid,
LDAPControl **serverctrls,
+
+
+
+Expires: May 2001 [Page 44]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
LDAPControl **clientctrls
);
ld The session handle.
-
-
-
-Expires: 23 August 1999 [Page 41]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
msgid The message id of the request to be abandoned.
-serverctrls List of LDAP server controls.
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
-clientctrls List of client controls.
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
ldap_abandon_ext() abandons the operation with message id msgid and
returns the constant LDAP_SUCCESS if the abandon was successful or
-another LDAP error code if not. See the section below on error handling
-for more information about possible errors and how to interpret them.
+another LDAP result code if not. See the section below on error han-
+dling for more information about possible errors and how to interpret
+them.
ldap_abandon() is identical to ldap_abandon_ext() except that it does
not accept client or server controls and it returns zero if the abandon
ldap_result(). There is no server response to LDAP abandon operations.
-12. Obtaining Results and Peeking Inside LDAP Messages
+13. Obtaining Results and Peeking Inside LDAP Messages
ldap_result() is used to obtain the result of a previous asynchronously
initiated operation. Note that depending on how it is called,
-ldap_result() may actually return a list or "chain" of result messages.
+ldap_result() can actually return a list or "chain" of result messages.
The ldap_result() function only returns messages for a single request,
so for all LDAP operations other than search only one result message is
-expected; that is, the only time the "result chain" may contain more
+expected; that is, the only time the "result chain" can contain more
than one message is if results from a search operation are returned.
Once a chain of messages has been returned to the caller, it is no
longer tied in any caller-visible way to the LDAP request that produced
-it. Therefore, a chain of messages returned by calling ldap_result() or
-by calling a synchronous search routine will never be affected by subse-
-quent LDAP API calls (except for ldap_msgfree() which is used to dispose
-of a chain of messages).
+it. However, it MAY be tied to the session handle. Therefore, a chain
+of messages returned by calling ldap_result() or by calling a synchro-
+nous search routine will never be affected by subsequent LDAP API calls
+
+
+
+Expires: May 2001 [Page 45]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+except for ldap_msgfree() (which is used to dispose of a chain of mes-
+sages) and the unbind calls (which dispose of a session handle):
+ldap_unbind(), ldap_unbind_s(), or ldap_unbind_ext(), or functions
+defined by extensions of this API.
ldap_msgfree() frees the result messages (possibly an entire chain of
messages) obtained from a previous call to ldap_result() or from a call
to a synchronous search routine.
-ldap_msgtype() returns the type of an LDAP message. ldap_msgid()
-returns the message ID of an LDAP message.
+ldap_msgtype() returns the type of an LDAP message.
+
+ldap_msgid() returns the message ID of an LDAP message.
int ldap_result(
LDAP *ld,
int msgid,
int all,
struct timeval *timeout,
-
-
-
-Expires: 23 August 1999 [Page 42]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAPMessage **res
);
ld The session handle.
msgid The message id of the operation whose results are to be
- returned, or the constant LDAP_RES_ANY (-1) if any result is
- desired.
+ returned, the constant LDAP_RES_UNSOLICITED (0) if an unsoli-
+ cited result is desired, or or the constant LDAP_RES_ANY (-1)
+ if any result is desired.
all Specifies how many messages will be retrieved in a single call
to ldap_result(). This parameter only has meaning for search
message at a time. Pass LDAP_MSG_ALL (0x01) to request that
all results of a search be received before returning all
results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to
- indicate that all messages retrieved so far should be returned
+ indicate that all messages retrieved so far are to be returned
in the result chain.
timeout A timeout specifying how long to wait for results to be
returned. A NULL value causes ldap_result() to block until
- results are available. A timeout value of zero seconds speci-
- fies a polling behavior.
+ results are available. A timeout value of zero seconds
+
+
+
+Expires: May 2001 [Page 46]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ specifies a polling behavior.
res For ldap_result(), a result parameter that will contain the
- result(s) of the operation. If no results are returned, *res is
- set to NULL. For ldap_msgfree(), the result chain to be freed,
- obtained from a previous call to ldap_result(),
- ldap_search_s(), or ldap_search_st(). If res is NULL, nothing
- is done and ldap_msgfree() returns zero.
+ result(s) of the operation. If an API error occurs or no
+ results are returned, *res is set to NULL. For ldap_msgfree(),
+ the result chain to be freed, obtained from a previous call to
+ ldap_result(), ldap_search_s(), or ldap_search_st(). If res is
+ NULL, nothing is done and ldap_msgfree() returns zero.
Upon successful completion, ldap_result() returns the type of the first
result returned in the res parameter. This will be one of the following
LDAP_RES_SEARCH_RESULT (0x65)
LDAP_RES_MODIFY (0x67)
LDAP_RES_ADD (0x69)
-
-
-
-Expires: 23 August 1999 [Page 43]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAP_RES_DELETE (0x6B)
LDAP_RES_MODDN (0x6D)
LDAP_RES_COMPARE (0x6F)
occurs, in which case the error parameters of the LDAP session handle
will be set accordingly.
-ldap_msgfree() frees the result structure pointed to by res and returns
-the type of the message it freed. If res is NULL, nothing is done and
-the value zero is returned.
+ldap_msgfree() frees each message in the result chain pointed to by res
+and returns the type of the last message in the chain. If res is NULL,
+nothing is done and the value zero is returned.
ldap_msgtype() returns the type of the LDAP message it is passed as a
parameter. The type will be one of the types listed above, or -1 on
error.
ldap_msgid() returns the message ID associated with the LDAP message
-passed as a parameter.
+passed as a parameter, or -1 on error.
-13. Handling Errors and Parsing Results
+14. Handling Errors and Parsing Results
The following calls are used to extract information from results and
handle errors returned by other LDAP API routines. Note that
ically be used in addition to ldap_parse_result() to retrieve all the
result information from SASL Bind and Extended Operations respectively.
+
+
+
+Expires: May 2001 [Page 47]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
int ldap_parse_result(
LDAP *ld,
LDAPMessage *res,
);
int ldap_parse_extended_result(
-
-
-
-Expires: 23 August 1999 [Page 44]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAP *ld,
LDAPMessage *res,
char **retoidp,
int freeit
);
+ #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036"
+
char *ldap_err2string( int err );
- The use of the following routines is deprecated.
+ The use of the following routines is deprecated and more complete
+ descriptions can be found in RFC 1823:
int ldap_result2error(
LDAP *ld,
ldap_result() or one of the synchronous API operation
calls.
-errcodep This result parameter will be filled in with the LDAP error
- code field from the LDAPMessage message. This is the indi-
- cation from the server of the outcome of the operation.
- NULL may be passed to ignore this field.
-matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result
- parameter will be filled in with a DN indicating how much
- of the name in the request was recognized. NULL may be
- passed to ignore this field. The matched DN string should
- be freed by calling ldap_memfree() which is described later
- in this document.
+
+Expires: May 2001 [Page 48]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+errcodep This result parameter will be filled in with the LDAP
+ resultCode field from the LDAPMessage message. This is the
+ indication from the server of the outcome of the operation.
+ NULL SHOULD be passed to ignore this field.
+
+matcheddnp If the server returned a matchedDN string to indicate how
+ much of a name passed in a request was recognized, this
+ result parameter will be filled in with that matchedDN
+ string. Otherwise, this field will be set to NULL. NULL
+ SHOULD be passed to ignore this field. The matched DN
+ string SHOULD be freed by calling ldap_memfree() which is
+ described later in this document. Note that the server may
+ return a zero length matchedDN (in which case *matchednp is
+ set to an allocated copy of "") which is different than not
+ returning a value at all (in which case *matcheddnp is set
+ to NULL).
errmsgp This result parameter will be filled in with the contents
of the error message field from the LDAPMessage message.
- The error message string should be freed by calling
+ The error message string SHOULD be freed by calling
ldap_memfree() which is described later in this document.
- NULL may be passed to ignore this field.
+ NULL SHOULD be passed to ignore this field.
referralsp This result parameter will be filled in with the contents
of the referrals field from the LDAPMessage message, indi-
cating zero or more alternate LDAP servers where the
-
-
-
-Expires: 23 August 1999 [Page 45]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
- request should be retried. The referrals array should be
+ request is to be retried. The referrals array SHOULD be
freed by calling ldap_value_free() which is described later
- in this document. NULL may be passed to ignore this field.
+ in this document. NULL SHOULD be passed to ignore this
+ field. If no referrals were returned, *referralsp is set
+ to NULL.
serverctrlsp This result parameter will be filled in with an allocated
array of controls copied out of the LDAPMessage message.
- The control array should be freed by calling
- ldap_controls_free() which was described earlier.
+ If serverctrlsp is NULL, no controls are returned. The
+ control array SHOULD be freed by calling
+ ldap_controls_free() which was described earlier. If no
+ controls were returned, *serverctrlsp is set to NULL.
freeit A boolean that determines whether the res parameter is
disposed of or not. Pass any non-zero value to have these
is disposed of.
servercredp For SASL bind results, this result parameter will be filled
+
+
+
+Expires: May 2001 [Page 49]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
in with the credentials passed back by the server for
mutual authentication, if given. An allocated berval struc-
- ture is returned that should be disposed of by calling
- ber_bvfree(). NULL may be passed to ignore this field.
+ ture is returned that SHOULD be disposed of by calling
+ ber_bvfree(). NULL SHOULD be passed to ignore this field.
retoidp For extended results, this result parameter will be filled
in with the dotted-OID text representation of the name of
- the extended operation response. This string should be
- disposed of by calling ldap_memfree(). NULL may be passed
- to ignore this field.
+ the extended operation response. This string SHOULD be
+ disposed of by calling ldap_memfree(). NULL SHOULD be
+ passed to ignore this field. If no OID was returned,
+ *retoidp is set to NULL. The LDAP_NOTICE_OF_DISCONNECTION
+ macro is defined as a convenience for clients that wish to
+ check an OID to see if it matches the one used for the
+ unsolicited Notice of Disconnection (defined in RFC 2251[2]
+ section 4.4.1).
retdatap For extended results, this result parameter will be filled
in with a pointer to a struct berval containing the data in
- the extended operation response. It should be disposed of
- by calling ber_bvfree(). NULL may be passed to ignore this
- field.
+ the extended operation response. It SHOULD be disposed of
+ by calling ber_bvfree(). NULL SHOULD be passed to ignore
+ this field. If no data is returned, *retdatap is set to
+ NULL.
-err For ldap_err2string(), an LDAP error code, as returned by
+err For ldap_err2string(), an LDAP result code, as returned by
ldap_parse_result() or another LDAP API call.
Additional parameters for the deprecated routines are not described.
Interested readers are referred to RFC 1823.
-All three of the ldap_parse_*_result() routines skip over messages of
-type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking
-for a result message to parse. They return the constant LDAP_SUCCESS if
-the result was successfully parsed and another LDAP error code if not.
-Note that the LDAP error code that indicates the outcome of the opera-
-tion performed by the server is placed in the errcodep
-ldap_parse_result() parameter. If a chain of messages that contains
-
-
-
-Expires: 23 August 1999 [Page 46]
+The ldap_parse_result(), ldap_parse_sasl_bind_result(), and
+ldap_parse_extended_result() functions all skip over messages of type
+LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a
+result message to parse. They return the constant LDAP_SUCCESS if the
+result was successfully parsed and another LDAP API result code if not.
+If a value other than LDAP_SUCCESS is returned, the values of all the
+result parameters are undefined. Note that the LDAP result code that
+indicates the outcome of the operation performed by the server is placed
+in the errcodep ldap_parse_result() parameter. If a chain of messages
+that contains more than one result message is passed to these routines
+they always operate on the first result in the chain.
+
+ldap_err2string() is used to convert a numeric LDAP result code, as
+returned by ldap_parse_result(), ldap_parse_sasl_bind_result(),
+ldap_parse_extended_result() or one of the synchronous API operation
+calls, into an informative zero-terminated character string message
+describing the error. It returns a pointer to static data and it MUST
+NOT return NULL; the value returned is always a valid null-terminated
+"C" string.
+
+
+
+Expires: May 2001 [Page 50]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
-more than one result message is passed to these routines they always
-operate on the first result in the chain.
+C LDAP API C LDAP Application Program Interface 17 November 2000
-ldap_err2string() is used to convert a numeric LDAP error code, as
-returned by one of the three ldap_parse_*_result() routines, or one of
-the synchronous API operation calls, into an informative zero-terminated
-character string message describing the error. It returns a pointer to
-static data.
-
-14. Stepping Through a List of Results
+15. Stepping Through a List of Results
The ldap_first_message() and ldap_next_message() routines are used to
step through the list of messages in a result chain returned by
-ldap_result(). For search operations, the result chain may actually
+ldap_result(). For search operations, the result chain can actually
include referral messages, entry messages, and result messages.
ldap_count_messages() is used to count the number of messages returned.
The ldap_msgtype() function, described above, can be used to distinguish
case the error parameters in the session handle ld will be set to indi-
cate the error.
-ldap_count_messages() returns the number of messages contained in a
-chain of results. It can also be used to count the number of messages
-that remain in a chain if called with a message, entry, or reference
-returned by ldap_first_message(), ldap_next_message(),
-ldap_first_entry(), ldap_next_entry(), ldap_first_reference(),
-ldap_next_reference().
+If successful, ldap_count_messages() returns the number of messages con-
+tained in a chain of results; if an error occurs such as the res parame-
+ter being invalid, -1 is returned. The ldap_count_messages() call can
+also be used to count the number of messages that remain in a chain if
+called with a message, entry, or reference returned by
+ldap_first_message(), ldap_next_message(), ldap_first_entry(),
+ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
+16. Parsing Search Results
-Expires: 23 August 1999 [Page 47]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+The following calls are used to parse the entries and references
+returned by ldap_search() and friends. These results are returned in an
+opaque structure that MAY be accessed by calling the routines described
+below. Routines are provided to step through the entries and references
+returned, step through the attributes of an entry, retrieve the name of
-15. Parsing Search Results
-The following calls are used to parse the entries and references
-returned by ldap_search() and friends. These results are returned in an
-opaque structure that should only be accessed by calling the routines
-described below. Routines are provided to step through the entries and
-references returned, step through the attributes of an entry, retrieve
-the name of an entry, and retrieve the values associated with a given
-attribute in an entry.
+Expires: May 2001 [Page 51]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
-15.1. Stepping Through a List of Entries or References
+an entry, and retrieve the values associated with a given attribute in
+an entry.
+
+
+16.1. Stepping Through a List of Entries or References
The ldap_first_entry() and ldap_next_entry() routines are used to step
through and retrieve the list of entries from a search result chain.
ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and
ldap_next_reference() all return NULL when no more entries or references
-
-
-
-Expires: 23 August 1999 [Page 48]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
exist in the result set to be returned. NULL is also returned if an
error occurs while stepping through the entries or references, in which
case the error parameters in the session handle ld will be set to indi-
cate the error.
ldap_count_entries() returns the number of entries contained in a chain
-of entries. It can also be used to count the number of entries that
-remain in a chain if called with a message, entry or reference returned
-by ldap_first_message(), ldap_next_message(), ldap_first_entry(),
-ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
+of entries; if an error occurs such as the res parameter being invalid,
+
+
+
+Expires: May 2001 [Page 52]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+-1 is returned. The ldap_count_entries() call can also be used to count
+the number of entries that remain in a chain if called with a message,
+entry or reference returned by ldap_first_message(),
+ldap_next_message(), ldap_first_entry(), ldap_next_entry(),
+ldap_first_reference(), ldap_next_reference().
ldap_count_references() returns the number of references contained in a
-chain of search results. It can also be used to count the number of
-references that remain in a chain.
+chain of search results; if an error occurs such as the res parameter
+being invalid, -1 is returned. The ldap_count_references() call can
+also be used to count the number of references that remain in a chain.
-15.2. Stepping Through the Attributes of an Entry
+16.2. Stepping Through the Attributes of an Entry
The ldap_first_attribute() and ldap_next_attribute() calls are used to
step through the list of attribute types returned with an entry.
structure that is described in more detail later in this document
in the section "Encoded ASN.1 Value Manipulation".
+mem A pointer to memory allocated by the LDAP library, such as the
+ attribute type names returned by ldap_first_attribute() and
+ ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem
+
-Expires: 23 August 1999 [Page 49]
+Expires: May 2001 [Page 53]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
-mem A pointer to memory allocated by the LDAP library, such as the
- attribute type names returned by ldap_first_attribute() and
- ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem
- is NULL, nothing is done.
+ is NULL, the ldap_memfree() call does nothing.
ldap_first_attribute() and ldap_next_attribute() will return NULL when
the end of the attributes is reached, or if there is an error, in which
cate the error.
Both routines return a pointer to an allocated buffer containing the
-current attribute name. This should be freed when no longer in use by
+current attribute name. This SHOULD be freed when no longer in use by
calling ldap_memfree().
ldap_first_attribute() will allocate and return in ptr a pointer to a
-BerElement used to keep track of the current position. This pointer
-should be passed in subsequent calls to ldap_next_attribute() to step
-through the entry's attributes. After a set of calls to
-ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it
-should be freed by calling ber_free( ptr, 0 ). Note that it is very
-important to pass the second parameter as 0 (zero) in this call, since
-the buffer associated with the BerElement does not point to separately
-allocated memory.
+BerElement used to keep track of the current position. This pointer MAY
+be passed in subsequent calls to ldap_next_attribute() to step through
+the entry's attributes. After a set of calls to ldap_first_attribute()
+and ldap_next_attribute(), if ptr is non-NULL, it SHOULD be freed by
+calling ber_free( ptr, 0 ). Note that it is very important to pass the
+second parameter as 0 (zero) in this call, since the buffer associated
+with the BerElement does not point to separately allocated memory.
The attribute type names returned are suitable for passing in a call to
ldap_get_values() and friends to retrieve the associated values.
-15.3. Retrieving the Values of an Attribute
+16.3. Retrieving the Values of an Attribute
ldap_get_values() and ldap_get_values_len() are used to retrieve the
values of a given attribute from an entry. ldap_count_values() and
int ldap_count_values( char **vals );
+ int ldap_count_values_len( struct berval **vals );
+ void ldap_value_free( char **vals );
-Expires: 23 August 1999 [Page 50]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
- int ldap_count_values_len( struct berval **vals );
+Expires: May 2001 [Page 54]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
- void ldap_value_free( char **vals );
void ldap_value_free_len( struct berval **vals );
ldap_count_values() and ldap_count_values_len() return -1 if an error
occurs such as the vals parameter being invalid.
-Note that the values returned are dynamically allocated and should be
+If a NULL vals parameter is passed to ldap_value_free() or
+ldap_value_free_len(), nothing is done.
+
+Note that the values returned are dynamically allocated and SHOULD be
freed by calling either ldap_value_free() or ldap_value_free_len() when
no longer in use.
-15.4. Retrieving the name of an entry
+16.4. Retrieving the name of an entry
ldap_get_dn() is used to retrieve the name of an entry.
ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
char **ldap_explode_rdn( const char *rdn, int notypes );
+ char *ldap_dn2ufn( const char *dn );
-Expires: 23 August 1999 [Page 51]
+Expires: May 2001 [Page 55]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
- char *ldap_dn2ufn( const char *dn );
-
Parameters are:
ld The session handle.
entry The entry whose name is to be retrieved, as returned by
ldap_first_entry() or ldap_next_entry().
-dn The dn to explode, such as returned by ldap_get_dn().
+dn The dn to explode, such as returned by ldap_get_dn(). If NULL,
+ a zero length DN is used.
rdn The rdn to explode, such as returned in the components of the
- array returned by ldap_explode_dn().
+ array returned by ldap_explode_dn(). If NULL, a zero length DN
+ is used.
notypes A boolean parameter, if non-zero indicating that the dn or rdn
- components should have their type information stripped off
+ components are to have their type information stripped off
(i.e., "cn=Babs" would become "Babs").
ldap_get_dn() will return NULL if there is some error parsing the dn,
setting error parameters in the session handle ld to indicate the error.
-It returns a pointer to newly allocated space that the caller should
+It returns a pointer to newly allocated space that the caller SHOULD
free by calling ldap_memfree() when it is no longer in use. Note the
-format of the DNs returned is given by [4].
+format of the DNs returned is given by [5]. The root DN is returned as
+a zero length string ("").
ldap_explode_dn() returns a NULL-terminated char * array containing the
RDN components of the DN supplied, with or without types as indicated by
the notypes parameter. The components are returned in the order they
-appear in the dn. The array returned should be freed when it is no
+appear in the dn. The array returned SHOULD be freed when it is no
longer in use by calling ldap_value_free().
ldap_explode_rdn() returns a NULL-terminated char * array containing the
components of the RDN supplied, with or without types as indicated by
the notypes parameter. The components are returned in the order they
-appear in the rdn. The array returned should be freed when it is no
+appear in the rdn. The array returned SHOULD be freed when it is no
longer in use by calling ldap_value_free().
ldap_dn2ufn() converts the DN into the user friendly format described in
-[5]. The UFN returned is newly allocated space that should be freed by a
-call to ldap_memfree() when no longer in use.
+[14]. The UFN returned is newly allocated space that SHOULD be freed by
+a call to ldap_memfree() when no longer in use.
-15.5. Retrieving controls from an entry
+16.5. Retrieving controls from an entry
ldap_get_entry_controls() is used to extract LDAP controls from an
entry.
- int ldap_get_entry_controls(
-Expires: 23 August 1999 [Page 52]
+Expires: May 2001 [Page 56]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+ int ldap_get_entry_controls(
LDAP *ld,
LDAPMessage *entry,
LDAPControl ***serverctrlsp
serverctrlsp This result parameter will be filled in with an allocated
array of controls copied out of entry. The control array
- should be freed by calling ldap_controls_free(). If ser-
- verctrlsp is NULL, no controls are returned.
+ SHOULD be freed by calling ldap_controls_free(). If ser-
+ verctrlsp is NULL, no controls are returned. If no con-
+ trols were returned, *serverctrlsp is set to NULL.
-ldap_get_entry_controls() returns an LDAP error code that indicates
+ldap_get_entry_controls() returns an LDAP result code that indicates
whether the reference could be successfully parsed (LDAP_SUCCESS if all
-goes well).
+goes well). If ldap_get_entry_controls() returns a value other than
+LDAP_SUCCESS, the value of the serverctrlsp output parameter is unde-
+fined.
-15.6. Parsing References
+16.6. Parsing References
ldap_parse_reference() is used to extract referrals and controls from a
SearchResultReference message.
ref The reference to parse, as returned by ldap_result(),
ldap_first_reference(), or ldap_next_reference().
-referralsp This result parameter will be filled in with an allocated
- array of character strings. The elements of the array are
- the referrals (typically LDAP URLs) contained in ref. The
- array should be freed when no longer in used by calling
-Expires: 23 August 1999 [Page 53]
+Expires: May 2001 [Page 57]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+referralsp This result parameter will be filled in with an allocated
+ array of character strings. The elements of the array are
+ the referrals (typically LDAP URLs) contained in ref. The
+ array SHOULD be freed when no longer in used by calling
ldap_value_free(). If referralsp is NULL, the referral
- URLs are not returned.
+ URLs are not returned. If no referrals were returned,
+ *referralsp is set to NULL.
serverctrlsp This result parameter will be filled in with an allocated
array of controls copied out of ref. The control array
- should be freed by calling ldap_controls_free(). If ser-
- verctrlsp is NULL, no controls are returned.
+ SHOULD be freed by calling ldap_controls_free(). If ser-
+ verctrlsp is NULL, no controls are returned. If no con-
+ trols were returned, *serverctrlsp is set to NULL.
freeit A boolean that determines whether the ref parameter is
disposed of or not. Pass any non-zero value to have this
tion. This is provided as a convenience; you can also use
ldap_msgfree() to free the result later.
-ldap_parse_reference() returns an LDAP error code that indicates whether
-the reference could be successfully parsed (LDAP_SUCCESS if all goes
-well).
+ldap_parse_reference() returns an LDAP result code that indicates
+whether the reference could be successfully parsed (LDAP_SUCCESS if all
+goes well). If a value other than LDAP_SUCCESS is returned, the value
+of the referralsp and serverctrlsp result parameters are undefined.
+
-16. Encoded ASN.1 Value Manipulation
+17. Encoded ASN.1 Value Manipulation
-This section describes routines which may be used to encode and decode
+This section describes routines which MAY be used to encode and decode
BER-encoded ASN.1 values, which are often used inside of control and
extension values.
these functions are compatible with the University of Michigan LDAP 3.3
implementation of BER.
+Note that the functions defined in this section all provide a method for
+determining success or failure but generally do not provide access to
+specific error codes. Therefore, applications that require precise
+error information when encoding or decoding ASN.1 values SHOULD NOT use
+these functions.
+
+
+17.1. BER Data Structures and Types
+
+The following additional integral types are defined for use in manipula-
+tion of BER encoded ASN.1 values:
+
+
+
+Expires: May 2001 [Page 58]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ typedef <impl_tag_t> ber_tag_t; /* for BER tags */
+
+ typedef <impl_int_t> ber_int_t; /* for BER ints, enums, and Booleans */
+
+ typedef <impl_unit_t> ber_uint_t; /* unsigned equivalent of ber_uint_t */
+
+ typedef <impl_slen_t> ber_slen_t; /* signed equivalent of ber_len_t */
+
+Note that the actual definition for these four integral types is imple-
+mentation specific; that is, `<impl_tag_t>', `<impl_int_t>',
+`<impl_uint_t>', and `<impl_slen_t>' MUST each be replaced with an
+appropriate implementation-specific type.
-16.1. General
+The `ber_tag_t' type is an unsigned integral data type that is large
+enough to hold the largest BER tag supported by the API implementation.
+The width (number of significant bits) of `ber_tag_t' MUST be at least
+32, greater than or equal to that of `unsigned int' (so that integer
+promotions won't promote it to `int'), and no wider than that of
+`unsigned long'.
- struct berval {
- unsigned long bv_len;
+The `ber_int_t' and `ber_uint_t' types are the signed and unsigned vari-
+ants of an integral type that is large enough to hold integers for pur-
+poses of BER encoding and decoding. The width of `ber_int_t' MUST be at
+least 32 and no larger than that of `long'.
+
+The `ber_slen_t' type is the signed variant of the `ber_len_t' integral
+type, i.e. if `ber_len_t' is unsigned long, then `ber_slen_t' is signed
+long. The `<impl_slen_t>' in the `ber_len_t' typedef MUST be replaced
+with an appropriate type. Note that `ber_slen_t' is not used directly
+in the C LDAP API but is provided for the convenience of application
+developers and for use by extensions to the API.
+
+ typedef struct berval {
+ ber_len_t bv_len;
char *bv_val;
- };
+ } BerValue;
-A struct berval contains a sequence of bytes and an indication of its
-length. The bv_val is not necessarily zero-terminated. bv_len must
-always be a nonnegative number. Applications may allocate their own
+As defined earlier in the section "Common Data Structures", a berval
+structure contains an arbitrary sequence of bytes and an indication of
+its length. The bv_len element is an unsigned integer. The bv_val is
+not necessarily zero-terminated. Applications MAY allocate their own
berval structures.
-As defined earlier, the BerElement structure is an opaque structure:
+As defined earlier in the section "Common Data Structures", the BerEle-
+ment structure is an opaque structure:
typedef struct berelement BerElement;
-It contains not only a copy of the encoded value, but also state infor-
-mation used in encoding or decoding. Applications cannot allocate their
-Expires: 23 August 1999 [Page 54]
+Expires: May 2001 [Page 59]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+It contains not only a copy of the encoded value, but also state infor-
+mation used in encoding or decoding. Applications cannot allocate their
own BerElement structures. The internal state is neither thread-
-specific nor locked, so two threads should not manipulate the same
+specific nor locked, so two threads SHOULD NOT manipulate the same
BerElement value simultaneously.
A single BerElement value cannot be used for both encoding and decoding.
+17.2. Memory Disposal and Utility Functions
+
void ber_bvfree( struct berval *bv );
-ber_bvfree() frees a berval returned from this API. Both the bv->bv_val
-string and the berval itself are freed. Applications should not use
-ber_bvfree() with bervals which the application has allocated.
+ber_bvfree() frees a berval structure returned from this API. Both the
+bv->bv_val string and the berval structure itself are freed. If bv is
+NULL, this call does nothing.
void ber_bvecfree( struct berval **bv );
-ber_bvecfree() frees an array of bervals returned from this API. Each
-of the bervals in the array are freed using ber_bvfree(), then the array
-itself is freed.
+ber_bvecfree() frees an array of berval structures returned from this
+API. Each of the berval structures in the array are freed using
+ber_bvfree(), then the array itself is freed. If bv is NULL, this call
+does nothing.
struct berval *ber_bvdup( const struct berval *bv );
-ber_bvdup() returns a copy of a berval. The bv_val field in the
-returned berval points to a different area of memory than the bv_val
-field in the argument berval. The NULL pointer is returned on error
-(e.g. out of memory).
+ber_bvdup() returns a copy of a berval structure. The bv_val field in
+the returned berval structure points to a different area of memory than
+the bv_val field in the bv argument. The NULL pointer is returned on
+error (e.g. out of memory).
void ber_free( BerElement *ber, int fbuf );
ber_free() frees a BerElement which is returned from the API calls
-ber_alloc_t() or ber_init(). Each BerElement must be freed by the
-caller. The second argument fbuf should always be set to 1 to ensure
+ber_alloc_t() or ber_init(). Each BerElement SHOULD be freed by the
+caller. The second argument fbuf SHOULD always be set to 1 to ensure
that the internal buffer used by the BER functions is freed as well as
-the BerElement container itself.
+the BerElement container itself. If ber is NULL, this call does noth-
+ing.
-16.2. Encoding
+17.3. Encoding
BerElement *ber_alloc_t( int options );
ber_alloc_t() constructs and returns BerElement. The NULL pointer is
returned on error. The options field contains a bitwise-or of options
which are to be used when generating the encoding of this BerElement.
-One option is defined and must always be supplied:
-
- #define LBER_USE_DER 0x01
-
-When this option is present, lengths will always be encoded in the
-minimum number of octets. Note that this option does not cause values
-of sets to be rearranged in tag and byte order or default values to be
+One option is defined and SHOULD always be supplied:
-Expires: 23 August 1999 [Page 55]
+Expires: May 2001 [Page 60]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+ #define LBER_USE_DER 0x01
+When this option is present, lengths will always be encoded in the
+minimum number of octets. Note that this option does not cause values
+of sets to be rearranged in tag and byte order or default values to be
removed, so these functions are not sufficient for generating DER output
as defined in X.509 and X.680. If the caller takes responsibility for
ordering values of sets correctly and removing default values, DER out-
The BerElement returned by ber_alloc_t() is initially empty. Calls to
ber_printf() will append bytes to the end of the ber_alloc_t().
- int ber_printf( BerElement *ber, const char *fmt, ... )
+ int ber_printf( BerElement *ber, const char *fmt, ... );
The ber_printf() routine is used to encode a BER element in much the
same way that sprintf() works. One important difference, though, is
that state information is kept in the ber argument so that multiple
calls can be made to ber_printf() to append to the end of the BER ele-
-ment. ber must be a pointer to a BerElement returned by ber_alloc_t().
+ment. ber MUST be a pointer to a BerElement returned by ber_alloc_t().
ber_printf() interprets and formats its arguments according to the for-
mat string fmt. ber_printf() returns -1 if there is an error during
-encoding and a positive number if successful. As with sprintf(), each
-character in fmt refers to an argument to ber_printf().
+encoding and a non-negative number if successful. As with sprintf(),
+each character in fmt refers to an argument to ber_printf().
The format string can contain the following format characters:
-'t' Tag. The next argument is an int specifying the tag to override
- the next element to be written to the ber. This works across
- calls. The int value must contain the tag class, constructed
- bit, and tag value. For example, a tag of "[3]" for a con-
- structed type is 0xA3. All implementations must support tags
- that fit in a single octet (i.e., where the tag value is less
- than 32) and they may support larger tags.
+'t' Tag. The next argument is a ber_tag_t specifying the tag to
+ override the next element to be written to the ber. This works
+ across calls. The integer tag value SHOULD contain the tag
+ class, constructed bit, and tag value. For example, a tag of
+ "[3]" for a constructed type is 0xA3U. All implementations MUST
+ support tags that fit in a single octet (i.e., where the tag
+ value is less than 32) and they MAY support larger tags.
-'b' Boolean. The next argument is an int, containing either 0 for
- FALSE or 0xff for TRUE. A boolean element is output. If this
- format character is not preceded by the 't' format modifier, the
- tag 0x01 is used for the element.
+'b' Boolean. The next argument is an ber_int_t, containing either 0
+ for FALSE or 0xff for TRUE. A boolean element is output. If
+ this format character is not preceded by the 't' format modif-
+ ier, the tag 0x01U is used for the element.
-'i' Integer. The next argument is an int, containing the integer in
- the host's byte order. An integer element is output. If this
- format character is not preceded by the 't' format modifier, the
- tag 0x02 is used for the element.
+'e' Enumerated. The next argument is a ber_int_t, containing the
+ enumerated value in the host's byte order. An enumerated ele-
+ ment is output. If this format character is not preceded by the
+ 't' format modifier, the tag 0x0AU is used for the element.
-'X' Bitstring. The next two arguments are a char * pointer to the
- start of the bitstring, followed by an int containing the number
- of bits in the bitstring. A bitstring element is output, in
- primitive form. If this format character is not preceded by the
- 't' format modifier, the tag 0x03 is used for the element.
+'i' Integer. The next argument is a ber_int_t, containing the
-
-Expires: 23 August 1999 [Page 56]
+Expires: May 2001 [Page 61]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+ integer in the host's byte order. An integer element is output.
+ If this format character is not preceded by the 't' format
+ modifier, the tag 0x02U is used for the element.
-'n' Null. No argument is required. An ASN.1 NULL element is out-
- put. If this format character is not preceded by the 't' format
- modifier, the tag 0x05 is used for the element.
+'B' Bitstring. The next two arguments are a char * pointer to the
+ start of the bitstring, followed by a ber_len_t containing the
+ number of bits in the bitstring. A bitstring element is output,
+ in primitive form. If this format character is not preceded by
+ the 't' format modifier, the tag 0x03U is used for the element.
+
+'X' Reserved and not to be used. In older revisions of this specif-
+ ication,
+
+'n' Null. No argument is needed. An ASN.1 NULL element is output.
+ If this format character is not preceded by the 't' format
+ modifier, the tag 0x05U is used for the element.
'o' Octet string. The next two arguments are a char *, followed by
- an int with the length of the string. The string may contain
- null bytes and need not be zero-terminated. An octet string
- element is output, in primitive form. If this format character
- is not preceded by the 't' format modifier, the tag 0x04 is used
- for the element.
+ a ber_len_t with the length of the string. The string MAY con-
+ tain null bytes and are do not have to be zero-terminated. An
+ octet string element is output, in primitive form. If this for-
+ mat character is not preceded by the 't' format modifier, the
+ tag 0x04U is used for the element.
's' Octet string. The next argument is a char * pointing to a
zero-terminated string. An octet string element in primitive
form is output, which does not include the trailing '\0' (null)
byte. If this format character is not preceded by the 't' format
- modifier, the tag 0x04 is used for the element.
+ modifier, the tag 0x04U is used for the element.
'v' Several octet strings. The next argument is a char **, an array
of char * pointers to zero-terminated strings. The last element
- in the array must be a NULL pointer. The octet strings do not
+ in the array MUST be a NULL pointer. The octet strings do not
include the trailing '\0' (null) byte. Note that a construct
- like '{v}' is required to get an actual SEQUENCE OF octet
- strings. The 't' format modifier cannot be used with this for-
- mat character.
-
-'V' Several octet strings. A NULL-terminated array of berval *'s is
- supplied. Note that a construct like '{V}' is required to get an
- actual SEQUENCE OF octet strings. The 't' format modifier cannot
- be used with this format character.
+ like '{v}' is used to get an actual SEQUENCE OF octet strings.
+ The 't' format modifier cannot be used with this format charac-
+ ter.
-'{' Begin sequence. No argument is required. If this format char-
- acter is not preceded by the 't' format modifier, the tag 0x30
- is used.
-
-'}' End sequence. No argument is required. The 't' format modifier
+'V' Several octet strings. A NULL-terminated array of struct berval
+ *'s is supplied. Note that a construct like '{V}' is used to
+ get an actual SEQUENCE OF octet strings. The 't' format modifier
cannot be used with this format character.
-'[' Begin set. No argument is required. If this format character
- is not preceded by the 't' format modifier, the tag 0x31 is
+'{' Begin sequence. No argument is needed. If this format charac-
+ ter is not preceded by the 't' format modifier, the tag 0x30U is
used.
-']' End set. No argument is required. The 't' format modifier can-
- not be used with this format character.
-
-Each use of a '{' format character must be matched by a '}' character,
-either later in the format string, or in the format string of a subse-
-quent call to ber_printf() for that BerElement. The same applies to the
-'[' and ']' format characters.
+'}' End sequence. No argument is needed. The 't' format modifier
-Expires: 23 August 1999 [Page 57]
+Expires: May 2001 [Page 62]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ cannot be used with this format character.
+
+'[' Begin set. No argument is needed. If this format character is
+ not preceded by the 't' format modifier, the tag 0x31U is used.
+
+']' End set. No argument is needed. The 't' format modifier cannot
+ be used with this format character.
+Each use of a '{' format character SHOULD be matched by a '}' character,
+either later in the format string, or in the format string of a subse-
+quent call to ber_printf() for that BerElement. The same applies to the
+'[' and ']' format characters.
-Sequences and sets nest, and implementations of this API must maintain
+Sequences and sets nest, and implementations of this API MUST maintain
internal state to be able to properly calculate the lengths.
- int ber_flatten( const BerElement *ber, struct berval **bvPtr );
+ int ber_flatten( BerElement *ber, struct berval **bvPtr );
The ber_flatten routine allocates a struct berval whose contents are a
BER encoding taken from the ber argument. The bvPtr pointer points to
-the returned berval, which must be freed using ber_bvfree(). This rou-
-tine returns 0 on success and -1 on error.
+the returned berval structure, which SHOULD be freed using ber_bvfree().
+This routine returns 0 on success and -1 on error.
The ber_flatten API call is not present in U-M LDAP 3.3.
returned by ber_flatten() if this situation is exists).
-16.3. Encoding Example
+17.4. Encoding Example
The following is an example of encoding the following ASN.1 data type:
}
- int encode_example1(const char *s,int val1,int val2,struct berval **bvPtr)
+ int encode_example1(const char *s, ber_int_t val1, ber_int_t val2,
+ struct berval **bvPtr)
{
BerElement *ber;
int rc = -1;
+ *bvPtr = NULL; /* in case of error */
+
+
+
+Expires: May 2001 [Page 63]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
ber = ber_alloc_t(LBER_USE_DER);
if (ber == NULL) return -1;
}
if (val2 != 0) {
- if (ber_printf(ber,"ti",0x80,val2) == -1) {
+ if (ber_printf(ber,"ti",(ber_tag_t)0x80,val2) == -1) {
goto done;
}
}
if (ber_printf(ber,"}") == -1) {
-
-
-
-Expires: 23 August 1999 [Page 58]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
goto done;
}
}
-16.4. Decoding
+17.5. Decoding
+
+The following two macros are available to applications: LBER_ERROR and
+LBER_DEFAULT. Both of these macros MUST be #define'd as ber_tag_t
+integral values that are treated as invalid tags by the API implementa-
+tion. It is RECOMMENDED that the values of LBER_ERROR and LBER_DEFAULT
+be the same and that they be defined as values where all octets have the
+value 0xFF. ISO C guarantees that these definitions will work:
-The following two symbols are available to applications.
+ #define LBER_ERROR ((ber_tag_t)-1)
+ #define LBER_DEFAULT ((ber_tag_t)-1)
- #define LBER_ERROR 0xffffffffUL
- #define LBER_DEFAULT 0xffffffffUL
+The intent is that LBER_ERROR and LBER_DEFAULT are both defined as the
+integer value that has all octets set to 0xFF, as such a value is not a
+valid BER tag.
BerElement *ber_init( const struct berval *bv );
ment containing a copy of the data in the bv argument. ber_init returns
the NULL pointer on error.
- unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );
+
+
+
+Expires: May 2001 [Page 64]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ber_tag_t ber_scanf( BerElement *ber, const char *fmt, ... );
The ber_scanf() routine is used to decode a BER element in much the same
way that sscanf() works. One important difference, though, is that some
state information is kept with the ber argument so that multiple calls
can be made to ber_scanf() to sequentially read from the BER element.
-The ber argument must be a pointer to a BerElement returned by
+The ber argument SHOULD be a pointer to a BerElement returned by
ber_init(). ber_scanf interprets the bytes according to the format
string fmt, and stores the results in its additional arguments.
ber_scanf() returns LBER_ERROR on error, and a different value on suc-
-cess.
+cess. If an error occurred, the values of all the result parameters are
+undefined.
The format string contains conversion specifications which are used to
direct the interpretation of the BER element. The format string can
contain the following characters:
-'a' Octet string. A char ** argument should be supplied. Memory is
+'a' Octet string. A char ** argument MUST be supplied. Memory is
allocated, filled with the contents of the octet string, zero-
terminated, and the pointer to the string is stored in the argu-
- ment. The returned value must be freed using ldap_memfree. The
- tag of the element must indicate the primitive form (constructed
- strings are not supported) but is otherwise ignored and dis-
- carded during the decoding. This format cannot be used with
+ ment. The returned value SHOULD be freed using ldap_memfree.
+ The tag of the element MUST indicate the primitive form (con-
+ structed strings are not supported) but is otherwise ignored and
+ discarded during the decoding. This format cannot be used with
octet strings which could contain null bytes.
+'O' Octet string. A struct berval ** argument MUST be supplied,
+ which upon return points to an allocated struct berval contain-
+ ing the octet string and its length. ber_bvfree() SHOULD be
+ called to free the allocated memory. The tag of the element
+ MUST indicate the primitive form (constructed strings are not
+ supported) but is otherwise ignored during the decoding.
+
+'b' Boolean. A pointer to a ber_int_t MUST be supplied. The
+ ber_int_t value stored will be 0 for FALSE or nonzero for TRUE.
+ The tag of the element MUST indicate the primitive form but is
+ otherwise ignored during the decoding.
+
+'e' Enumerated. A pointer to a ber_int_t MUST be supplied. The
+ enumerated value stored will be in host byte order. The tag of
+ the element MUST indicate the primitive form but is otherwise
+ ignored during the decoding. ber_scanf() will return an error
+ if the value of the enumerated value cannot be stored in a
+ ber_int_t.
+
+'i' Integer. A pointer to a ber_int_t MUST be supplied. The
+ ber_int_t value stored will be in host byte order. The tag of
+ the element MUST indicate the primitive form but is otherwise
-Expires: 23 August 1999 [Page 59]
+
+Expires: May 2001 [Page 65]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
-'O' Octet string. A struct berval ** argument should be supplied,
- which upon return points to an allocated struct berval contain-
- ing the octet string and its length. ber_bvfree() must be
- called to free the allocated memory. The tag of the element
- must indicate the primitive form (constructed strings are not
- supported) but is otherwise ignored during the decoding.
+ ignored during the decoding. ber_scanf() will return an error
+ if the integer cannot be stored in a ber_int_t.
-'b' Boolean. A pointer to an int should be supplied. The int value
- stored will be 0 for FALSE or nonzero for TRUE. The tag of the
- element must indicate the primitive form but is otherwise
- ignored during the decoding.
-
-'i' Integer. A pointer to an int should be supplied. The int value
- stored will be in host byte order. The tag of the element must
- indicate the primitive form but is otherwise ignored during the
- decoding. ber_scanf() will return an error if the integer can-
- not be stored in an int.
-
-'B' Bitstring. A char ** argument should be supplied which will
- point to the allocated bits, followed by an unsigned long *
- argument, which will point to the length (in bits) of the bit-
- string returned. ldap_memfree must be called to free the bit-
- string. The tag of the element must indicate the primitive form
- (constructed bitstrings are not supported) but is otherwise
- ignored during the decoding.
-
-'n' Null. No argument is required. The element is verified to have
- a zero-length value and is skipped. The tag is ignored.
-
-'v' Several octet strings. A char *** argument should be supplied,
+'B' Bitstring. A char ** argument MUST be supplied which will point
+ to the allocated bits, followed by a ber_len_t * argument, which
+ will point to the length (in bits) of the bitstring returned.
+ ldap_memfree SHOULD be called to free the bitstring. The tag of
+ the element MUST indicate the primitive form (constructed bit-
+ strings are not supported) but is otherwise ignored during the
+ decoding.
+
+'n' Null. No argument is needed. The element is verified to have a
+ zero-length value and is skipped. The tag is ignored.
+
+'t' Tag. A pointer to a ber_tag_t MUST be supplied. The ber_tag_t
+ value stored will be the tag of the next element in the BerEle-
+ ment ber, represented so it can be written using the 't' format
+ of ber_printf(). The decoding position within the ber argument
+ is unchanged by this; that is, the fact that the tag has been
+ retrieved does not affect future use of ber.
+
+'v' Several octet strings. A char *** argument MUST be supplied,
which upon return points to an allocated NULL-terminated array
of char *'s containing the octet strings. NULL is stored if the
- sequence is empty. ldap_memfree must be called to free each
+ sequence is empty. ldap_memfree SHOULD be called to free each
element of the array and the array itself. The tag of the
sequence and of the octet strings are ignored.
'V' Several octet strings (which could contain null bytes). A
- struct berval *** should be supplied, which upon return points
- to a allocated NULL-terminated array of struct berval *'s con-
- taining the octet strings and their lengths. NULL is stored if
- the sequence is empty. ber_bvecfree() can be called to free the
+ struct berval *** MUST be supplied, which upon return points to
+ a allocated NULL-terminated array of struct berval *'s contain-
+ ing the octet strings and their lengths. NULL is stored if the
+ sequence is empty. ber_bvecfree() can be called to free the
allocated memory. The tag of the sequence and of the octet
strings are ignored.
'x' Skip element. The next element is skipped. No argument is
- required.
-
-'{' Begin sequence. No argument is required. The initial sequence
+ needed.
+'{' Begin sequence. No argument is needed. The initial sequence
+ tag and length are skipped.
+'}' End sequence. No argument is needed.
-Expires: 23 August 1999 [Page 60]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+'[' Begin set. No argument is needed. The initial set tag and
+ length are skipped.
+']' End set. No argument is needed.
- tag and length are skipped.
-'}' End sequence. No argument is required.
-'[' Begin set. No argument is required. The initial set tag and
- length are skipped.
+Expires: May 2001 [Page 66]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
-']' End set. No argument is required.
- unsigned long ber_peek_tag( BerElement *ber, unsigned long *lenPtr );
+ ber_tag_t ber_peek_tag( BerElement *ber,
+ ber_len_t *lenPtr );
ber_peek_tag() returns the tag of the next element to be parsed in the
BerElement argument. The length of this element is stored in the
*lenPtr argument. LBER_DEFAULT is returned if there is no further data
-to be read. The ber argument is not modified.
+to be read. The decoding position within the ber argument is unchanged
+by this call; that is, the fact that ber_peek_tag() has been called does
+not affect future use of ber.
- unsigned long ber_skip_tag( BerElement *ber, unsigned long *lenPtr );
+ ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *lenPtr );
ber_skip_tag() is similar to ber_peek_tag(), except that the state
pointer in the BerElement argument is advanced past the first tag and
length, and is pointed to the value part of the next element. This rou-
-tine should only be used with constructed types and situations when a
+tine SHOULD only be used with constructed types and situations when a
BER encoding is used as the value of an OCTET STRING. The length of the
value is stored in *lenPtr.
- unsigned long ber_first_element( BerElement *ber,
- unsigned long *lenPtr, char **opaquePtr );
+ ber_tag_t ber_first_element( BerElement *ber,
+ ber_len_t *lenPtr, char **opaquePtr );
- unsigned long ber_next_element( BerElement *ber,
- unsigned long *lenPtr, char *opaque );
+ ber_tag_t ber_next_element( BerElement *ber,
+ ber_len_t *lenPtr, char *opaque );
ber_first_element() and ber_next_element() are used to traverse a SET,
SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
in the constructed type. LBER_DEFAULT is returned if there are no
further values.
-The len and opaque values should not be used by applications other than
+The len and opaque values SHOULD NOT be used by applications other than
as arguments to ber_next_element(), as shown in the example below.
-16.5. Decoding Example
+17.6. Decoding Example
The following is an example of decoding an ASN.1 data type:
-
-
-
-Expires: 23 August 1999 [Page 61]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
Example2Request ::= SEQUENCE {
dn OCTET STRING, -- must be printable
scope ENUMERATED { b (0), s (1), w (2) },
ali ENUMERATED { n (0), s (1), f (2), a (3) },
size INTEGER,
time INTEGER,
+
+
+
+Expires: May 2001 [Page 67]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
tonly BOOLEAN,
attrs SEQUENCE OF OCTET STRING, -- must be printable
[0] SEQUENCE OF SEQUENCE {
value OCTET STRING
} OPTIONAL }
- #define TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */
+ #define TAG_CONTROL_LIST 0xA0U /* context specific cons 0 */
int decode_example2(struct berval *bv)
{
BerElement *ber;
- unsigned long len, res;
- int scope, ali, size, time, tonly;
+ ber_len_t len;
+ ber_tag_t res;
+ ber_int_t scope, ali, size, time, tonly;
char *dn = NULL, **attrs = NULL;
int i,rc = 0;
/* *** use attrs[i] */
ldap_memfree(attrs[i]);
}
- ldap_memfree(attrs);
+ ldap_memfree((char *)attrs);
+
+ if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
+ char *opaque;
+ ber_tag_t tag;
+ for (tag = ber_first_element(ber,&len,&opaque);
-Expires: 23 August 1999 [Page 62]
+Expires: May 2001 [Page 68]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
- if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
- char *opaque;
- unsigned long tag;
-
- for (tag = ber_first_element(ber,&len,&opaque);
tag != LBER_DEFAULT;
tag = ber_next_element (ber,&len,opaque)) {
- unsigned long ttag, tlen;
+ ber_len_t tlen;
+ ber_tag_t ttag;
char *type;
- int crit;
+ ber_int_t crit;
struct berval *value;
if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
ldap_memfree(type);
ttag = ber_peek_tag(ber,&tlen);
- if (ttag == 0x01) { /* boolean */
+ if (ttag == 0x01U) { /* boolean */
if (ber_scanf(ber,"b",
&crit) == LBER_ERROR) {
fputs("ERROR cannot parse crit\n",
rc = -1;
break;
}
- } else if (ttag == 0x04) { /* octet string */
+ } else if (ttag == 0x04U) { /* octet string */
crit = 0;
} else {
fputs("ERROR extra field in controls\n",
}
}
- ber_scanf(ber,"}");
+ if ( rc == 0 ) { /* no errors so far */
+ if (ber_scanf(ber,"}") == LBER_ERROR) {
+ rc = -1;
+ }
+ }
-Expires: 23 August 1999 [Page 63]
+Expires: May 2001 [Page 69]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
+C LDAP API C LDAP Application Program Interface 17 November 2000
ber_free(ber,1);
-17. Security Considerations
+18. Security Considerations
LDAPv2 supports security through protocol-level authentication using
-clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen-
+clear-text passwords. LDAPv3 adds support for SASL [12] (Simple Authen-
tication Security Layer) methods. LDAPv3 also supports operation over a
secure transport layer using Transport Layer Security TLS [9]. Readers
are referred to the protocol documents for discussion of related secu-
rity considerations.
-Implementations of this API should be cautious when handling authentica-
+Implementations of this API SHOULD be cautious when handling authentica-
tion credentials. In particular, keeping long-lived copies of creden-
tials without the application's knowledge is discouraged.
-18. Acknowledgements
+19. Acknowledgements
Many members of the IETF ASID and LDAPEXT working groups as well as
members of the Internet at large have provided useful comments and
ported by the National Science Foundation under Grant No. NCR-9416667.
-19. Copyright
+20. Copyright
-Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
+Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
This document and translations of it may be copied and furnished to oth-
ers, and derivative works that comment on or otherwise explain it or
be modified in any way, such as by removing the copyright notice or
references to the Internet Society or other Internet organizations,
except as needed for the purpose of developing Internet standards in
-which case the procedures for copyrights defined in the Internet
+which case the procedures for copyrights defined in the Internet Stan-
+dards process must be followed, or as required to translate it into
-Expires: 23 August 1999 [Page 64]
+Expires: May 2001 [Page 70]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
-Standards process must be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not be
NESS FOR A PARTICULAR PURPOSE.
-20. Bibliography
+21. Bibliography
-[1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
- X.520.
+[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", RFC 2119, March 1997.
+
+[2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
+ (v3)", RFC 2251, December 1997.
-[2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
+[3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
"Lightweight Directory Access Protocol (v3): Attribute Syntax
Definitions", RFC 2252, December 1997.
-[3] T. Howes, "The String Representation of LDAP Search Filters," RFC
- 2254, December 1997.
+[4] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
+ X.520.
-[4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
+[5] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
(v3): A UTF-8 String Representation of Distinguished Names", RFC
2253, December 1997.
-[5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
- ing," RFC 1781, March 1995.
+[6] F. Yergeau, "UTF-8, a transformation format of Unicode and ISO
+ 10646", RFC 2044, October 1996.
-[6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
- (v3)", RFC 2251, December 1997.
+[7] K. Simonsen, "Character Mnemonics and Character Sets," RFC 1345,
+ June 1992.
-[7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control
- Extension for Server Side Sorting of Search Results", INTERNET-
- DRAFT <draft-ietf-ldapext-sorting-01.txt>, 7 August 1998.
+[8] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997.
-[8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC
- 2222, October 1997.
+[9] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto-
+ col (v3): Extension for Transport Layer Security", INTERNET-DRAFT
+ (work in progress) <draft-ietf-ldapext-ldapv3-tls-05.txt>, June
+ 1999.
-[9] "Lightweight Directory Access Protocol (v3): Extension for Tran-
- sport Layer Security", INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-
- tls-04.txt>, November 1998.
+[10] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture," RFC
+ 1884, December 1995.
-[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
-Expires: 23 August 1999 [Page 65]
+Expires: May 2001 [Page 71]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
- 2044, October 1996.
+[11] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension
+ for Server Side Sorting of Search Results", INTERNET-DRAFT (work in
+ progress) <draft-ietf-ldapext-sorting-02.txt>, 5 April 1999.
-[11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995.
+[12] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC
+ 2222, October 1997.
-[12] "Character Mnemonics and Character Sets," RFC 1345, June 1992.
+[13] T. Howes, "The String Representation of LDAP Search Filters," RFC
+ 2254, December 1997.
-[13] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997.
+[14] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
+ ing," RFC 1781, March 1995.
-21. Authors' Addresses
+22. Authors' Addresses
Mark Smith (document editor)
Netscape Communications Corp.
- 501 E. Middlefield Rd., Mailstop MV068
- Mountain View, CA 94043
+ 901 San Antonio Rd.
+ Palo Alto, CA 94303-4900
+ Mail Stop SCA17 - 201
USA
+1 650 937-3477
mcs@netscape.com
Tim Howes
- Netscape Communications Corp.
- 501 E. Middlefield Rd., Mailstop MV068
- Mountain View, CA 94043
+ Loudcloud, Inc.
+ 599 N. Mathilda Avenue
+ Sunnyvale, CA 94085
USA
- +1 650 937-3419
- howes@netscape.com
+ +1 408 744-7300
+ howes@loudcloud.com
Andy Herron
Microsoft Corp.
andyhe@microsoft.com
Mark Wahl
- Innosoft International, Inc.
+ Sun Microsystems, Inc.
8911 Capital of Texas Hwy, Suite 4140
Austin, TX 78759
USA
+1 626 919 3600
- Mark.Wahl@innosoft.com
-
- Anoop Anantha
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
+ Mark.Wahl@sun.com
-Expires: 23 August 1999 [Page 66]
+Expires: May 2001 [Page 72]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+ Anoop Anantha
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+1 425 882-8080
anoopa@microsoft.com
-22. Appendix A - Sample C LDAP API Code
+23. Appendix A - Sample C LDAP API Code
#include <stdio.h>
#include <ldap.h>
}
/* step through each entry returned */
- for ( e = ldap_first_entry( ld, res ); e != NULL;
- e = ldap_next_entry( ld, e ) ) {
- /* print its name */
- dn = ldap_get_dn( ld, e );
- printf( "dn: %s\n", dn );
-Expires: 23 August 1999 [Page 67]
+Expires: May 2001 [Page 73]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+ for ( e = ldap_first_entry( ld, res ); e != NULL;
+ e = ldap_next_entry( ld, e ) ) {
+ /* print its name */
+ dn = ldap_get_dn( ld, e );
+ printf( "dn: %s\n", dn );
ldap_memfree( dn );
/* print each attribute */
}
-23. Appendix B - Namespace Consumed By This Specification
+24. Appendix B - Namespace Consumed By This Specification
The following 2 prefixes are used in this specification to name func-
tions:
tures, unions, and typedefs:
ldap
LDAP
- PLDAP
+ mod_vals_u
ber
Ber
- timeval
-
-The following 3 prefixes are used in this specification to name #defined
-macros:
- LDAP
-Expires: 23 August 1999 [Page 68]
+Expires: May 2001 [Page 74]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
+ timeval
+
+The following 3 prefixes are used in this specification to name #defined
+macros:
+ LDAP
LBER_
mod_
-24. Appendix C - Summary of Requirements for API Extensions
+25. Appendix C - Summary of Requirements for API Extensions
As the LDAP protocol is extended, this C LDAP API will need to be
extended as well. For example, an LDAPv3 control extension has already
been defined for server-side sorting of search results [7]. This appen-
dix summarizes the requirements for extending this API.
-24.1. Compatibility
+25.1. Compatibility
-Extensions to this document should not, by default, alter the behavior
+Extensions to this document SHOULD NOT, by default, alter the behavior
of any of the APIs specified in this document. If an extension option-
ally changes the behavior of any existing C LDAP API function calls, the
-behavior change must be well documented.
+behavior change MUST be well documented. If an extension that operates
+on an LDAP session affects a chain of messages that was previously
+obtained by a call to ldap_result() or by calling a synchronous search
+routine, this MUST be well documented.
-24.2. Style
+25.2. Style
-Extensions to this API should follow the general style and naming con-
-ventions used in this document. For example, function names should
+Extensions to this API SHOULD follow the general style and naming con-
+ventions used in this document. For example, function names SHOULD
start with "ldap_" or "ber_" and consist entirely of lowercase letters,
-digits, and underscore ('_') characters. More information can be found
-in the preceding appendix called "Namespace Consumed By This Specifica-
-tion."
-
-24.3. Dependence on Externally Defined Types
-
-Extensions to this API should minimize dependencies on types and macros
-that are defined in system header files and generally use only intrinsic
+digits, and underscore ('_') characters. It is RECOMMENDED that private
+and experimental extensions use only the following prefixes for macros,
+types, and function names:
+ LDAP_X_
+ LBER_X_
+ ldap_x_
+ ber_x_
+and that these prefixes not be used by standard extensions.
+
+25.3. Dependence on Externally Defined Types
+
+Extensions to this API SHOULD minimize dependencies on types and macros
+that are defined in system headers and generally use only intrinsic
types that are part of the C language, types defined in this specifica-
tion, or types defined in the extension document itself.
-24.4. Compile Time Information
-
-Extensions to this API should conform to the requirements contained in
-the "Retrieving Information at Compile Time" section of this document.
-That is, extensions should define a macro of the form:
- #define LDAP_API_FEATURE_x level
-so that applications can detect the presence or absense of the extension
-at compile time and also test the version or level of the extension pro-
-vided by an API implementation.
+Expires: May 2001 [Page 75]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+25.4. Compile Time Information
+Extensions to this API SHOULD conform to the requirements contained in
+the "Retrieving Information at Compile Time" section of this document.
+That is, extensions SHOULD define a macro of the form:
-Expires: 23 August 1999 [Page 69]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ #define LDAP_API_FEATURE_x level
+so that applications can detect the presence or absence of the extension
+at compile time and also test the version or level of the extension pro-
+vided by an API implementation.
-24.5. Runtime Information
+25.5. Runtime Information
-Extensions to this API should conform to the requirements contained in
+Extensions to this API SHOULD conform to the requirements contained in
the "Retrieving Information During Execution" section of this document.
-That is, each extension should be given a character string name and that
-name should appear in the ldapai_extensions array field of the LDAPAPI-
+That is, each extension SHOULD be given a character string name and that
+name SHOULD appear in the ldapai_extensions array field of the LDAPAPI-
Info structure following a successful call to ldap_get_option() with an
option parameter value of LDAP_OPT_API_INFO. In addition, information
-about the extension should be available via a call to ldap_get_option()
+about the extension SHOULD be available via a call to ldap_get_option()
with an option parameter value of LDAP_OPT_API_FEATURE_INFO.
-24.6. Values Used for Session Handle Options
+25.6. Values Used for Session Handle Options
Extensions to this API that add new session options (for use with the
-ldap_get_option() and ldap_set_option() functions) should meet the
+ldap_get_option() and ldap_set_option() functions) SHOULD meet the
requirements contained in the last paragraph of the "LDAP Session Handle
Options" section of this document. Specifically, standards track docu-
ments MUST use values for option macros that are between 0x1000 and
for the option macros that are between 0x4000 and 0x7FFF inclusive.
-25. Appendix D - Known Incompatibilities with RFC 1823
+26. Appendix D - Known Incompatibilities with RFC 1823
This appendix lists known incompatibilities between this API specifica-
tion and the one contained in RFC 1823, beyond the additional API func-
tions added in support of LDAPv3.
-25.1. Opaque LDAP Structure
+26.1. Opaque LDAP Structure
In RFC 1823, some fields in the LDAP structure were exposed to applica-
tion programmers. To provide a cleaner interface and to make it easier
for implementations to evolve over time without sacrificing binary com-
patibility with older applications, the LDAP structure is now entirely
opaque. The new ldap_set_option() and ldap_get_option() calls can be
+
+
+
+Expires: May 2001 [Page 76]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
used to manipulate per-session and global options.
-25.2. Additional Error Codes
+26.2. Additional Result Codes
-The following new error code macros were introduced to support LDAPv3:
+The following new result code macros were introduced to support LDAPv3:
LDAP_REFERRAL
LDAP_ADMINLIMIT_EXCEEDED
LDAP_UNAVAILABLE_CRITICAL_EXTENSION
LDAP_CONFIDENTIALITY_REQUIRED
LDAP_SASL_BIND_IN_PROGRESS
LDAP_AFFECTS_MULTIPLE_DSAS
-
-
-
-Expires: 23 August 1999 [Page 70]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
LDAP_CONNECT_ERROR
LDAP_NOT_SUPPORTED
LDAP_CONTROL_NOT_FOUND
LDAP_REFERRAL_LIMIT_EXCEEDED
-25.3. Freeing of String Data with ldap_memfree()
+26.3. Freeing of String Data with ldap_memfree()
All strings received from the API (e.g., those returned by the
-ldap_get_dn() or ldap_dn2ufn() functions) should be freed by calling
+ldap_get_dn() or ldap_dn2ufn() functions) SHOULD be freed by calling
ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree()
function.
-25.4. Changes to ldap_result()
+26.4. Changes to ldap_result()
The meaning of the all parameter to ldap_result has changed slightly.
Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There
(0x6D).
-25.5. Changes to ldap_first_attribute() and ldap_next_attribute
+26.5. Changes to ldap_first_attribute() and ldap_next_attribute
-Each non-NULL return value should be freed by calling ldap_memfree()
+Each non-NULL return value SHOULD be freed by calling ldap_memfree()
after use. In RFC 1823, these two functions returned a pointer to a
per-session buffer, which was not very thread-friendly.
After the last call to ldap_first_attribute() or ldap_next_attribute(),
-the value set in the ptr parameter should be freed by calling ber_free(
-ptr, 0 ). RFC 1823 did not mention that the ptr value should be freed.
+the value set in the ptr parameter SHOULD be freed by calling ber_free(
+
+
+
+Expires: May 2001 [Page 77]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ptr, 0 ). RFC 1823 did not mention that the ptr value SHOULD be freed.
The type of the ptr parameter was changed from void * to BerElement *.
-25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions
+26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions
In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a
parameter called deleteoldrdn. This does not match the great majority
of implementations, so in this specification the deleteoldrdn parameter
was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional
functions that support deleteoldrdn and are widely implemented as well
+were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
+26.7. Changes to the berval structure
-Expires: 23 August 1999 [Page 71]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
-
-
-were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
+In RFC 1823, the bv_len element of the berval structure was defined as
+an `unsigned long'. In this specification, the type is implementation-
+specific, although it MUST be an unsigned integral type that is at least
+32 bits in size. See the appendix "Data Types and Legacy Implementa-
+tions" for additional considerations.
-25.7. API Specification Clarified
+26.8. API Specification Clarified
RFC 1823 left many things unspecified, including behavior of various
memory disposal functions when a NULL pointer is presented, requirements
-for header files, values of many macros, and so on. This specification
-is more complete and generally tighter than the one in RFC 1823.
+for headers, values of many macros, and so on. This specification is
+more complete and generally tighter than the one in RFC 1823.
-25.8. Deprecated Functions
+26.9. Deprecated Functions
A number of functions that are in RFC 1823 are labeled as "deprecated"
in this specification. In most cases, a replacement that provides
ldap_kerberos_bind() and ldap_kerberos_bind_s()
No equivalent functions are provided.
+
+
+
+Expires: May 2001 [Page 78]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
ldap_modrdn() and ldap_modrdn2()
Use ldap_rename() instead.
Use ldap_init() instead.
ldap_perror()
- Use ldap_err2string() instead.
+ Use ldap_get_option( ld, LDAP_OPT_RESULT_CODE, &rc ) followed
+ by fprintf( stderr, "%s: %s", msg, ldap_err2string( rc ))
+ instead.
ldap_result2error()
Use ldap_parse_result() instead.
-26. Appendix E - Changes Made Since Last Document Revision
-
-The previous version of this document was draft-ietf-ldapext-ldap-c-
-api-01.txt, dated 7 August 1998. This appendix lists all of the changes
-made to that document to produce the one you are reading now.
-
-
-
-Expires: 23 August 1999 [Page 72]
+27. Appendix E - Data Types and Legacy Implementations
+
+The data types associated with the length of a ber value (ber_len_t),
+and the tag (ber_tag_t) have been defined in this specification as
+unsigned integral types of implementation-specific size. The data type
+used for encoding and decoding ber integer, enumerated, and boolean
+values has been defined in this specification as a signed integral type
+of implementation-specific size. This was done so that source and
+binary compatibility of the C LDAP API can be maintained across ILP32
+environments (where int, long, and pointers are all 32 bits in size) and
+LP64 environments (where ints remain 32 bits but longs and pointers grow
+to 64 bits).
+
+In older implementations of the C LDAP API, such as those based on RFC
+1823, implementors may have chosen to use an `unsigned long' for length
+and tag values. If a long data type was used for either of these items,
+a port of an application to a 64-bit operating system using the LP64
+data model would find the size of the types used by the C LDAP API to
+increase. Also, if the legacy implementation had chosen to implement
+the tag and types as an unsigned int, adoption of a specification that
+mandated use of unsigned longs would cause a source incompatibility in
+an LP64 application. By using implementation-specific data types, the C
+LDAP API implementation is free to choose the correct data type and the
+ability to maintain source compatibility.
+
+For example, suppose a legacy implementation chose to define the return
+value of ber_skip_tag() as an unsigned long but wishes to have the
+library return a 32-bit quantity in both ILP32 and LP64 data models.
+The following typedefs for ber_tag_t will provide a fixed sized data
+structure while preserving existing ILP32 source -- all without
+
+
+
+Expires: May 2001 [Page 79]
\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+C LDAP API C LDAP Application Program Interface 17 November 2000
-26.1. API Changes
+generating compiler warnings:
+ #include <limits.h> /* provides UINT_MAX in ISO C */
+ #if UINT_MAX >= 0xffffffffU
+ typedef unsigned int ber_tag_t;
+ #else
+ typedef unsigned long ber_tag_t;
+ #endif
- General: added the 'const' keyword to function prototypes where
- appropriate.
+Similar code can be used to define appropriate ber_len_t, ber_int_t,
+ber_slen_t and ber_uint_t types.
- Added two new sections that specify additional features and require-
- ments for API implementors:
- "Header File Requirements"
- "A Client Control That Governs Referral Processing"
- "Retrieving Information at Compile Time" section: added
- LDAP_VERSION_MIN, LDAP_VERSION_MAX, LDAP_VENDOR_NAME, and
- LDAP_VENDOR_VERSION macros. Corrected LDAP_API_VERSION example code
- to use >= instead of >. Added note about what value to use for
- LDAP_API_VERSION prior to publication of this draft as an RFC (2000 +
- draft revision number).
+28. Appendix F - Changes Made Since Last Document Revision
- "Retrieving Information During Execution" section: added
- LDAP_API_INFO_VERSION macro and clarified the text to explain the
- behavior when there is a mismatch between LDAPAPIInfo structure ver-
- sions. Added LDAP_OPT_API_FEATURE_INFO to allow applications to
- retrieve version information about API extended features.
-
- "LDAP Session Handle Options" section: Added macro definitions for
- LDAP_OPT_ON and LDAP_OPT_OFF and changed the "invalue" type for
- Boolean options from "int" to "void *". For consistency, we now
- require that applications dispose of "char *" and "LDAPControl *"
- values that are returned. Added note about which option value ranges
- are to be used for various purposes.
-
- "Closing the session" section: added new function ldap_unbind_ext()
- to allow controls to be used with unbind operations.
-
- "Searching" section: added requirement that *res be set to NULL by
- synchronous calls that fail to return any results.
-
- "Modifying the Name of an Entry" section: added function prototypes
- for ldap_modrdn2() and ldap_modrdn2_s() and corrected the ones for
- ldap_modrdn() and ldap_modrdn_s() to match the most widely imple-
- mented APIs.
-
- "Obtaining Results and Peeking Inside LDAP Messages" section: added
- requirement that "*res" be set to NULL when ldap_result() fails to
- return any results. Added requirement that ldap_msgfree() accept a
- NULL "res" parameter.
-
- "Stepping Through the Attributes of an Entry" section: added
- requirement that ldap_memfree() accept a NULL "mem" parameter.
+The previous version of this document was draft-ietf-ldapext-ldap-c-
+api-04.txt, dated 8 October 1999. This appendix lists all of the
+changes made to that document to produce this one.
+28.1. API Changes
+ "Header Requirements" section: added requirement that the simple pro-
+ gram provided must execute as well as compile without errors.
-Expires: 23 August 1999 [Page 73]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ "LDAP Session Handle Options" section: changed the name of the
+ LDAP_OPT_ERROR_NUMBER option to LDAP_OPT_RESULT_CODE. Allow
+ LDAP_OPT_ON to be defined as an implementation specific value (to
+ avoid problems on architectures where the value ((void *)1) is not
+ usable).
+ "Initializing an LDAP Session" section: allow use of the value zero
+ for the `portno' parameter to mean "use port 389."
- "Encoded ASN.1 Value Manipulation - Encoding" section: added note
- that implementations may support tags with a value larger than 32
- (but this is not required).
+ "Searching" section: added LDAP_DEFAULT_SIZELIMIT (-1) to allow
+ application programmers to use the sizelimit from the LDAP session
+ handle with ldap_search_ext() and ldap_search_ext_s().
- "Encoded ASN.1 Value Manipulation - Decoding" section: changed the
- LBER_ERROR and LBER_DEFAULT macros to end in "UL" instead of "L"
- since all the functions that return these two values return an
- "unsigned long" value.
+ "Modifying an entry" section: moved mod_vals union out of LDAPMod and
+ added mod_vals_u_t typedef so users of the API can declare variables
+ using the union type. "Handling Errors and Parsing Results" section:
+ added text to require that ldap_err2string() MUST NOT return NULL.
+ "A Client Control That Governs Referral Processing" section: modified
+ the text to specify that a ber_uint_t value should be used to hold
+ the flags.
-26.2. Editorial changes
- Removed section: "Appendix - Outstanding Issues."
- Added two new editorial sections:
- "Appendix - Summary of Requirements for API Extensions"
- "Appendix - Known Incompatibilities with RFC 1823".
- General: replaced all occurrences of "LDAP C API" with "C LDAP API"
- for consistency.
- "Status of Memo" section: added a statement that this document is in
- full conformance with all provisions of Section 10 of RFC2026. Also
- revised the text about the Internet Draft current and shadow direc-
- tories to match the latest I-D guidelines.
- Document authors: removed Chris Weider from the list of authors (at
- his own request) and added an explicit mention of him in the "Ack-
- nowledgements" section. Updated Mark Wahl's company affiliation in
- document preface. Added "(document editor)" after Mark Smith's name
- in the "Authors' Addresses" section.
+Expires: May 2001 [Page 80]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
- Copyright: updated the year to 1999.
- "Introduction" section: expanded the sentence that mentioned the sam-
- ple code appendix to mention all of the appendices.
+28.2. Editorial Changes and Clarifications
- "Overview of LDAP API Use" section: numbered the four simple steps
- for using the API. Added mention of the referrals client control.
- Clarified the text on character sets. Replaced mention of
- ldap_bind() with ldap_sasl_bind() because the former is deprecated.
- Added note that this API is designed for use in environments where
- the 'int' type is at least 32 bits in size.
+ "Overview of LDAP API Use and General Requirements" section: added
+ text to clarify our use of the term "asynchronous."
- "Common Data Structures" section: added definition of BerElement so
- it is defined before it is used. Added reference back to "Header
- File Requirements" for "struct timeval" related considerations.
+ "Retrieving Information During Execution" section: added text
+ describing the `ldapai_vendor_name' and `ldapai_vendor_version'
+ fields (text was accidently deleted during a previous round of
+ edits).
+ "LDAP Session Handle Options" section: improved the text that
+ describes the LDAP_OPT_TIMELIMIT, LDAP_OPT_SIZELIMIT, and
+ LDAP_OPT_RESULT_CODE options. Provided details and an example of the
+ correct LDAP_OPT_HOST_NAME string to return when the `portno' passed
+ to ldap_init() is not zero or 389.
+ "Result Codes" section: renamed section (was "LDAP Error Codes").
-Expires: 23 August 1999 [Page 74]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ "Authenticating to the directory" section: clarified that the `dn',
+ `cred', and `passwd' parameters can be NULL. Added text indicate
+ that the `servercredp' is set to NULL if an API error occurs.
+ "Performing LDAP Operations" section: replaced "All functions take a
+ session handle" with "Most functions...."
- "Initializing an LDAP Session" section: moved note about ldap_open()
- attempting to make a server connection closer to the ldap_open()
- function prototype. Added note that using literal IPv6 addresses in
- the "hostname" parameter is not yet supported.
+ "Search" section: removed the detailed discussion of the session han-
+ dle options (already covered in the "Retrieving Information During
+ Execution" section). Also removed the word "global" when discussing
+ the session default value for the `timeout' parameter. Also clari-
+ fied that a NULL `base' parameter means use a zero-length string for
+ the base DN.
- "LDAP Session Handle Options" section: replaced one instance of
- "Formerly" with "In RFC 1823." Added note about inheritance of
- options when automatic referral following is enabled. Added
- LDAP_OPT_API_INFO and LDAP_OPT_API_FEATURE_INFO for completeness (not
- previously included in this section). Replaced erroneous references
- to the "Using Controls" section with references to the "Working With
- Controls" section. In the text describing the LDAP_OPT_HOST_NAME
- option, added a reference to the "hostname" parameter of ldap_init()
- for the syntax of the option value. Clarified that ldap_set_option()
- makes a copy of the "invalue" data.
+ "Comparing a Value Against an Entry" section: corrected the "success-
+ ful" return codes for ldap_compare_ext_s() and ldap_compare_s() (was
+ LDAP_SUCCESS; changed to LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE).
- "Working With Controls" section: added a note to remind the reader
- that server controls that are marked critical should not be used with
- unbind and abandon operations since those two operations have no
- server response.
+ "Extended Operations" section: added text to indicate that the
+ `retoidp' and `retdatap' result parameters are set to NULL if an API
+ error occurs in ldap_extended_operation_s().
- "Closing the session" section: made it clear that all open connec-
- tions associated with a session handle are closed when any of the
- unbind API functions are called.
+ "Handling Errors and Parsing Results" section: added text to say that
+ the `matcheddnp' result parameter will be set to NULL if the server
+ does not return a matched DN string. Added text to indicate that
+ serverctrlsp can be NULL. Added text to indicate that *retoidpp,
+ *retdatap, *referralsp, and *serverctrlsp will be set to NULL if no
+ items of that type are returned. Removed specific reference to
+ LDAP_NO_SUCH_OBJECT result code when discussing the `matcheddnp'
+ result parameter and added clarifying note about "" vs. NULL.
- "Searching" section: added note that only a subset of the filter
- functionality is available when communicating with an LDAPv2 server.
- Clarified text to explain when a local timeout is used and when it is
- not.
- "Abandoning An Operation" section: removed some redundant text from
- the paragraph that explains the differences between ldap_abandon()
- and ldap_abandon_ext().
- "Obtaining Results and Peeking Inside LDAP Messages" section: clari-
- fied that ldap_result() only returns messages for one request at a
- time.
+Expires: May 2001 [Page 81]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
- "Handling Errors and Parsing Results" section: replace a few
- occurrences of LDAPResult with LDAPMessage (there is no type called
- LDAPResult). Changed the names of the "resultoidp" and "resultdatap"
- parameters to "retoidp" and "retdatap" to avoid confusion with LDAP
- result messages.
- "Stepping Through a List of Entries or References" section: added "or
- References" to the section name to better reflect its contents.
- Added missing description of "ref" parameter. Added mention of
- ldap_first_reference() and ldap_next_reference() in sentence about
+ "Parsing References" section: added text to indicate that *refer-
+ ralsp, and *serverctrlsp will be set to NULL if no items of that type
+ are returned.
+ "Obtaining Results and Peeking Inside LDAP Messages" section: added
+ text to say that LDAPMessage chains MAY be tied to a session handle.
+ "BER Data Structures and Types" section: removed note about
+ ber_uint_t not being used in this document (it is now). Changed text
+ to simplify the description of ber_slen_t. Removed misleading sen-
+ tence about the width of ber_uint_t.
-Expires: 23 August 1999 [Page 75]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ "Encoded ASN.1 Value Manipulation / Encoding" section: added note
+ that 'X' is reserved. Also fixed a few small bugs in the example
+ code.
+ "Encoded ASN.1 Value Manipulation / Decoding" section: clarified the
+ requirements for LBER_ERROR and LBER_DEFAULT (expressed using octets
+ instead of bits). Also fixed a few small bugs in the example code.
- function return values.
+ Added the following text to all descriptions of the `serverctrls' and
+ `clientctrls' parameters: ", or NULL if no <server/client> controls
+ are to be used."
- "Stepping Through the Attributes of an Entry" section: added forward
- reference for BerElement type.
+ Added the following text to the description of all `dn' and `rdn'
+ parameters: "If NULL, a zero length DN is sent to the server."
- "Parsing References" section: in the description of the "ref" parame-
- ter, changed the phrase "these routines" to the more accurate "this
- routine."
+ Replaced many occurrences of the phrase "error code" with "result
+ code" throughout the document.
- "Encoded ASN.1 Value Manipulation - General" section: changed text to
- make sense given that the definition of BerElement now appears first
- in the "Common Data Structures" section.
+ Added text to indicate that the value of the `msgidp' result parame-
+ ter is undefined if an error occurs in the following functions:
+ ldap_sasl_bind(), ldap_search_ext(), ldap_compare_ext(),
+ ldap_modify_ext(), ldap_add_ext(), ldap_delete_ext(),
+ ldap_extended_operation().
- "Encoded ASN.1 Value Manipulation - Encoding" section: Changed the
- style of function prototypes to better match the rest of the docu-
- ment. Corrected a typo in the ber_bvdup() description ("as the"
- replaced with "than the"). Changed "null" to "NULL" where appropri-
- ate to be consistent with use elsewhere in the document. Removed
- mention of sequences from the discussion of the LBER_USE_DER option.
- Fixed some truncated sentences (by adding some missing '\' characters
- to the nroff document source).
+ Added text to indicate that the `res' result parameter is set to NULL
+ if an API error occurs in the following functions: ldap_result(),
+ ldap_search_s(), ldap_search_st().
- "Encoded ASN.1 Value Manipulation - Encoding Example" section: sim-
- plified the error handling in the example code through the use of a
- 'goto' statement.
+ Added text to indicate that all result parameters have undefined
+ values if an API error is returned by the following functions:
+ ldap_parse_result(), ldap_parse_sasl_bind_result(),
+ ldap_parse_extended_result(), ldap_parse_reference(), ber_scanf().
- "Encoded ASN.1 Value Manipulation - Decoding" section: Changed the
- style of function prototypes to better match the rest of the docu-
- ment. Changed "null" to "NULL" and "null-terminated" to "zero-
- terminated" where appropriate to be consistent with use elsewhere in
- the document. Fixed a typo (the text now says "an allocated" instead
- of "a allocated."). Clarified the description of the 'n' format
- character for ber_scanf().
+ Added angle brackets around ficticious impl_XXX_t types to make it
+ more obvious that these are not real "C" types, e.g., typedef
+ <impl_len_t> ber_len_t'.
- "Encoded ASN.1 Value Manipulation - Decoding Example" section:
- changed code to not define a macro that begins with "LDAP" since that
- prefix is reserved for the API. Removed an extra 'i' from the format
- string used in the first call to ber_scanf(). Changed error report-
- ing code to send messages to stderr instead of stdout. Changed
- declaration of "res" local variable from "int" to "unsigned long" and
- corrected one test of the ber_scanf() return value to test against
- LBER_ERROR instead of -1. Fixed improperly rendered strings (by
- adding '\' characters to the nroff source for this document so that
- '\t' and '\n' are correctly rendered).
- "Acknowledgements" section: added the mention of Chris Weider.
- Rephrased the text that gives credit to the National Science Founda-
- tion (it now says "The original material upon which this
+Expires: May 2001 [Page 82]
+\f
+C LDAP API C LDAP Application Program Interface 17 November 2000
-Expires: 23 August 1999 [Page 76]
-\f
-C LDAP API C LDAP Application Program Interface 23 February 1999
+ Appendix B: Added mod_vals_u and removed PLDAP from the struct,
+ unions, and typedefs prefix list.
+ Appendix C: Added note in "Compatibility" section about extensions
+ possible affecting chains of messages and the fact that that must be
+ well documented. Appendix D: Improved text for ldap_perror() (what
+ to use instead).
- specification is based was supported by ..." instead of "This origi-
- nal material upon which this revision is based was based upon work
- supported by ..."
+ "Authors" section: updated contact information for Mark Smith, Tim
+ Howes, and Mark Wahl.
- In the "Bibliography" section: Added a reference to RFC 1345 and
- ANSI/ISO C. Updated the LDAPv3 TLS and Sorting references to point
- to the latest revisions of those documents.
+ Fixed a few obvious typos, improved indentation, added missing blank
+ lines, and so on.
- "Appendix - Sample C LDAP API Code": added #include <stdio.h> to the
- sample code. Changed the code to demonstrate good error handling by
- freeing all memory and calling ldap_unbind() before returning.
- Replaced calls to exit() with return statements. Fixed improperly
- rendered strings (by adding '\' characters to the nroff source for
- this document so that '\t' and '\n' are correctly rendered).
-Expires: 23 August 1999 [Page 77]
+Expires: May 2001 [Page 83]
\f
projects / openldap / blobdiff