Struct ldap3::SearchStream
source · pub struct SearchStream<'a, S, A> {
pub res: Option<LdapResult>,
/* private fields */
}
Expand description
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§
source§impl<'a, S, A> SearchStream<'a, S, A>where
S: AsRef<str> + Send + Sync + 'a,
A: AsRef<[S]> + Send + Sync + 'a,
impl<'a, S, A> SearchStream<'a, S, A>where S: AsRef<str> + Send + Sync + 'a, A: AsRef<[S]> + Send + Sync + 'a,
sourcepub async fn start(
&mut self,
base: &str,
scope: Scope,
filter: &str,
attrs: A
) -> Result<()>
pub async fn start( &mut self, base: &str, scope: Scope, filter: &str, attrs: A ) -> 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(())
.
sourcepub async fn next(&mut self) -> Result<Option<ResultEntry>>
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.
sourcepub async fn finish(&mut self) -> LdapResult
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.
sourcepub async fn adapter_chain_tail(
&mut self
) -> Vec<Box<dyn Adapter<'a, S, A> + 'a>>
pub async fn adapter_chain_tail( &mut self ) -> Vec<Box<dyn Adapter<'a, S, A> + '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.
sourcepub fn state(&self) -> StreamState
pub fn state(&self) -> StreamState
Return the current state of the stream.
sourcepub fn ldap_handle(&mut self) -> &mut Ldap
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.