LdapConnection class

Connection to perform LDAP operations on an LDAP server.

Properties

An LdapConnection is defined by the network connection and the LDAP binding.

The network connection is determined by the hostname, whether SSL/TLS is used or not, and the port number.

The badCertHandler is a callback function to process bad certificates (if encountered when attempting to establish a TLS/SSL connection). The callback function should return true to accept the certificate (and the security consequences of doing so), or false to reject it. If no certificate callback is provided, the default behaviour is to throw the LdapCertificateException if a bad certificate is encountered.

Connection management

State

The state of the LdapConnection can be determined by examining its state.

Disconnections

An open network connection can be disconnected by external causes, which are outside the control of the application. For example, disconnections occur when: the LDAP server times out the connection, the LDAP server is re-started, or network errors causes the connection to be dropped. See the LdapConnectionPool to handle dropped connections. etc.

Results

All of the above LDAP operation methods return a Future to an LdapResult.

The LdapResult contains a resultCode value that will always be either ResultCode.OK, ResultCode.COMPARE_FALSE or ResultCode.COMPARE_TRUE. The last two values only occur when performing a compare operation. For all other operations, the resultCode does not carry useful information, because errors will cause an exception to be thrown.

Exceptions

This package defines exceptions that are all subclasses of the abstract LdapResultException class.

In automatic mode, all of them can also throw any of the exceptions the open or bind methods can throw.

In manual mode, all of them can also throw StateError if the connection is closed or disconnected. Also, all of them except bind can also throw StateError if it is in manual mode and the state is bindRequired.

All of the above LDAP operation methods can also thrown exceptions specific to their operation. See the documentation of specific methods for some of these, or the classes that implement the LdapException. The abstract LdapResultException is an abstract class that is a base class of exceptions relating to the result of LDAP operations.

Standard

Asynchronicity

All these LDAP operations are asynchronous. A program does not need to wait for the current operation to complete before sending the next one.

Special care must be taken with the bind operation in manual mode. If subsequent operations are to be performed with those LDAP bindings, the application should wait for the Future returned by bind to complete before performing the next operation. In automatic mode, this ordering is always enforced (when bind is explicitly called, and when the LDAP BIND request is automatically sent).

LDAP return results are matched to requests using a message id. They are not guaranteed to be returned in the same order they were sent.

There is currently no flow control. Messages will be queued and sent to the LDAP server as fast as possible. Messages are sent in in the order in which they are queued.

Closing

When finished with the LdapConnection, close it.

Inheritance

Constructors

LdapConnection({String host = 'localhost', bool ssl = false, int port = Ldap.PORT_LDAP, String bindDN = '', String password = '', BadCertHandlerType badCertificateHandler = defaultBadCertHandler, SecurityContext? context})
Constructor for an LDAP connection to an LDAP directory server.
LdapConnection.copy(LdapConnection c)

Properties

badCertHandler → BadCertHandlerType
no setter
bindDN → String
The distinguished name used when a BIND request is sent.
no setter
connectionId → int
Return the unique connection id for this connection TODO: How does this work with isolates?
no setter
connectionInfo ↔ ConnectionInfo
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
host → String
Host name of the LDAP directory server.
no setter
isBound → bool
no setter
isReady → bool
no setter
isSSL → bool
Indicates the protocol being used (LDAP over SSL or plain LDAP)
no setter
port → int
Port number of the LDAP directory server.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state ↔ ConnectionState
getter/setter pair
url → String
URL representation of the LDAP connection's host and port.
no setter

Methods

abandonRequest({required int messageId}) → void
add(String dn, Map<String, dynamic> attrs) → Future<LdapResult>
Performs an LDAP add operation.
override
bind({String? DN, String? password}) → Future<LdapResult>
Performs an LDAP BIND operation.
override
close() → Future<void>
Closes the connection to the LDAP directory server.
compare(String dn, String attrName, String attrValue) → Future<LdapResult>
Performs an LDAP compare operation.
override
delete(String dn) → Future<LdapResult>
Performs an LDAP delete operation.
override
modify(String dn, List<Modification> mods) → Future<LdapResult>
Performs an LDAP modify operation.
override
modifyDN(String dn, String rdn, {bool deleteOldRDN = true, String? newSuperior}) → Future<LdapResult>
Performs an LDAP modifyDN operation.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
open() → Future<void>
Opens the network connection to the LDAP directory server.
query(String baseDN, String query, List<String> attributes, {int scope = SearchScope.SUB_LEVEL, int sizeLimit = 0, List<Control> controls = const []}) → Future<SearchResult>
Like the search method, but the filter is constructed using the query string. See https://tools.ietf.org/html/rfc2254
inherited
reconnect() → Future<void>
Reopen the connection, and rebind with the last known bind credentiuals
Performs an LDAP search operation.
override
toString() → String
A string representation of this object.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

defaultBadCertHandler(X509Certificate cert) → bool
Default bad certificate handler.