Struct ldap3::LdapConn
[−]
[src]
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
[src]
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 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>
&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>
&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>
&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 HashSet
s 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>
&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>
&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>
&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>,
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
[src]
fn clone(&self) -> LdapConn
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more