Subject: C API questions on section 9

From: Mark Wahl <[email-masked]>
Date: Mon, 15 Nov 1999 16:55:03 -0600

I assume that when this document is sent to the RFC editors, we will remove
the paragraph:

 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
 LDAP_API_VERSION.  For example, the correct value for LDAP_API_VERSION
 for revision 04 of this draft is 2004.

Correct?  (The reason I had originally suggested an RFC number was to stop
implementors from shipping products claiming conformance to a standards-track
specification before the RFC was even published!)

In section 9.2 for LDAP_OPT_API_INFO: "If the value received is not recognized 
by the API implementation, the ldap_get_option() function ... returns an error 
without filling in any of the other fields in the LDAPAPIInfo structure.".  
So ldap_get_option() returns -1.  The question is, what does a subsequent call
to LDAP_OPT_ERROR_NUMBER return to signal this?  Since LDAP_OPT_API_INFO 
allocates memory, it can't be LDAP_NO_MEMORY, and none of the others look
suitable.  I propose that this section state that a subsequent call to get
the error number will indicate LDAP_NOT_SUPPORTED.

In section 9.2 the C API omits to mention that the caller must 
ldap_memfree(ldapai_vendor_name).

In section 9.2 I'm having trouble figuring how to use the feature info to 
obtain interoperability between a client from A, a feature from X and a 
library from Y.

 1. How do I find out _what_ the feature is?  (A client control? a new call?)
 2. How do I find out whose feature it is?  (An internal version number by
 itself is not useful - suppose vendor X adds a feature to vendor Y's base
 library - there is no guarantee that X and Y's numbering plans are 
 synchronized)
 3. How do new features register themselves so that ldap_get_option() will know
 about them?
 4. If the number could be an RFC or could be an internal number which might
 look like an RFC number, how does a client do a sensible comparison on it?

I propose we consider removing the feature info request of ldap_get_option()
from this document and consider moving it to its own document.  I suspect we 
will have enough trouble at present just getting source code interoperability
between different client libraries, that binary compatibility is still too far
away.  If you disagree, then I suggest then that we REQUIRE the version number
to be an RFC number.  

Mark Wahl, Directory Product Architect
Innosoft International, Inc.

---

From: Mark Smith <[email-masked]>
Date: Tue, 16 Nov 1999 15:47:54 -0500

> specification before the RFC was even published!)

As Kurt explained, he lobbied for the I-D based scheme.  But the text
should definitely be deleted once we publish the C API as an RFC.

> the error number will indicate LDAP_NOT_SUPPORTED.

LDAP_NOT_SUPPORTED is generally used for protocol level issues such as
trying to use a control with a v2 connection.  I suggest we use
LDAP_PARAM_ERROR since an unrecognized value was passed... but I could
be convinced to use LDAP_NOT_SUPPORTED instead.

> ldap_memfree(ldapai_vendor_name).

Actually, a chunk of text was accidentally deleted that used to be in
the draft.  This was discussed a couple of weeks ago on the list.  The
missing text includes the note about freeing ldapai_vendor_name.

>  1. How do I find out _what_ the feature is?  (A client control? a new call?)

The feature discovery mechanism is not designed to describe the details
of the feature.  The assumption is that a feature is fully described in
an API extension document (RFC) and that client applications and API
implementations that know about a given feature are both based on such a
document.

>  library - there is no guarantee that X and Y's numbering plans are

Whether vendor X can add a feature to vendor Y's API implementation
without vendor Y's cooperation is a big unknown... but from the API
specification's perspective, there is only room for one vendor.  I am
skeptical that we need to allow for a separate vendor for each feature.

>  3. How do new features register themselves so that ldap_get_option() will know

The same way any other new function is added to an API implementation --
typically by writing code and arranging for it to be linked into a
library.  A dynamic loading mechanism could be defined, and that might
help developers who are implementing API extensions -- but the feature
discovery mechanism in the C API draft is designed to serve the needs of
application writers only.

>  look like an RFC number, how does a client do a sensible comparison on it?

Presumably the match is equality, but an interesting question is whether
it makes sense to stipulate that internal numbers must be less than 2000
or something to keep them out of (future) RFC range.

> away.  If you disagree, then I suggest then that we REQUIRE the version number

I would be okay with removing LDAP_OPT_API_FEATURE_INFO, although I do
think it will prove useful.  The idea is that applications can query at
runtime to find out whether a given API extension is supported by the
API implementation they are running against.  But your point that binary
compatibility is not something we are aiming for with this specification
is a valid one.

-- 
Mark Smith
iPlanet Directory Architect / Sun-Netscape Alliance
My words are my own, not my employer's.   Got LDAP?