Struct ldap3::LdapConn

pub struct LdapConn { /* fields omitted */ }

Handle for LDAP operations.

A connection is opened by calling new(). If successful, this returns a handle which is used for all subsequent operations on that connection. Authenticating the user can be done with simple_bind() or sasl_external_bind(); the latter is available on Unix-like systems, and can only work on Unix domain socket connections.

Some connections need additional parameters, and providing separate functions to initialize them, singly or in combination, would result in a confusing and cumbersome interface. Instead, connection initialization is optimized for the expected most frequent usage, and additional customization is delegated to LdapConnBuilder.

All LDAP operations allow attaching a series of request controls, which augment or modify the operation. Controls are attached by calling with_controls() on the handle, and using the result to call another modifier or the operation itself. A timeout can be imposed on an operation by calling with_timeout() on the handle before invoking the operation.

The Search operation has many parameters, most of which are infrequently used. Those parameters can be specified by constructing a SearchOptions structure and passing it to with_search_options() called on the handle. This method can be combined with with_controls() and with_timeout(), described above.

There are two ways to invoke a search. The first, using search(), returns all result entries in a single vector, which works best if it's known that the result set will be limited. The other way uses streaming_search(), which accepts the same parameters, but returns a handle which must be used to obtain result entries one by one.

As a rule, operations return LdapResult, a structure of result components. The most important element of LdapResult is the result code, a numeric value indicating the outcome of the operation. This structure also contains the possibly empty vector of response controls, which are not directly usable, but must be additionally parsed by the driver- or user-supplied code.

Methods

impl LdapConn

fn new(url: &str) -> Result<Self>

Open a connection to an LDAP server specified by url. For the details of supported URL formats, see LdapConnAsync::new().

fn simple_bind(&self, bind_dn: &str, bind_pw: &str) -> Result<LdapResult>

Do a simple Bind with the provided DN (bind_dn) and password (bind_pw).

fn sasl_external_bind(&self) -> Result<LdapResult>

Do a SASL EXTERNAL bind on the connection. Presently, it only makes sense on Unix domain socket connections. The bind is made with the hardcoded empty authzId value.

fn with_search_options(&self, opts: SearchOptions) -> &Self

Use the provided SearchOptions with the next Search operation, which can be invoked directly on the result of this method. If this method is used in combination with a non-Search operation, the provided options will be silently discarded when the operation is invoked.

The Search operation can be invoked on the result of this method.

fn with_controls<V: IntoRawControlVec>(&self, ctrls: V) -> &Self

Pass the provided request control(s) to the next LDAP operation. Controls can be constructed by instantiating structs in the controls module, and converted to the form needed by this method by calling into() on the instances. Alternatively, a control struct may offer a constructor which will produce a RawControl instance itself. See the module-level documentation for the list of directly supported controls and procedures for defining custom controls.

This method accepts either a single RawControl or a Vec of them, in order to make the call site less noisy, since it's expected that passing a single control will comprise the majority of uses.

The desired operation can be invoked on the result of this method.

fn with_timeout(&self, duration: Duration) -> &Self

Perform the next operation with the timeout specified in duration. See the tokio-core documentation for the Timeout struct for timer limitations. The LDAP Search operation consists of an indeterminate number of Entry/Referral replies; the timer is reset for each reply.

If the timeout occurs, the operation will return an io::Error wrapping the string "timeout". The connection remains usable for subsequent operations.

The desired operation can be invoked on the result of this method.

fn search<S: AsRef<str>>(
    &self,
    base: &str,
    scope: Scope,
    filter: &str,
    attrs: Vec<S>
) -> Result<SearchResult>

Perform a Search with the given base DN (base), scope, filter, and the list of attributes to be returned (attrs). If attrs is empty, or if it contains a special name * (asterisk), return all (user) attributes. Requesting a special name + (plus sign) will return all operational attributes. Include both * and + in order to return all attributes of an entry.

The returned structure wraps the vector of result entries and the overall result of the operation. Entries are not directly usable, and must be parsed by SearchEntry::construct().

This method should be used if it's known that the result set won't be large. For other situations, one can use streaming_search().

fn streaming_search<S: AsRef<str>>(
    &self,
    base: &str,
    scope: Scope,
    filter: &str,
    attrs: Vec<S>
) -> Result<EntryStream>

Perform a Search, but unlike search() (q.v., also for the parameters), which returns all results at once, return a handle which will be used for retrieving entries one by one. See EntryStream for the explanation of the protocol which must be adhered to in this case.

fn add<S: AsRef<str> + Eq + Hash>(
    &self,
    dn: &str,
    attrs: Vec<(S, HashSet<S>)>
) -> Result<LdapResult>

Add an entry named by dn, with the list of attributes and their values given in attrs. None of the HashSets of values for an attribute may be empty.

fn delete(&self, dn: &str) -> Result<LdapResult>

Delete an entry named by dn.

fn modify<S: AsRef<str> + Eq + Hash>(
    &self,
    dn: &str,
    mods: Vec<Mod<S>>
) -> Result<LdapResult>

Modify an entry named by dn by sequentially applying the modifications given by mods. See the Mod documentation for the description of possible values.

fn modifydn(
    &self,
    dn: &str,
    rdn: &str,
    delete_old: bool,
    new_sup: Option<&str>
) -> Result<LdapResult>

Rename and/or move an entry named by dn. The new name is given by rdn. If delete_old is true, delete the previous value of the naming attribute from the entry. If the entry is to be moved elsewhere in the DIT, new_sup gives the new superior entry where the moved entry will be anchored.

fn unbind(&self) -> Result<()>

Terminate the connection to the server.

fn compare<B: AsRef<[u8]>>(
    &self,
    dn: &str,
    attr: &str,
    val: B
) -> Result<CompareResult>

Compare the value(s) of the attribute attr within an entry named by dn with the value val. If any of the values is identical to the provided one, return result code 5 (compareTrue), otherwise return result code 6 (compareFalse). If access control rules on the server disallow comparison, another result code will be used to indicate an error.

fn extended<E>(&self, exop: E) -> Result<ExopResult> where
    E: Into<Exop>, 

Perform an Extended operation given by exop. Extended operations are defined in the exop module. See the module-level documentation for the list of extended operations supported by this library and procedures for defining custom exops.

Trait Implementations

impl Clone for LdapConn

fn clone(&self) -> LdapConn

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.