With the exception of abandon and unbind operations (and operations prematurely terminated by an abandon or unbind), whenever a directory server completes processing for an LDAP request, it will return a response to the client with information about the result of that processing. The basic elements of an LDAP result are:

  • A result code. This indicates whether the operation was successful and why it might have failed. See the Result Code Reference page for a list of LDAP result codes and information about the conditions under which they may be returned.
  • An optional matched DN. If the operation failed because it targeted an entry that did not exist, then the matched DN element may contain the greatest portion of the target DN that does exist in the server. For example, if a client request targets nonexistent entry “uid=missing,ou=People,dc=example,dc=com” but the entry “ou=People,dc=example,dc=com” does exist in the server, then the result may include a matched DN value of “ou=People,dc=example,dc=com”.
  • An optional diagnostic message. This may provide additional information about the success or failure of the operation. If the operation failed, then this may provide a more detailed reason for that failure. Even if the operation succeeded, a diagnostic message may provide additional information that could be useful to the requester. In most cases, the diagnostic message is meant to be human-readable, but some servers may include parseable elements like numeric codes to help further clarify the result.
  • An optional set of referral URIs. If a server is unable to process a request but knows of other servers that might be able to do so (e.g., if a read-only server receives a write request and knows of servers that do support write operations), or if a server determines that a request targeting one entry should be re-issued to target a different entry, then that server may include a set of URIs in the result to provide the client re-try the operation in a manner that may succeed. Referral URIs are generally in the form of LDAP URLs, although the LDAP specification technically allows other types of URIs to be provided.

For certain types of operations, there may be additional fields in the response. These include:

  • For a SASL bind operation, the result may include an optional “server SASL credentials” element that allows the server to provide additional information to the client to use during bind processing. This may be used, for example, to provide the client with information needed for the next phase of a multi-stage bind, or to help negotiate secure communication between the client and the server.

  • For an extended operation, the result may include an optional response OID that identifies the type of response, and/or an encoded response value with additional information about the processing that was performed.

An LDAP result may also contain zero or more controls that provide additional information about the processing for that operation.

Search Result Entries and References

Whenever a search operation is complete, it will return a final result (including a result code and optional matched DN, diagnostic message, and referrals) called a “search result done” message. However, there are two additional types of result messages that may be returned for a search operation:

  • If the search criteria matches any entries, then each will be returned in a separate “search result entry” message. Each search result entry message includes the DN of the matching entry and zero or more of the attributes contained in that entry.
  • If the server believes that any portion of the search may also match entries in other servers, then zero or more “search result reference” messages may be returned with referral URIs indicating where the client may continue the search.

See The LDAP Search Operation for more information about search operation processing.

Intermediate Responses

While search requests can return any number of search result entry and search result reference messages before the search result done that signifies the end of the search, other types of requests typically yield only a single result message. However, it may occasionally be useful for an operation to be able to return other types of messages before the operation has completed. Intermediate response messages may address this by allowing arbitrary messages to be returned to the client before the final result message for that operation. Each intermediate response message may have an optional OID to identify the type of intermediate response message, and/or an optional value with the encoded content of the response.

Note that intermediate response messages should not be returned for arbitrary requests. Rather, intermediate messages should only be returned by the server if the client does something to indicates that they are acceptable. This would generally come in the form of an extended request for which it is known that intermediate responses may be returned, although it is possible that intermediate response messages may be triggered for other types of operations through a request control.

Unsolicited Notifications

Most of the time, whenever an LDAP server sends a message to a client, it is in response to a request from that client. However, there may be cases in which the server needs to send a message to a client that is independent of any request from that client. For example, if an LDAP server is about to close a client connection (e.g., because the server is shutting down, or because the connection has been unused for too long), then it would be nice to send a message to the client indicating that it’s about to close the connection. This can be accomplished with an unsolicited notification.

An unsolicited notification is a special type of extended result message in which the message ID is always zero (rather than the message ID of a corresponding request), and for which the response OID element will always be present and should identify the type of notification that is represented.

Some types of unsolicited notification messages that may be used include:

  • The notice of disconnection (OID 1.3.6.1.4.1.1466.20036) may be used to indicate that the server is about to terminate a client connection.
  • The aborted transaction notice (OID 1.3.6.1.1.21.4) may be used to indicate that the server has aborted an LDAP transaction that had been begun by the client but had not been completed.