Most LDAP result codes are intended to be included in responses from the directory server to the client. However, there are also a number of possible client-side error conditions that may arise in the course of attempting to process operations, and it’s often convenient for LDAP APIs to allow developers to treat those client-side problems in the same way that they would treat an error response from the server.
There are a couple of specifications, draft-ietf-ldapext-ldap-c-api and draft-ietf-ldapext-ldap-java-api, that suggest APIs that C-based and Java-based libraries could expose to facilitate communication with an LDAP directory server. Although you can certainly debate how good the proposed APIs are (and there are many LDAP libraries that have chosen to expose different interfaces), they are at the very least useful because they define a number of result codes that can be used to represent client-side error conditions. This chapter explores these client-side result codes.
The serverDown result code doesn’t necessarily mean that the directory server has gone down. It merely indicates that an existing connection to the server is no longer valid. Some of the possible reasons for this result code include:
Regardless of the cause of the connection closure, the client will need to re-establish the connection, or establish a connection to a different server, before it can submit additional requests.
In the event that the directory server software closed the connection to the client (whether because it was being shut down or for some other reason), it may send a notice of disconnection unsolicited notification with a reason for the closure. Clients should watch for unsolicited notifications because if the server does send a notice of disconnection, it can help the client detect and react to certain connection closures more quickly.
The localError result code indicates that a problem occurred in the client for which none of the other client-side result codes is more appropriate. It’s the client-side equivalent of the other (80) result code, and it often means that an unexpected error has occurred in the library that the client is using to perform LDAP communication.
The encodingError result code indicates that a problem occurred while the client was attempting to encode a request to send to the directory server. This is not a commonly-used result code, since there are other result codes that are more appropriate for many of the conditions that can lead to encoding failures (for example, paramError (89) if there is a problem with one of the request parameters, or noMemory (90) if a problem occurs while attempting to allocate memory to hold the request).
The decodingError result code indicates that a problem occurred while the client was trying to decode a response received from the directory server. This generally means that either the server sent a malformed response or that the LDAP client library has a bug in it that prevents it from parsing a valid response.
The timeout result code indicates that the client did not receive an expected response to a request after waiting for some maximum length of time. Clients often provide some mechanism for configuring the maximum request time limit (whether global, connection-wide, or operation-specific), and if that time limit is reached without receiving a response, then the client will stop waiting for the response and report an error with this result code.
Optionally, the client may also send an abandon or cancel request to the directory server to indicate that it should stop processing the operation, but the client should not assume that the server will not complete the associated processing. If the request was for a write operation, then the requested change may still eventually be applied.
The authUnknown result code indicates that the client attempted to process some kind of authentication (presumably, a SASL mechanism) that the LDAP library does not recognize or support.
The filterError result code indicates that the LDAP client encountered an error related to a search filter. This usually means that the client encountered a problem while trying to parse a string as a search filter, but there may be other cases in which it may be used. For example, the matched values request control (described in RFC 3876) may be used to indicate that the server should only return values for a specified attribute that match a given filter, but not all filter types may be used in conjunction with this filter, and an attempt to include an unsupported filter type may trigger the filterError result code.
The userCanceled result code indicates that the operation was canceled by the client. It may have been interactively canceled (for example, by pressing Ctrl+C on a command-line tool, or clicking a cancel button in a graphical interface), or it may have been automatically generated by the client for some reason (for example, because another thread using the same connection sent an abandon request for the operation).
The paramError result code indicates that the client application or end user provided an inappropriate value for some parameter. This may be an invalid argument for a function or method, an invalid value provided for a command-line argument, illegal input into some form field, or any other area in which the LDAP client API may encounter and reject invalid data.
The noMemory result code indicates that the client encountered a memory-related problem during processing. It usually means that the client failed to allocate memory or its memory consumption would have exceeded some maximum allowed amount.
The connectError result code indicates that the client encountered a problem while attempting to establish a connection to the directory server. There are a number of potential reasons for this result code, including:
The connectError result code is different from the serverDown (81) result code in that connectError applies when trying to establish a new connection, while serverDown applies when the client detects that an already-established connection is no longer valid.
The notSupported result code indicates that the client attempted to perform some operation that is not supported by the LDAP client library. This result code should only be used if there isn’t another result code that is more specific to the condition at hand. For example, if the client is trying to use an unsupported SASL mechanism, then the authUnknown (86) result code is more appropriate. Or if the client doesn’t support StartTLS, then the tlsNotSupported (112) result code is more appropriate.
The controlNotFound result code indicates that a response received from the directory server did not include an expected response control. There are a number of request controls that, if successfully processed, should cause the result to include a corresponding response control. This result code may be used if the client expected a particular response control to be returned, but it wasn’t found in the response.
The noResultsReturned result code indicates that the client didn’t receive any expected response messages (in addition to the final response indicating that the operation has completed). This usually means that the client expected the server to return one or more entries in response to a search operation, but it could also apply to search result references or intermediate responses.
The moreResultsToReturn result code indicates that the client has received some of the responses for an operation, but that it also expects there are more responses available to be retrieved. The most likely use for this result code would be for the case in which the client attempts to retrieve only a portion of search results with the simple paged results control (RFC 2696) or the virtual list view request control (draft-ietf-ldapext-ldapv3-vlv). If the server returns all of the entries in the page of results, but the response indicates that there may be more pages that can be returned, the client may use this result code to indicate that. However, there may also be other uses for this result code involving a case in which the client expects that there may be search result entries, search result references, or intermediate responses.
The clientLoop result code indicates that the client has detected some kind of loop while processing results from the server. It usually applies when the client is trying to follow a referral (or a search result reference) and encounters a referral URL that it has already tried to follow.
The referralLimitExceeded result code indicates that the client has reached some limit when trying to follow referrals returned during processing. The two most likely reasons for this result code include:
The invalidResponse result code indicates that the client has received some kind of invalid response. It’s like a client-side version of the protocolError (2) result code, and can be used to indicate a couple of possible problems:
The ambiguousResponse result code indicates that the client received more than one final response message for the same request. You will probably never encounter this result code because it depends on two highly unlikely events: the server would have to send multiple final responses for the same request, and the client would have to recognize that it received multiple final responses for the same request. Even if the server were to incorrectly return multiple final responses to the same request, the client would probably just take the first one and ignore any subsequent final responses for that request.
The tlsNotSupported result code indicates that the client indicated a desire to begin TLS (Transport Layer Security, formerly known as the Secure Sockets Layer, or SSL) negotiation on a connection, but the client library does not support (or is not configured properly to handle) TLS encryption. This may be used when trying to establish a connection that is secured with TLS from the beginning, or when trying to use the StartTLS extended operation to add TLS security to an existing insecure connection.
The intermediateResponse result code indicates that the client received an intermediate response message from the server. Intermediate response messages were introduced in RFC 3771 and can be used to convey additional information in messages before the final response. This result code could be useful for client APIs that don’t provide some other means of handling intermediate responses (like an intermediate response listener) but still want to make them available to the client application.
The unknownType result code indicates that the client received a response with an unrecognized BER type. Every LDAP message has a message ID, a protocol operation, and an optional set of controls. The protocol operation element contains the bulk of the response, but it also has a BER type, which indicates what kind of response it is. The unknownType result code may be used if the client receives a response message with a protocol operation that has an unknown BER type.
| Previous: Other Server-Side Result Codes |