Struct ldap3::EntryStream
[−]
[src]
pub struct EntryStream { /* fields omitted */ }
Handle for obtaining a stream of search results.
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 must either be driven to the end by
repeatedly calling next()
until it returns Ok(None)
or an error. If the stream is cancelled by calling abandon()
,
next()
will return Ok(None)
.
After regular termination or cancellation, the overall result of the search
must be retrieved by calling result()
on the stream handle.
Methods
impl EntryStream
[src]
fn next(&mut self) -> Result<Option<ResultEntry>>
Retrieve the next search result. Ok(None)
signals the end of the
stream.
fn result(&mut self) -> Result<LdapResult>
Retrieve the overall result of the search. This method must be
called after the stream has terminated by returning Ok(None)
or
an error, although the latter case is guaranteed to also return an
error. If this protocol is not followed, the method will hang.
fn abandon(&mut self) -> Result<()>
Abandon the search by signalling the underlying asynchronous stream to
send the Abandon operation to the server. If the operation is successfully sent,
the next invocation of EntryStream::next()
will return Ok(None)
, indicating
the end of the stream. The overall result of the search will have an error code
indicating that the operation has been abandoned.
This method can return an error if there is a problem with retrieving the channel from the stream instance or sending the signal over the channel.