Re: C API questions on section 9

[Mark Smith <mcs@netscape.com>]

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

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.


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

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.



> 
> In section 9.2 the C API omits to mention that the caller must
> 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.


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

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.


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

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

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.


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

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.


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

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?