Struct ldap3::SearchStream

pub struct SearchStream<'a, S> {
    pub res: Option<LdapResult>,
    // some fields omitted
}

Asynchronous handle for obtaining a stream of search results. *

User code can't construct a stream directly, but only by using streaming_search() or streaming_search_with() on an Ldap handle.

A streaming search should be used for situations where the expected size of result entries varies considerably between searches, and/or can rise above a few tens to hundreds of KB. This is more of a concern for a long-lived process which is expected to have a predictable memory footprint (i.e., a server), but can also help with one-off searches if the result set is in the tens of thounsands of entries.

Once initiated, a streaming search is driven to the end by repeatedly calling next() until it returns Ok(None) or an error. Then, a call to finish() will return the overall result of the search. Calling finish() earlier will terminate search result processing in the client; it is the user's responsibility to inform the server that the operation has been terminated by performing an Abandon or a Cancel operation.

There are two variants of SearchStream, direct and adapted. The former calls stream operations directly, while the latter first passes through a chain of adapters given at the time of stream creation.

Fields

res: Option<LdapResult>

Implementations

impl<'a, S> SearchStream<'a, S> where
    S: AsRef<str> + Send + Sync + 'a, 

pub async fn start<'_, '_, '_>(
    &'_ mut self,
    base: &'_ str,
    scope: Scope,
    filter: &'_ str,
    attrs: Vec<S>
) -> Result<()>

Initialize a streaming Search.

This method exists as an initialization point for search adapters, and is not meant for calling from regular user code. It must be public for user-defined adapters to work, but explicitly calling it on a SearchStream handle is a no-op: it will immediately return Ok(()).

pub async fn next<'_>(&'_ mut self) -> Result<Option<ResultEntry>>

Fetch the next item from the result stream after executing the adapter chain if there is one.

Returns Ok(None) at the end of the stream.

pub async fn finish<'_>(&'_ mut self) -> LdapResult

Return the overall result of the Search.

This method can be called at any time. If the stream has been read to the end, the return value will be the actual result returned by the server. Otherwise, a synthetic cancellation result is returned, and it's the user's responsibility to abandon or cancel the operation on the server.

If the Search is adapted, this method will first execute the finish() methods of all adapters in the chain.

pub async fn adapter_chain_tail<'_>(
    &'_ mut self
) -> Vec<Box<dyn Adapter<'a, S> + 'a>>

Return a vector of the remaining adapters in the chain at the point of the method call. Adapter instances are cloned and collected into the resulting vector. The purpose of this method is to enable uniformly configured Search calls on the connections newly opened in an adapter.

pub fn state(&self) -> StreamState

Return the current state of the stream.

pub fn ldap_handle(&mut self) -> &mut Ldap

Return the Ldap handle of the stream.

Mutating the public elements of Ldap through the obtained handle can't affect the current operation except in the start() chain of an adapted streaming Search, intentionally so.

Trait Implementations

impl<'a, S: Debug> Debug for SearchStream<'a, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.