C API questions on section 9

[Mark Wahl <M.Wahl@INNOSOFT.COM>]

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.