ldap-c-api comments (Was: LDAPEXT status and last calls)

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

Pardon my previous reply.  I obviously hit the wrong key...

Mark C Smith wrote:
> "Kurt D. Zeilenga" wrote:
> > In particular, I believe the following issues must be
> > addressed before it should be progressed:

Another important issue is the use of 'int' vs 'long'  and 'int'/'long' vs
a fixed sized type within the document.  Understanding the heartburn that
existing implementators might have to suffer, I suggest we carefully
analysis our use of these types and determine on a case by case basis
which ones should be changed.

> > * UTF-8 requirement for DNs/string values
> >         Needs to be clarified what is required of the implementation
> >         when using LDAPv2 and detailing specific translation requirements.
> 
> My personal view is that (1) LDAPv2 is not very interesting as it is on its
> way out and (2) implementations have done a lot of different things with
> respect to charsets used in LDAPv2.

When I read the draft, I saw UTF-8 was required for all DNs and string values
regradless of the underlying protocol used.  This would be difficult to implement
and cause more problems that it would be solve.

I agree only clarification of the UTF-8 statement is needed. 

> We can argue the merits of different
> approaches,

We can defer that discussion until an actual extension is proposed.

>but since we are specifying an API for LDAPv3 I do not believe we
> should spend a lot of effort on this area.

I actually hope to migrate to this API independently of our migration
to LDAPv3...   If the default protocol is going to be LDAPv2, than it
damn better be usable.  (I believe it is).

> A statement such as "If the LDAP
> API is used to communicate with LDAPv2 servers, the character set used for
> attribute values and DNs when they are passed and and out of LDAP API
> functions should match that defined by LDAPv2 (typically ASCII or T.61)."
> What do you think?

I basically agree and do believe we can and should escape this issue by
changing the UTF-8 requirement statement (section 5, page 5).  I would
suggest a little different wording... maybe replace that paragraph with:

	All requiring that the DN and string attributes passed into or
	our produced by the C LDAP API are represented using the character
	encoding of the underlying LDAP protocol version.  When this API
	is used with LDAPv3, DN and strings attributes are UTF-8.  When
	this API is used with LDAPv2, DN and string attributes are T.61.
	Some LDAP API implementations may provide API extensions to support
	other character sets.  These extensions are not described by this
	document.

> > * Header requirements should be detailed.
> 
> I plan to incorporate some of your earlier comments into the draft.
> Specifically, I agree that the ldap.h header file should have all of these
> characteristics: idempotent, mutually independent, equivalent to file level
> declarations, well documented.

I look forward to your next revision.

I'd very much like to see:
	LDAP_VENDOR_NAME
	LDAP_VENDOR_VERSION
macros added so that an application can verify the header matches the
runtime API info.

I would also allow implementations to (in ldap.h):
	struct timeval;  /* avoid pulling in system headers */

for reasons previously stated.

> > Also, all the "Outstanding Issues" should be resolved:
> 
> In my opinion, most of these can be safely deferred to separate extension
> documents.

I concur.

> > 23.7 Session Options
> >         ldap_get/set_option interface should be nailed down.
> 
> I am pretty happy with it as currently defined, but will respond to your
> earlier comments on the subject.  There is definitely a tradeoff between
> creating the perfect API and maintaining compatibility with existing
> implementations (this draft has been around for a long time now).

I feel strongly that the allocation/deallocation handling exceptions for
strings and controls be removed. That is, the caller is responsible for freeing
memory associated with the use of these calls.  The implementation must provide
copies of info on gets and make copies on sets.

I very much would like to ldap_get/set_option return an error code instead
of just a boolean success/failure.  I believe this could be done without
breaking existing implementations.


I look forward to your comments on this and previous postings.   I appreciate
very much the work in this area and hope that a revised draft can be progressed
quickly.

	-- Kurt