New LDAP C API (Was: LDAP_DEPRECATED in OPENLDAP_REL_ENG_2_2)

["Kurt D. Zeilenga" <Kurt@OpenLDAP.org>]

At 03:18 AM 12/23/2003, Howard Chu wrote:
>> Of course, maybe we should just give up on trying to "fix" this
>> library and just write a new one...  I've been quite close to
>> doing this before (I've actually started doing it a few times),
>> but it's more work than I want to take on right now.
>
>We need to make this happen... Maybe we can just start by describing how a
>new API should be structured in general terms, in contrast to the present
>API.  After we get enough ideas collected together we'll all have a better
>idea of where to go next. Some points I have in mind:

- "proper" error handling
        Any routine which can "fail" (e.g., most) should return
        a clear indication of success or the nature of the failure.
        ("fail" here refers to API failure, not a protocol failure.)

        Protocol errors are not to be treated as API errors.

        no ld_errno, no ld->ld_errno, etc.. (This relates to
        Howard's #3.)
- API designed for thread-free implementation
- Ability to provide filters in native (LBER) form
- Applications provided extensibility where ever the ASN.1 allows it
- Applications allowed to "register" new error codes, etc..
- ldap_* be a low-level LDAP API (one-to-one mapping of API
  to protocol).  Higher level "directory" API provided above
  to handle referral chasing and such.


>1) Needs an explicit library_init/library_destroy and a library_handle. (No
>static/global state, everything referenced by the library_handle.)
>
>2) APIs for operations must have a function parameter for every operation
>protocol parameter. (E.g., current ldap_search variations all omit DEREF, so
>you can only specify this via ldap_set_option. Ugly.)
>  2a) Functions with long parameter lists are difficult to manage. Perhaps
>use request structures/parameter blocks, like 2.2 slapd.
>  2b) Caller must provide storage for pointers-to-results. (E.g., no
>mallocing struct bervals to return a berval to caller.)
>
>3) Requests and results must be bound together. (E.g., ldap_get_option(
>OPT_ERROR_NUMBER) has no notion of which result's error is being retrieved.)
>
>...
>
>  -- Howard Chu
>  Chief Architect, Symas Corp.       Director, Highland Sun
>  http://www.symas.com               http://highlandsun.com/hyc
>  Symas: Premier OpenSource Development and Support