mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
715 lines
27 KiB
Plaintext
715 lines
27 KiB
Plaintext
|
INTERNET-DRAFT Kurt D. Zeilenga
|
||
|
Intended Category: Standards Track OpenLDAP Foundation
|
||
|
Extends: draft-ietf-ldapext-ldap-c-api-03.txt
|
||
|
Expires: 28 March 2000
|
||
|
28 September 1999
|
||
|
|
||
|
LDAP C API Concurrency Extensions
|
||
|
<draft-zeilenga-ldap-c-api-concurrency-00.txt>
|
||
|
|
||
|
1. Status of this Memo
|
||
|
|
||
|
This document is an Internet-Draft and is in full conformance with all
|
||
|
provisions of Section 10 of RFC2026.
|
||
|
|
||
|
This draft document will be submitted to the RFC Editor as a Standards
|
||
|
Track document. Distribution of this memo is unlimited. Technical
|
||
|
discussion of this document will take place on the IETF LDAP Extension
|
||
|
Working Group mailing list <ietf-ldapext@netscape.com>. Please send
|
||
|
editorial comments directly to the author <Kurt@OpenLDAP.org>.
|
||
|
|
||
|
Internet-Drafts are working documents of the Internet Engineering Task
|
||
|
Force (IETF), its areas, and its working groups. Note that other
|
||
|
groups may also distribute working documents as Internet-Drafts.
|
||
|
|
||
|
Internet-Drafts are draft documents valid for a maximum of six months
|
||
|
and may be updated, replaced, or obsoleted by other documents at any
|
||
|
time. It is inappropriate to use Internet-Drafts as reference
|
||
|
material or to cite them other than as "work in progress."
|
||
|
|
||
|
The list of current Internet-Drafts can be accessed at
|
||
|
http://www.ietf.org/ietf/1id-abstracts.txt
|
||
|
|
||
|
The list of Internet-Draft Shadow Directories can be accessed at
|
||
|
http://www.ietf.org/shadow.html.
|
||
|
|
||
|
Copyright 1999, The Internet Society. All Rights Reserved.
|
||
|
|
||
|
Please see the Copyright section near the end of this document for
|
||
|
more information.
|
||
|
|
||
|
2. Abstract
|
||
|
|
||
|
This document defines extensions to the LDAP C API to support use in
|
||
|
concurrent execution environments. The document describes and defines
|
||
|
|
||
|
Zeilenga [Page 1]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
requirements for multiple concurrency levels: thread safe, session
|
||
|
thread safe, and operation thread safe.
|
||
|
|
||
|
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||
|
"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
|
||
|
to be interpreted as described in RFC 2119 [KEYW].
|
||
|
|
||
|
3. Introduction
|
||
|
|
||
|
This document extends the LDAP C API [CAPI] specification to support
|
||
|
use in concurrent execution environments. The extensions add powerful
|
||
|
concurrent processing capabilities to the simple to use CAPI. This
|
||
|
document provides an overview of different levels of concurrent
|
||
|
execution support and offers a number of CAPI "features" to provide
|
||
|
capabilities at these levels.
|
||
|
|
||
|
The remainder of this section describes three levels of concurrent
|
||
|
execution: thread safe, session thread safe, operation thread safe
|
||
|
APIs.
|
||
|
|
||
|
3.1. Thread Safe
|
||
|
|
||
|
An implementation which allows applications to safely execute in
|
||
|
concurrent execution environments where the application provides
|
||
|
necessary synchronization to ensure serialization of CAPI usage is
|
||
|
considered to be "thread safe." Applications may execute non-CAPI
|
||
|
calls in concurrent execution contexts when using thread safe
|
||
|
implementations.
|
||
|
|
||
|
3.2. Session Thread Safe
|
||
|
|
||
|
A "thread safe" implementation which allows CAPI calls associated with
|
||
|
different LDAP sessions to proceed asychronously is considered to be
|
||
|
"session thread safe."
|
||
|
|
||
|
3.3. Operation Thread Safe
|
||
|
|
||
|
A "session thread safe" implementation which allows CAPI calls
|
||
|
associated with different LDAP operations to proceed asychronously is
|
||
|
considered to be "operation thread safe".
|
||
|
|
||
|
4. Basic Thread Safe Feature
|
||
|
|
||
|
Zeilenga [Page 2]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
This section details requirements for the thread safe CAPI feature.
|
||
|
Implementations fulfilling these requirements are said to support the
|
||
|
LDAP_API_FEATURE_THREAD_SAFE feature and SHOULD advertise this support
|
||
|
as detailed below. This feature SHOULD be provided by
|
||
|
implementations.
|
||
|
|
||
|
Implementations of this feature MUST implement the LDAP error handling
|
||
|
extension [ERRNO].
|
||
|
|
||
|
Implementations of this feature MUST allow non-CAPI calls to proceed
|
||
|
asynchronously.
|
||
|
|
||
|
Implementations of this feature MUST NOT use any non-thread safe call
|
||
|
or mechanism provided by C environment or operating system. An
|
||
|
example of non-reentrant calls is the UNIX strtok() function. Example
|
||
|
of a non-reentrant mechanism is global (i.e.: non-thread specific)
|
||
|
errno.
|
||
|
|
||
|
5. Session Thread Safe Feature
|
||
|
|
||
|
This section details requirements for the session thread safe CAPI
|
||
|
feature. Implementations fulfilling these requirements are said to
|
||
|
support the LDAP_API_FEATURE_SESSION_THREAD_SAFE feature and SHOULD
|
||
|
advertise this support as detailed below. This feature is
|
||
|
RECOMMENDED.
|
||
|
|
||
|
5.1. Prerequisite Features
|
||
|
|
||
|
Implementations providing this feature MUST provide and advertise both
|
||
|
LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO] and
|
||
|
LDAP_API_FEATURE_THREAD_SAFE.
|
||
|
|
||
|
5.2. Atomic Session Handles
|
||
|
|
||
|
Implementations providing this feature SHOULD ensure that operations
|
||
|
upon a given session handle are atomic. Implementations which provide
|
||
|
atomic session handles SHOULD advertise the feature
|
||
|
LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES.
|
||
|
|
||
|
5.3. Concurrency Requirements
|
||
|
|
||
|
Implementations providing this feature MUST not restrict CAPI calls
|
||
|
acting upon a given LDAP session to a particular execution context.
|
||
|
Applications MAY use a session handle on any thread. Applications
|
||
|
|
||
|
Zeilenga [Page 3]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
MUST NOT assume that operations upon a session are atomic.
|
||
|
|
||
|
Implementations providing this feature MUST allow CAPI calls acting
|
||
|
upon different LDAP sessions to safely proceed asynchronously.
|
||
|
|
||
|
Implementations providing this feature MUST allow CAPI calls not
|
||
|
acting upon an LDAP session to safely proceed asynchronously.
|
||
|
|
||
|
6. Operation Thread Safe Feature
|
||
|
|
||
|
This section details requirements for the operation thread safe CAPI
|
||
|
feature based upon a duplicate session handles mechanism.
|
||
|
|
||
|
Implementations fulfilling these requirements are said to support the
|
||
|
LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES feature and SHOULD
|
||
|
advertise this support as detailed below. This feature is OPTIONAL.
|
||
|
|
||
|
6.1. Prerequisite Features
|
||
|
|
||
|
Implementations of this feature MUST provide and advertise
|
||
|
LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO],
|
||
|
LDAP_API_FEATURE_THREAD_SAFE, LDAP_API_FEATURE_SESSION_THREAD_SAFE,
|
||
|
and LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES.
|
||
|
|
||
|
6.2. Duplicated Session Handles
|
||
|
|
||
|
Implementations of this feature MUST support duplicated session
|
||
|
handles.
|
||
|
|
||
|
As defined in CAPI, a session handle refers to an LDAP session
|
||
|
encompassing connections with one or more servers, associated message
|
||
|
results, a set of properties (options), and state information. This
|
||
|
feature provides a mechanism for a handle to be duplicated. A session
|
||
|
handle and its duplicates are considered siblings. Each sibling
|
||
|
session handle refers to the same LDAP session and message results.
|
||
|
Some properties and state are specific to a handle and others shared
|
||
|
between siblings as detailed below.
|
||
|
|
||
|
CAPI calls made on a handle are atomic. Calls made on sibling (or
|
||
|
other) handles MAY proceed asynchronously.
|
||
|
|
||
|
Session handles are duplicated using ldap_dup() and destroyed using
|
||
|
ldap_destroy(). Use of duplicated session handles with CAPI calls
|
||
|
have the following semantics detailed in the sections below.
|
||
|
|
||
|
Zeilenga [Page 4]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
6.2.1. Creating and Destroying duplicated sessions
|
||
|
|
||
|
Implementations of this feature are required to provide two new
|
||
|
routines: LDAP *ldap_dup( ld ); int ldap_destroy( ld );
|
||
|
|
||
|
Parameters are: ld The session handle
|
||
|
|
||
|
The ldap_dup() function returns a duplicate of a session handle. The
|
||
|
returned session handle may be used concurrently with the original
|
||
|
session handle as described below. ldap_dup returns NULL if it is not
|
||
|
able to duplicate the session handle and sets LDAP_OPT_ERROR_NUMBER
|
||
|
and ldap_errno indicating the nature of the failure.
|
||
|
|
||
|
The ldap_destroy() function destroys the session handle. If the
|
||
|
session handle has no siblings, ldap_destroy behaves exactly like
|
||
|
ldap_unbind. If the session handle has siblings, the resources
|
||
|
assocated with the handle are released and the siblings remain valid.
|
||
|
ldap_destroy() returns LDAP_SUCCESS or an error number indicating the
|
||
|
nature of failure. Regardless of returned value, the handle SHOULD be
|
||
|
considered invalid and MUST not be used in subsequent calls. Attempts
|
||
|
to use a destroyed session handle MUST NOT result in
|
||
|
LDAP_INVALID_SESSION error being reported. Implementations SHOULD
|
||
|
report LDAP_PARAM_ERROR in such cases.
|
||
|
|
||
|
6.2.2. ldap_unbind and siblings
|
||
|
|
||
|
When ldap_unbind() is called on a session handle with siblings, the
|
||
|
siblings become invalid. The siblings must be destroyed using
|
||
|
ldap_destroy(). All attempts to obtain the siblings'
|
||
|
LDAP_OPT_ERROR_NUMBER will return LDAP_INVALID_SESSION. Any use other
|
||
|
than ldap_destroy() or reading LDAP_OPT_ERROR_NUMBER will fail with an
|
||
|
LDAP_INVALID_SESSION error being reported.
|
||
|
|
||
|
6.2.3. ldap_result()
|
||
|
|
||
|
Message queues are shared between siblings. Results of operations on
|
||
|
a duplicated session handles are accessible to all sibling session
|
||
|
handles.
|
||
|
|
||
|
Applications desiring results associated with a specific operation
|
||
|
SHOULD provide the appropriate msgid to ldap_result(). Applications
|
||
|
SHOULD avoid calling ldap_result() with LDAP_RES_ANY as such may
|
||
|
"steal" and return results which an operation on a sibling requires to
|
||
|
complete.
|
||
|
|
||
|
Zeilenga [Page 5]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
6.2.4. Session Options
|
||
|
|
||
|
The following CAPI options access values shared between siblings:
|
||
|
|
||
|
LDAP_OPT_API_INFO LDAP_OPT_DESC LDAP_OPT_REFERRALS
|
||
|
LDAP_OPT_PROTOCOL_VERSION LDAP_OPT_API_FEATURE_INFO
|
||
|
LDAP_OPT_HOST_NAME
|
||
|
|
||
|
The following CAPI options access values specific to a sibling:
|
||
|
|
||
|
LDAP_OPT_DEREF LDAP_OPT_SIZELIMIT LDAP_OPT_TIMELIMIT
|
||
|
LDAP_OPT_RESTART LDAP_OPT_CLIENT_CONTROLS
|
||
|
LDAP_OPT_SERVER_CONTROLS LDAP_OPT_ERROR_NUMBER
|
||
|
LDAP_OPT_ERROR_STRING LDAP_OPT_MATCHED_DN
|
||
|
|
||
|
6.2.4.1. LDAP_OPT_SESSION_REFCNT
|
||
|
|
||
|
In addition, implementations MUST provide the READ-ONLY, shared
|
||
|
LDAP_OPT_SESSION_REFCNT option. LDAP_OPT_SESSION_REFCNT returns the
|
||
|
reference count associated with the supplied session handle argument.
|
||
|
The session handle argument is required. The outvalue argument should
|
||
|
be a pointer to an integer. Example use:
|
||
|
|
||
|
int refcount(LDAP *ld) {
|
||
|
|
||
|
#ifdef LDAP_OPT_SESSION_REFCNT
|
||
|
|
||
|
if(ld != NULL) {
|
||
|
int refcnt, rc;
|
||
|
rc = ldap_get_option(ld,
|
||
|
LDAP_OPT_SESSION_REFCNT, &refcnt);
|
||
|
|
||
|
if(rc == LDAP_OPT_SUCCESS) {
|
||
|
return refcnt;
|
||
|
}
|
||
|
}
|
||
|
|
||
|
#endif
|
||
|
|
||
|
return -1;
|
||
|
}
|
||
|
|
||
|
7. Advertising Features
|
||
|
|
||
|
This document REQUIRES that supported features with the name in the
|
||
|
form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as
|
||
|
|
||
|
Zeilenga [Page 6]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
follows:
|
||
|
|
||
|
SHOULD provide the macro LDAP_API_FEATURE_x with the value
|
||
|
of 1000 + revision number of this draft (i.e.: 1000+0 for
|
||
|
this 0 revision of the draft).
|
||
|
|
||
|
MUST provide the CAPI extension "x" when returning API
|
||
|
information upon LDAP_OPT_API_INFO option access, and
|
||
|
|
||
|
MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO
|
||
|
option mechanism. The feature version provided MUST match
|
||
|
the value LDAP_API_FEATURE_x macro
|
||
|
|
||
|
where x is replaced appropriately.
|
||
|
|
||
|
As implementations may not provide macros for all features,
|
||
|
applications SHOULD use LDAP_OPT_API_INFO to determine which features
|
||
|
are provided by a given implementation.
|
||
|
|
||
|
8. Changes to the C API specification
|
||
|
|
||
|
8.1. New Symbols
|
||
|
|
||
|
This extension introduces the following macros:
|
||
|
|
||
|
LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES
|
||
|
LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES
|
||
|
LDAP_API_FEATURE_SESSION_THREAD_SAFE
|
||
|
LDAP_API_FEATURE_THREAD_SAFE
|
||
|
LDAP_API_FEATURE_OPERATION_THREAD_SAFE LDAP_INVALID_SESSION
|
||
|
LDAP_OPT_SESSION_REFCNT
|
||
|
|
||
|
This extension introduces these new functions:
|
||
|
|
||
|
ldap_destroy() ldap_dup()
|
||
|
|
||
|
This extension introduces no new typedefs nor structure names.
|
||
|
|
||
|
8.2. Duplicated Session Handles
|
||
|
|
||
|
This extension introduces duplicated session handles and requirements
|
||
|
for handling duplicated session handles. Semantics of non-duplicated
|
||
|
session handles are not affected by this introduction. However, the
|
||
|
semantics of calls upon duplicate session handles differs as described
|
||
|
in the extension.
|
||
|
|
||
|
Zeilenga [Page 7]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
9. Security Considerations
|
||
|
|
||
|
None taken, none given.
|
||
|
|
||
|
10. Copyright
|
||
|
|
||
|
Copyright 1999, The Internet Society. All Rights Reserved.
|
||
|
|
||
|
This document and translations of it may be copied and furnished to
|
||
|
others, and derivative works that comment on or otherwise explain it
|
||
|
or assist in its implementation may be prepared, copied, published and
|
||
|
distributed, in whole or in part, without restriction of any kind,
|
||
|
provided that the above copyright notice and this paragraph are
|
||
|
included on all such copies and derivative works. However, this
|
||
|
document itself may not 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 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
|
||
|
revoked by the Internet Society or its successors or assigns.
|
||
|
|
||
|
This document and the information contained herein is provided on an
|
||
|
"AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
|
||
|
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
|
||
|
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
|
||
|
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
|
||
|
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
||
|
|
||
|
11. Bibliography
|
||
|
|
||
|
[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The
|
||
|
C LDAP Application Program Interface", INTERNET-DRAFT, <draft-
|
||
|
ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions, June 1999.
|
||
|
|
||
|
[ERRNO] K. Zeilenga, "LDAP C API Error Reporting Extension",
|
||
|
INTERNET-DRAFT, <draft-zeilenga-ldap-c-api-errno-00.txt>,
|
||
|
June 1999.
|
||
|
|
||
|
[KEYW] S. Bradner, "Key words for use in RFCs to Indicate
|
||
|
Requirement Levels", RFC 2119, March 1997.
|
||
|
|
||
|
Zeilenga [Page 8]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
|
||
|
|
||
|
[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
|
||
|
Access Protocol (v3)", RFC 2251, December 1997.
|
||
|
|
||
|
13. Author's Address
|
||
|
|
||
|
Kurt D. Zeilenga
|
||
|
OpenLDAP Foundation
|
||
|
<Kurt@OpenLDAP.org>
|
||
|
|
||
|
This document expires on 28 March 2000.
|
||
|
|
||
|
Zeilenga [Page 9]
|
||
|
|
||
|
---------------------------------------------------------------------
|
||
|
|
||
|
INTERNET-DRAFT Kurt D. Zeilenga
|
||
|
Intended Category: Standards Track OpenLDAP Foundation
|
||
|
Extends: draft-ietf-ldapext-ldap-c-api-03.txt
|
||
|
Expires: 28 March 2000
|
||
|
28 September 1999
|
||
|
|
||
|
LDAP C API Error Reporting Extension
|
||
|
<draft-zeilenga-ldap-c-api-errno-00.txt>
|
||
|
|
||
|
1. Status of this Memo
|
||
|
|
||
|
This document is an Internet-Draft and is in full conformance with all
|
||
|
provisions of Section 10 of RFC2026.
|
||
|
|
||
|
This draft document will be submitted to the RFC Editor as a Standards
|
||
|
Track document. Distribution of this memo is unlimited. Technical
|
||
|
discussion of this document will take place on the IETF LDAP Extension
|
||
|
Working Group mailing list <ietf-ldapext@netscape.com>. Please send
|
||
|
editorial comments directly to the author <Kurt@OpenLDAP.org>.
|
||
|
|
||
|
Internet-Drafts are working documents of the Internet Engineering Task
|
||
|
Force (IETF), its areas, and its working groups. Note that other
|
||
|
groups may also distribute working documents as Internet-Drafts.
|
||
|
|
||
|
Internet-Drafts are draft documents valid for a maximum of six months
|
||
|
and may be updated, replaced, or obsoleted by other documents at any
|
||
|
time. It is inappropriate to use Internet-Drafts as reference
|
||
|
material or to cite them other than as ``work in progress.''
|
||
|
|
||
|
The list of current Internet-Drafts can be accessed at
|
||
|
http://www.ietf.org/ietf/1id-abstracts.txt
|
||
|
|
||
|
The list of Internet-Draft Shadow Directories can be accessed at
|
||
|
http://www.ietf.org/shadow.html.
|
||
|
|
||
|
Copyright 1999, The Internet Society. All Rights Reserved.
|
||
|
|
||
|
Please see the Copyright section near the end of this document for
|
||
|
more information.
|
||
|
|
||
|
2. Abstract
|
||
|
|
||
|
This document defines a manatory extension to the LDAP C API to
|
||
|
provide error reporting for all API calls. The mechanism is
|
||
|
nonintrusive and can, optionally, support concurrent execution
|
||
|
environments.
|
||
|
|
||
|
Zeilenga [Page 1]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
|
||
|
|
||
|
The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL
|
||
|
NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', and ``MAY'' in
|
||
|
this document are to be interpreted as described in RFC 2119 [KEYW].
|
||
|
|
||
|
3. Background and Intent of Use
|
||
|
|
||
|
The LDAP [LDAP] C API [CAPI] provides an interface which (due to
|
||
|
legacy compatibiity issues) does not provide a consistent mechanism
|
||
|
for reporting errors. A large number of the calls within the
|
||
|
specification have no mechanism to indicate the nature of a failure.
|
||
|
The usefulness of a CAPI without a consistent, easy to use, error
|
||
|
reporting mechanism is limited.
|
||
|
|
||
|
This document defines an mandatory extension to the CAPI. All
|
||
|
implementations of the CAPI MUST provide this extension.
|
||
|
|
||
|
The extension details additional requirements for error reporting.
|
||
|
Implementations MUST fulfill all other CAPI error reporting
|
||
|
requirements.
|
||
|
|
||
|
4. Error Handling Extension
|
||
|
|
||
|
This extension provides a mechanism that applications MAY use to
|
||
|
obtain an LDAP error number indicating the nature of the failure
|
||
|
associated with the last failed CAPI call.
|
||
|
|
||
|
Implementations MUST provide access to an LDAP error number (CAPI,
|
||
|
Section 9) resulting from the last failed CAPI call via the symbol
|
||
|
ldap_errno. The last failed CAPI call may be within the global
|
||
|
context or within the current execution context.
|
||
|
|
||
|
The ldap_errno MUST evaluate to a modifiable lvalue that has type
|
||
|
'int', the value of which is set to a LDAP error number. It is
|
||
|
unspecified whether ldap_errno is a macro or an identifier declared
|
||
|
with external linkage. If a macro definition is suppressed in order
|
||
|
to access an actual object, or a program defines an identifier with
|
||
|
the name ldap_errno, the behavior is undefined.
|
||
|
|
||
|
Applications MUST access ldap_errno within the same concurrent
|
||
|
execution context, commonly a thread, in which the failure occurred.
|
||
|
The value of ldap_errno is LDAP_SUCCESS (0) if no API failure has
|
||
|
occurred within the supported context and the user has not assigned a
|
||
|
value within the supported context.
|
||
|
|
||
|
Zeilenga [Page 2]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
|
||
|
|
||
|
Implementations SHALL NOT update the ldap_errno value upon successful
|
||
|
CAPI call completion.
|
||
|
|
||
|
Implementations providing a current execution context specific
|
||
|
ldap_errno MUST advertise the feature LDAP_API_CONTEXT_SPECIFIC_ERRNO
|
||
|
as described in Section 6. Implementation of
|
||
|
LDAP_API_CONTEXT_SPECIFIC_ERRNO is RECOMMENDED.
|
||
|
|
||
|
4.1. Reporting Server Errors
|
||
|
|
||
|
It is not a CAPI failure for a server to return an error number.
|
||
|
Implementations SHALL NOT assign error results returned by servers to
|
||
|
ldap_errno.
|
||
|
|
||
|
4.2. Implementation Specific Reporting
|
||
|
|
||
|
The CAPI specification stated that the caller may obtain an indication
|
||
|
of failure of certain calls (see listed below) using implementation
|
||
|
specific and/or operating system specific requirements.
|
||
|
Implementations are NOT REQUIRED to support any implementation
|
||
|
specific and/or operating system mechanism for ANY call detailed by
|
||
|
the CAPI specification or its extensions.
|
||
|
|
||
|
Affected calls include ldap_init(), ldap_open(), and ber_*().
|
||
|
|
||
|
4.3. Example
|
||
|
|
||
|
The following is an example showing how an application may obtain the
|
||
|
error information resulting from a failed CAPI calls:
|
||
|
|
||
|
int msgid;
|
||
|
LDAP *ld = ldap_init("localhost", 389);
|
||
|
|
||
|
if(ld == NULL) {
|
||
|
printf("ldap_init failed, ldap_errno=%d (%s)\n",
|
||
|
ldap_errno, ldap_err2string(ldap_errno));
|
||
|
|
||
|
printf("unable to initialize LDAP session\n");
|
||
|
return -1;
|
||
|
}
|
||
|
|
||
|
msgid = ldap_simple_bind(ld, NULL, NULL);
|
||
|
|
||
|
if(msgid == -1) {
|
||
|
int err = ldap_errno;
|
||
|
|
||
|
if (err != LDAP_SUCCESS ) {
|
||
|
|
||
|
Zeilenga [Page 3]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
|
||
|
|
||
|
/* API failure */
|
||
|
printf("ldap_simple_bind failure: ldap_errno=%d (%s)\n",
|
||
|
err, ldap_err2string(err));
|
||
|
|
||
|
} else {
|
||
|
int lderr, rc;
|
||
|
|
||
|
printf("ldap_simple_bind failed\n");
|
||
|
|
||
|
rc = ldap_get_option(ld,
|
||
|
LDAP_OPT_ERROR_NUMBER, &lderr);
|
||
|
|
||
|
if(rc == LDAP_OPT_SUCCESS) {
|
||
|
printf(" reason=%d (%s)\n",
|
||
|
lderr, ldap_err2string(lderr));
|
||
|
|
||
|
} else {
|
||
|
printf("ldap_get_option failed, ldap_errno=%d (%s)\n",
|
||
|
ldap_errno, ldap_err2string(ldap_errno)); }
|
||
|
}
|
||
|
|
||
|
goto unbind;
|
||
|
}
|
||
|
|
||
|
/* ... */
|
||
|
|
||
|
unbind: if(ldap_unbind(ld) != 0) {
|
||
|
printf("ldap_unbind failed, ldap_errno=%d (%s)\n",
|
||
|
ldap_errno, ldap_error2str(ldap_errno));
|
||
|
|
||
|
return -1;
|
||
|
}
|
||
|
return 0;
|
||
|
|
||
|
5. Advertising Features
|
||
|
|
||
|
This document REQUIRES that supported features with the name in the
|
||
|
form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as
|
||
|
follows:
|
||
|
|
||
|
SHOULD provide the macro LDAP_API_FEATURE_x with the value
|
||
|
of 1000 + revision number of this draft (i.e.: 1000+0 for
|
||
|
this 0 revision of the draft).
|
||
|
|
||
|
MUST provide the CAPI extension "x" when returning API
|
||
|
information upon LDAP_OPT_API_INFO option access, and
|
||
|
|
||
|
Zeilenga [Page 4]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
|
||
|
|
||
|
MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO
|
||
|
option mechanism. The feature version provided MUST match
|
||
|
the value LDAP_API_FEATURE_x macro
|
||
|
|
||
|
where x is replaced appropriately.
|
||
|
|
||
|
As implementations may not provide macros for all features,
|
||
|
applications SHOULD use LDAP_OPT_API_INFO to determine which features
|
||
|
are provided by a given implementation.
|
||
|
|
||
|
6. Changes to the LDAP C API
|
||
|
|
||
|
This section provides a summary of changes to the CAPI specification.
|
||
|
|
||
|
6.1. LDAP_API_VERSION
|
||
|
|
||
|
LDAP_API_VERSION should be set to the RFC number of this extension if
|
||
|
and when it is published as a Standards Track RFC. (see purpose of
|
||
|
this draft above).
|
||
|
|
||
|
Until such time as this document is published as an RFC,
|
||
|
implementations should use the value specified by CAPI plus 100 + 10 *
|
||
|
the number of this draft.
|
||
|
|
||
|
For the third draft of CAPI and this 0 revision of draft, the value of
|
||
|
2103 ((2000+3) + (100+10*0)) should be used.
|
||
|
|
||
|
6.2. New Symbols
|
||
|
|
||
|
This extension introduces two new symbols:
|
||
|
LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO ldap_errno
|
||
|
|
||
|
LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO is a macro. ldap_errno MAY be
|
||
|
a MACRO.
|
||
|
|
||
|
This extension indroductes no new functions, typedefs, or structure
|
||
|
names.
|
||
|
|
||
|
6.3. Implementation/System Specific Error Handling
|
||
|
|
||
|
This extensions removes any requirements that implementations to use
|
||
|
implementation and/or operating system specific error reporting
|
||
|
mechanisms.
|
||
|
|
||
|
Zeilenga [Page 5]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
|
||
|
|
||
|
7. Security Considerations
|
||
|
|
||
|
None taken, none given.
|
||
|
|
||
|
8. Copyright
|
||
|
|
||
|
Copyright 1999, The Internet Society. All Rights Reserved.
|
||
|
|
||
|
This document and translations of it may be copied and furnished to
|
||
|
others, and derivative works that comment on or otherwise explain it
|
||
|
or assist in its implementation may be prepared, copied, published and
|
||
|
distributed, in whole or in part, without restriction of any kind,
|
||
|
provided that the above copyright notice and this paragraph are
|
||
|
included on all such copies and derivative works. However, this
|
||
|
document itself may not 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 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
|
||
|
revoked by the Internet Society or its successors or assigns.
|
||
|
|
||
|
This document and the information contained herein is provided on an
|
||
|
"AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
|
||
|
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
|
||
|
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
|
||
|
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
|
||
|
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
||
|
|
||
|
9. Bibliography
|
||
|
|
||
|
[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha,
|
||
|
"The C LDAP Application Program Interface", INTERNET-DRAFT,
|
||
|
<draft-ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions,
|
||
|
June 1999.
|
||
|
|
||
|
[KEYW] S. Bradner, "Key words for use in RFCs to Indicate
|
||
|
Requirement Levels", RFC 2119, March 1997.
|
||
|
|
||
|
[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
|
||
|
Access Protocol (v3)", RFC 2251, December 1997.
|
||
|
|
||
|
Zeilenga [Page 6]
|
||
|
|
||
|
INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
|
||
|
|
||
|
10. Author's Address
|
||
|
|
||
|
Kurt D. Zeilenga
|
||
|
OpenLDAP Foundation
|
||
|
<Kurt@OpenLDAP.org>
|
||
|
|
||
|
This document expires on 28 March 2000.
|
||
|
|
||
|
Zeilenga [Page 7]
|