[Date Prev][Date Next] [Chronological] [Thread] [Top]

API info in ldapext-ldap-c-api-01

The API draft features for detecting implementation information
at compile time and execution time are fairly sound.  However,
I do have a few comments and suggestions based on our early
implementation experiences.

LDAP_API_VERSION (7.1, page 6)
  I assume there will be implementations of this draft.
  I assume there will be addition revisions of this draft.
  I assume there will future drafting of future C API specifications.

How should draft implementations define (or not define) LDAP_API_VERSION?
Should this be left for a exercise for early implementers?

In our OpenLDAP development, LDAP_API_VERSION is assigned to
2000 + draft revision number.  This makes LDAP_API_VERSION greater
than 1823 and less than the RFC number to eventually assigned.

NOTE: the LDAP_API_VERSION test on page 6 should be '>=' not '>'.


LDAP_API_FEATURE_X_VENDOR_EXTENSION (7.1, page 6)

I believe the draft should state what the vendor "SHOULD" use
as identifiers (or at least what they shouldn't).  For example,
LDAP_API_FEATURE_X_OL_FOO could be define by both OpenLDAP and
Obfuscated LDAP.


Additional defines.

I would like to see additional defines to allow compile time
checking of vendor name, version, and the supported protocols.

LDAP_VERSION_MIN
	specifies the minimum protocol version supported.
	(could be deferred until LDAPv4)

LDAP_VERSION_MAX
	specifies the maximum protocol version supported.
	Should match what returned by ldapai_protocol_version.

LDAP_API_VENDOR_NAME
	should match what's returned in LDAPAPIInfo.  Also,
	this should be used as the vendor identifier portion of
	LDAP_API_X_VENDOR_EXT and corresponding ldapai_extension
	strings.
	Example: "OPENLDAP"

LDAP_API_VENDOR_VERSION
	should match what's returned in LDAPAPIInfo.


LDAPAPIInfo struct (page7)

Why is the LDAPAPIinfo version number not the same as the
LDAP_API_VERSION?

The only reason I could see that an independent version
number would be needed is if this specification of its
members could be changed through extension of the API.
I would argue that this structure should ONLY be changed
through re-specification of the API.  Assuming this:

ldap.h can define one and only one LDAPAPIinfo structure.
This is either consistent or not with the library that is
linked against.  The LDAP_API_VERSION would be sufficient
to test link consistency.

If there is a mismatch, the application cannot determine
the API_VERSION number of the library.  I would recommend
eliminating the info_version field.  I would update the
note as follows:

Note that the ldapai_api_version field of the LDAPAPIInfo
MUST be set to the value of LDAP_API_VERSION.  This field
is checked by the ldap_get_option to ensure consistency.
If the version mismatched occurs, only the ldapi_api_version
field will be updated.

ldapai_api_version
	A number that matches that assigned to this API
	specification and should match the value of the
	LDAP_API_VERSION preprocessor symbol.  The caller
	MUST set this to LDAP_API_VERSION before calling
	ldap_get_option().

If there is good reason for the separate info_version field,
I would recommend requiring applications to set this field
with their version after checking for consistency.  This
allows the application to report to the user which versions
don't match.


Why is ldapai_api_version field of type int?

RFC65536 doesn't sound all that far away to me.  Also, I don't
think negative versions make much sense.  I would recommend
this field (and other version fields) be of a type
"unsigned int" or, at the very least, "unsigned int".


	Kurt