RE: C API: minor comments

["Anoop Anantha (Exchange)" <anoopa@Exchange.Microsoft.com>]

1] The description for LDAP_LOCAL_ERROR seems to suggest that no further
operations can be performed using the library since it is not in a
consistent state. I understand this is implementation specific but some
libraries might return this on a per operation basis and recover fully for
subsequent operations. I suggest it reads (if we decide to add
descriptions), for lack of a better description,

 - LDAP_LOCAL_ERROR (0x52)
	A generic error occured on this operation.

2] It might also help if we clarify that an application looking for
LDAP_RES_UNSOLICITED messages MAY get back messages of type
LDAP_RES_EXTENDED.

3] A client library MUST toss unsolicited responses with non-zero
messageIds. For unsolicited notifications with zero messageId, I would
suggest the default behavior be to toss them unless the app has explicitly
asked for them. We could provide an option to queue up these notifications
for applications which need them. If we don't do this, simple applications
which know nothing about unsolicited notifications will not process them and
the notifications may continue to queue up until the client runs out of
memory.


-Anoop Anantha

-----Original Message-----
From: Mark Wahl [mailto:M.Wahl@INNOSOFT.COM]
Sent: Monday, November 15, 1999 1:14 PM
To: mcs@netscape.com
Cc: M.Wahl@INNOSOFT.COM; howes@yahoo.com; Andy Herron (Exchange); Anoop
Anantha (Exchange); kurt@OpenLDAP.Org; ietf-ldapext@netscape.com
Subject: C API: minor comments



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.