h2. Message

The *Messages* are used to communicate with the *LDAP* server. We send requests, and receive responses. Both [#Request]s and [#Response]s are message.

In this chapter, we will describe the *Messages* elements, and how to use them.

h3. Existing messages
We have 10 possible requests, and 11 possible responses, with one special response (*[#IntermediateResponse]*). This special response can be used for any request, assuming that the client has specified a control that requires such a response, and is able to handle it.

*[#IntermediateResponse]s* are very specific, and a user should not expect to get it, except in some rare occasions, and it's very dependent o the Server the user is contacting. An example of *[#IntermediateResponse]* usage is when the server is implementing the [*Syncrepl|http://www.rfc-editor.org/rfc/rfc4533.txt] protocol

Here is a list of all the existing requests and their associated responses :

|| Request || Responses ||
| [#AbandonRequest] | none ([#IntermediateResponse]) | 
| [#AddRequest] | [#AddResponse] ([#IntermediateResponse]) |
| [#BindRequest] | [#BindResponse] ([#IntermediateResponse]) |
| [#CompareRequest] | [#CompareResponse] ([#IntermediateResponse]) |
| [#DelRequest] | [#DelResponse] ([#IntermediateResponse]) |
| [#ExtendedRequest] | [#ExtendedResponse], [#IntermediateResponse] |
| [#ModifyRequest] | [#ModifyResponse] ([#IntermediateResponse]) |
| [#ModifyDNRequest] | [#ModifyDNResponse] (IntermediateResponse]) |
| [#SearchRequest] | [#SearchResultEntry], [#SearchResultDone], [#SearchResultReference] |
| [#UnbindRequest] | None ([#IntermediateResponse]) |

h3. Requests
Here is the description of each request a user can send.

h4. AbandonRequest

The *AbandonRequest* is quite simple. It takes just one parameter, the *ID* of the message we want to abandon. Obviously, you need to know what this message *ID* is, and every message has an *ID* which can be retrieved by calling the _getMessageId()_ method.

Also note that only requests can be abandoned, that if you take a response's *ID*, and use it in the *AbandonRequest*, you will abandon the associated request (which makes sense only for *SearchResultEntry*, *SearchReference* and *IntermediateResponse*), and that all requests can't be abandoned.

h4. Using the AbandonRequest

{code:java}
        ... 
        // We have added 100 entries in the serverbefore doing a search
        // Launch the search now
        Cursor<Response> cursor = connection.search( new Dn( "ou=system" ), "(cn=*)", SearchScope.ONELEVEL, "*" );

        Response searchResponse = null;
        int count = 0;

        // Iterate over the results
        while ( cursor.next() )
        {
            searchResponse = cursor.get();
            count++;

            if ( count > 10 )
            {
                // Abandon the search request when we have received the 10th entry
                AbandonRequest abandon = new AbandonRequestImpl( searchResponse.getMessageId() );
                connection.abandon( abandon );
            }
        }
        
        cursor.close();

        System.out.println( "Responses received / expected : " + count + "/" + numEntries );
        ...
{code}

This code produces this output :

{code:java}
Responses received / expected : 11/100
{code}

As we can see, the _cursor_next()_ call won't return any other entry as soon as the _abandonRequest_ is received by the server.

h4. BindRequest
The *BindRequest* is used to get authenticated on a *LDAP* server. Note that it has nothing to do with the connection itself : you can be connected, and even request the server, without being bound. 

Once you are bound, you have a session with your credentials, and the server might behave accordingly to your set of authorizations.

We have two kind of authentication, each of them being established through a *BindRequest* :
* Simple authentication
* SASL authentication

h5. Simple Bind

TODO : complete the description

h5. SASL Bind

A *SASL* bind can be a complex operation, with more than one exchange between the client and the server. One can feed the *BindRequest* data structure and send it to the server, but this is not really an option, as the following exchanges have to be handled.

We provide some dedicated classes to manage many of the *SASL* bind :

|| Mechanism || class ||
| *CRAM-MD5* | *[DIRAPI:CramMd5Request]* |
| *DIGEST-MD5* | *[DIRAPI:DigestMd5Request]* |
| *GSSAPI* | *[DIRAPI:GssApiRequest]* |


h4. AddRequest
h4. BindRequest
h4. CompareRequest
h4. DelRequest
h4. ExtendedRequest
h4. ModifyRequest
h4. ModifyDNRequest
h4. SearchRequest
h4. UnbindRequest

h3. Responses
Here is the description of each response a user can receive.

h4. AddResponse
h4. BindResponse
h4. CompareResponse
h4. DelResponse
h4. ExtendedResponse
h4. ModifyResponse
h4. ModifyDNResponse
h4. SearchResultEntry
h4. SearchResultReference
h4. SearchResultDone
h4. IntermediateResponse