Subject: C API: minor comments

From: Mark Wahl <[email-masked]>
Date: Mon, 15 Nov 1999 15:13:36 -0600

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.  

In section 13 I suggest we add after the first paragraph.

ldap_result() can also be used to obtain unsolicited notifications from
the server.  

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.

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:

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

 - LDAP_ENCODING_ERROR (0x53)
	
 - LDAP_DECODING_ERROR (0x54)

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

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

 - LDAP_NO_MEMORY (0x5a)

 - LDAP_CONNECT_ERROR (0x5b)

 - LDAP_NOT_SUPPORTED (0x5c)

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

 - LDAP_NO_RESULTS_RETURNED (0x5e)
	Reserved.

 - LDAP_MORE_RESULTS_TO_RETURN (0x5f)
	Reserved.

 - LDAP_CLIENT_LOOP (0x60)
	Reserved.

 - LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)

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?  On
 a related note, what does the client library do if it receives a response
 for which there is no matching request?  

Mark Wahl, Directory Product Architect
Innosoft International, Inc.

---

From: Mark Smith <[email-masked]>
Date: Tue, 16 Nov 1999 15:27:35 -0500

> be able to easily distinguish client-generated requests and unsolicited

I commented on this in a separate message.

> ldap_result() can also be used to obtain unsolicited notifications from

Okay.

> as well as a search result done, and so these belong in the chain.

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

> actually used in this draft:

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

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

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

>         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_MORE_RESULTS_TO_RETURN (0x5f)

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

>  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

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?