Re: C API: minor comments

[Mark Smith <mcs@netscape.com>]

Mark Wahl wrote:
> 
> Two last call comments on the C API regarding unsolicited notifications:
> 
> I recommend that in section 5 we add:
> 
> Implementations of the API SHOULD begin numbering messages with 1, to
> be able to easily distinguish client-generated requests and unsolicited
> notifications.

I commented on this in a separate message.


> 
> In section 13 I suggest we add after the first paragraph.
> 
> ldap_result() can also be used to obtain unsolicited notifications from
> the server.

Okay.


> 
> In section 15 please note that a search can return extended responses
> as well as a search result done, and so these belong in the chain.

Good catch -- I forgot that searches MAY return extended responses.


> 
> I think it would be helpful if section 10 described what the meanings
> of errors 0x51 through 0x61 are.  Of these only LDAP_PARAM_ERROR is
> actually used in this draft:

I agree -- we should add some explanatory text for the API error codes.


> 
>  - LDAP_SERVER_DOWN (0x51)
>         The client library could not send the request to the server as the
>         connection has been lost.  The client can use ldap_result to obtain
>         any outstanding results left on this connection, but cannot issue
>         any new requests.  Once all the results have been obtained the client
>         SHOULD use ldap_unbind() to complete the disconnection process.
> 
>  - LDAP_LOCAL_ERROR (0x52)
>         The client library is in an inconsistent state.

What do you mean by "inconsistent state?"  I'd rather say something
like:

          The API implementation experienced an internal error that
          prevented it from completing the requested action.  It is
          RECOMMENDED that API implementations use this error code
          sparingly.
          
> 
>  - LDAP_ENCODING_ERROR (0x53)

Suggested text:

          An error occurred while encoding an LDAP message.

> 
>  - LDAP_DECODING_ERROR (0x54)

Suggested text:

          An error occurred while decoding an LDAP message.

> 
>  - LDAP_TIMEOUT (0x55)
>         Return code from ldap_search_st().

Note that ldap_search_ext_s() can also generate this error code.  My
suggested text:

          A local time limit was exceeded.  For example, if a non-zero
          timeout is passed to ldap_search_ext_s() and the timeout
          passes without a result being returned, ldap_search_ext_s()
          should return LDAP_TIMEOUT.
 
> 
>  - LDAP_AUTH_UNKNOWN (0x56)
>         Unsupported authmethod flag to ldap_bind() or ldap_bind_s().
> 
>  - LDAP_FILTER_ERROR (0x57)
>         Filter parameter to search is not correctly written.
> 
>  - LDAP_USER_CANCELLED (0x58)
>         Reserved.
> 
>  - LDAP_PARAM_ERROR (0x59)

Suggested text:

           An invalid value was passed to an API function.

> 
>  - LDAP_NO_MEMORY (0x5a)

Suggested text:

           A memory allocation failure occurred.

> 
>  - LDAP_CONNECT_ERROR (0x5b)

Suggested text:

          The API implementation was unable to open a connection to
          an LDAP server.

> 
>  - LDAP_NOT_SUPPORTED (0x5c)

Suggested text:

          The caller of the API tried to use an LDAPv3-only API feature
          or function call when the protocol version (set with
          LDAP_OPT_PROTOCOL_VERSION) was 2.

> 
>  - LDAP_CONTROL_NOT_FOUND (0x5d)
>         Used by extensions to this API.

I would add:

          ... to indicate that the requested control was not present
          in a list of controls such as those returned by a server.

> 
>  - LDAP_NO_RESULTS_RETURNED (0x5e)
>         Reserved.
> 
>  - LDAP_MORE_RESULTS_TO_RETURN (0x5f)
>         Reserved.

I would say instead:

          Returned by ldap_parse_result() when additional result
          messages are present in the chain of messages represented
          by the "res" parameter.

> 
>  - LDAP_CLIENT_LOOP (0x60)
>         Reserved.
> 
>  - LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)

This one should also be marked "reserved" or perhaps clarified with text
like this if we leave the mentions of automatic referral chasing in the
document:

          A API-enforced limit on the number of nested referrals that
can
          be present has been exceeded.


> 
> Open question on unsolicited notification:
> 
>  1. Do unsolicited notifications queue up in the client library until the
>  client asks for them with ldap_result() or an ldap_unbind() occurs?


I say yes, unsolicited notifications should queue up until the caller of
the API asks for them (or until ldap_unbind is called).  We should
clarify this by adding text to section 13 where ldap_result() is
discussed.


>  On
>  a related note, what does the client library do if it receives a response
>  for which there is no matching request?

Except for unsolicited notifications (those that have a zero message
ID), I think the API implementation should be allowed to discard such
responses.  But I don't think this needs to be a MUST.  I might even
leave it as a MAY like so:

     With the notable exception of unsolicited notifications which
     always have a message ID or zero, API implementations MAY
     discard responses for which no matching request was sent by
     the implementation (that is, when the message ID is unknown).

It seems to me that if a response is received with an unknown but
non-zero message ID, this would always be due to a bug in the server.

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