Re: C API: minor comments

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

At 04:55 PM 11/15/99 -0600, Mark Wahl wrote:
>
>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!)

I suggested the above to allow developers to experiment with the
proposed mechanisms.  I concur that should be removed during final
editing.

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

It likely could use some clarification.  I've experimented with exactly
this issue in our development branch and attempted to clarify some uses
of feature discovery within my errno/concurrency drafts.

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

The mechanism only allows you discover whether the feature
exists or not, but does not describe the feature itself.

You likely need to consult your <ldap.h> and your vendors documentation.

Note: the existance of a new client control may not necessilary be
described as a feature.  I think Mark Smith posted some comments in
this area a while back.

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

The library providing ldap_get_option should provide a
mechanism for you to discover who provided any feature listed via LDAP_OPT_API_FEATURE_INFO.

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

Not specified, hence implementation specific.

> 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?

The only sensible comparison is equality.

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

Some vendors offer multiple libraries which share a common <ldap.h>
and rely on ldap_get_option LDAP_OPT_API_FEATURE_INFO to allow which
features are provided dynamically.  See my errno and concurrency
drafts on one approach (zeilenga-ldap-errno, section 5. "Advertising
Features").

I would not be opposed to moving feature discovery into separate
document.

>If you disagree, then I suggest then that we REQUIRE the version number
>to be an RFC number.

I would be opposed to limiting the version number to a RFC number.
I believe non-RFC features should be discoverable using this mechanism.