% $Id: ldap-async.tex,v 1.2 2003/01/23 23:00:56 stroeder Exp $

\section{\module{ldap.async} ---
  Framework for stream-processing of large search results }

\declaremodule{standard}{ldap.async}

% Author of the module code;
\moduleauthor{Michael Str\"oder}{python-ldap-dev@lists.sourceforge.net}
% Author of the documentation,
\sectionauthor{Michael Str\"oder}{michael@stroeder.com}

\modulesynopsis{Framework for stream-processing of large search results.}

\subsection{Examples for ldap.async \label{ldap.async-example}}

\subsubsection{Using ldap.async.List \label{ldap.async-example.List}}

This example demonstrates how to use class ldap.async.List for
retrieving partial search results even though the exception
ldap.SIZELIMIT_EXCEEDED was raised because a server side limit was hit.

\begin{verbatim}
import sys,ldap,ldap.async

s = ldap.async.List(
  ldap.initialize('ldap://localhost'),
)

s.startSearch(
  'dc=stroeder,dc=com',
  ldap.SCOPE_SUBTREE,
  '(objectClass=*)',
)

try:
  partial = s.processResults()
except ldap.SIZELIMIT_EXCEEDED:
  sys.stderr.write('Warning: Server-side size limit exceeded.\n')
else:
  if partial:
    sys.stderr.write('Warning: Only partial results received.\n')

sys.stdout.write(
  '%d results received.\n' % (
    len(s.allResults)
  )
)
\end{verbatim}

\subsubsection{Using ldap.async.LDIFWriter \label{ldap.async-example.LDIFWriter}}

This example demonstrates how to use class ldap.async.LDIFWriter
for writing search results as LDIF to stdout.

\begin{verbatim}
import sys,ldap,ldap.async

s = ldap.async.LDIFWriter(
  ldap.initialize('ldap://localhost:1390'),
  sys.stdout
)

s.startSearch(
  'dc=stroeder,dc=com',
  ldap.SCOPE_SUBTREE,
  '(objectClass=*)',
)

try:
  partial = s.processResults()
except ldap.SIZELIMIT_EXCEEDED:
  sys.stderr.write('Warning: Server-side size limit exceeded.\n')
else:
  if partial:
    sys.stderr.write('Warning: Only partial results received.\n')

sys.stderr.write(
  '%d results received.\n' % (
    s.endResultBreak-s.beginResultsDropped
  )
)
\end{verbatim}

