[ldapext] [Fwd: LDAP C API gripes]

[Howard Chu <hyc@highlandsun.com>]

I've created this page  http://scratchpad.wikia.com/wiki/LDAP_C_API for 
putting together ideas for a new LDAP C API. The fact that the last 
LDAPv3 API doc never made it out of draft status really needs to be 
addressed, and there are so many flaws with the API (essentially 
inherited from the LDAPv2 API) that it's obvious a simple refresh is 
inadequate. The fact that groups like the Samba team have decided it was 
necessary to create their own LDAP API underscores the point. If anybody 
has comments on what is broken and how it can be fixed, please chime in.

-------- Original Message --------
Subject: 	LDAP C API gripes
Date: 	Mon, 12 Feb 2007 06:27:41 -0800


Probably this should just go out on the ldapext mailing list again. The 
main discussion I referred to started here
http://www.openldap.org/lists/openldap-devel/200312/msg00123.html

I posted my laundry list here
http://www.openldap.org/lists/openldap-devel/200312/msg00187.html

Kurt's followup adds some other considerations.

The list thus far:

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) Simplified APIs are still desirable, for apps that don't care about
controls/extensions/whatever.

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.)

4) char *'s should be avoided, use struct bervals more extensively
4a) the API is too malloc-happy. result parsing etc. should be done in-place
as much as possible.

- "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.

Another gripe I noted was that a lot of APIs are poorly named, but
that should be an easy one to fix along the way.


Obviously from the Samba side we need APIs that allow an external event 
handler to interact with the API. This includes using an already 
connected socket with the library, and being able to trigger response 
processing based on an external trigger/callback/whatever.

If you have suggestions for who else to get involved, let me know, and 
just forward this on. Once we figure out the correct forum for the 
discussion we can go on from there. Perhaps we should use the 
FAQ-o-Matic or a wiki for maintaining the updated list and evolving the 
spec.

--
 -- Howard Chu
 Chief Architect, Symas Corp.  http://www.symas.com
 Director, Highland Sun        http://highlandsun.com/hyc
 Chief Architect, OpenLDAP     http://www.openldap.org/project/


_______________________________________________
Ldapext mailing list
Ldapext@ietf.org
https://www1.ietf.org/mailman/listinfo/ldapext