File: ldap.tex

package info (click to toggle)
python-ldap-doc 2.3-1
  • links: PTS
  • area: contrib
  • in suites: lenny
  • size: 200 kB
  • ctags: 121
  • sloc: python: 661; makefile: 44
file content (1014 lines) | stat: -rw-r--r-- 36,340 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
% $Id: ldap.tex,v 1.30 2007/03/27 22:31:51 stroeder Exp $

% ==== 1. ====
% The section prologue.  Give the section a title and provide some
% meta-information.  References to the module should use
% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
% appropriate.

\section{\module{ldap} --- LDAP library interface module}

\declaremodule{extension}{ldap}		% not standard, in C

\platform{UNIX,Windows}

% 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}

% Leave at least one blank line after this, to simplify ad-hoc tools
% that are sometimes used to massage these files.
\modulesynopsis{Access to an underlying LDAP C library.}

% ==== 2. ====
% Give a short overview of what the module does.
% If it is platform specific, mention this.
% Mention other important restrictions or general operating principles.

This module provides access to the LDAP
(Lightweight Directory Access Protocol) \C\ API implemented
in OpenLDAP 2.3 or newer.
It is similar to the C API, with the notable differences
that lists are manipulated via Python
list operations and errors appear as exceptions.

For far more detailed information on the \C\ interface, 
please see the (expired) draft-ietf-ldapext-ldap-c-api-04.

This documentation is current for the Python LDAP module, version
$\version$.
Source and binaries are available from
\url{http://python-ldap.sourceforge.net/}.

% ==== 3. ====
% List the public functions defined by the module.  Begin with a
% standard phrase.  You may also list the exceptions and other data
% items defined in the module, insofar as they are important for the
% user.

\subsection{Functions}

The \module{ldap} module defines the following functions:

% ---- 3.1. ----
% For each function, use a ``funcdesc'' block.  This has exactly two
% parameters (each parameters is contained in a set of curly braces):
% the first parameter is the function name (this automatically
% generates an index entry); the second parameter is the function's
% argument list.  If there are no arguments, use an empty pair of
% curly braces.  If there is more than one argument, separate the
% arguments with backslash-comma.  Optional parts of the parameter
% list are contained in \optional{...} (this generates a set of square
% brackets around its parameter).  Arguments are automatically set in
% italics in the parameter list.  Each argument should be mentioned at
% least once in the description; each usage (even inside \code{...})
% should be enclosed in \var{...}.

\begin{funcdesc}{initialize}{uri} % -> LDAPObject
  Opens a new connection with an LDAP server, and return an LDAP object
  (see \ref{ldap-objects}) used to perform operations on that server.
  Parameter \var{uri} has to be a valid LDAP URL.
  \begin{seealso}
  \seerfc{4516}{Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator}{}
  \end{seealso}
\end{funcdesc}

\begin{funcdesc}{open}{host \optional{, port=\constant{PORT}}} % -> LDAPObject
  Opens a new connection with an LDAP server, and return an LDAP object
  (see \ref{ldap-objects}) used to perform operations on that server.
  \var{host} is a string containing solely the host name. \var{port}
  is an integer specifying the port where the LDAP server is
  listening (default is 389).
  Note: Using this function is deprecated.
\end{funcdesc}

\begin{funcdesc}{get_option}{option} % -> None
  This function returns the value of the global option
  specified by \var{option}.
\end{funcdesc}

\begin{funcdesc}{set_option}{option, invalue} % -> None
  This function sets the value of the global option
  specified by \var{option} to \var{invalue}.
\end{funcdesc}


% ---- 3.2. ----
% Data items are described using a ``datadesc'' block.  This has only
% one parameter: the item's name.

\subsection{Constants}

The module defines various constants.

\subsubsection{General}

\begin{datadesc}{PORT}
  The assigned TCP port number (389) that LDAP servers listen on.
\end{datadesc}

\begin{datadesc}{SASL_AVAIL}
  Boolean flag indicating whether python-ldap was built
  with support for SASL (Cyrus-SASL).
\end{datadesc}

\begin{datadesc}{TLS_AVAIL}
  Boolean flag indicating whether python-ldap was built
  with support for SSL/TLS (OpenSSL).
\end{datadesc}

\subsubsection{Options}

For use with functions and method set_option() and get_option() the
following option identifiers are defined as constants:

\begin{datadesc}{OPT_API_FEATURE_INFO}
\end{datadesc}

\begin{datadesc}{OPT_API_INFO}
\end{datadesc}

\begin{datadesc}{OPT_CLIENT_CONTROLS}
\end{datadesc}

\begin{datadesc}{OPT_DEBUG_LEVEL}
\end{datadesc}

\begin{datadesc}{OPT_DEREF}
\end{datadesc}

\begin{datadesc}{OPT_ERROR_STRING}
\end{datadesc}

\begin{datadesc}{OPT_HOST_NAME}
\end{datadesc}

\begin{datadesc}{OPT_MATCHED_DN}
\end{datadesc}

\begin{datadesc}{OPT_NETWORK_TIMEOUT}
\end{datadesc}

\begin{datadesc}{OPT_PRIVATE_EXTENSION_BASE}
\end{datadesc}

\begin{datadesc}{OPT_PROTOCOL_VERSION}
\end{datadesc}

\begin{datadesc}{OPT_REFERRALS}
\end{datadesc}

\begin{datadesc}{OPT_REFHOPLIMIT}
\end{datadesc}

\begin{datadesc}{OPT_RESTART}
\end{datadesc}

\begin{datadesc}{OPT_SERVER_CONTROLS}
\end{datadesc}

\begin{datadesc}{OPT_SIZELIMIT}
\end{datadesc}

\begin{datadesc}{OPT_SUCCESS}
\end{datadesc}

\begin{datadesc}{OPT_TIMELIMIT}
\end{datadesc}

\begin{datadesc}{OPT_TIMEOUT}
\end{datadesc}

\begin{datadesc}{OPT_URI}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_AUTHCID}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_AUTHZID}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_MECH}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_REALM}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_SECPROPS}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_SSF}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_SSF_EXTERNAL}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_SSF_MAX}
\end{datadesc}

\begin{datadesc}{OPT_X_SASL_SSF_MIN}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_ALLOW}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_CACERTDIR}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_CACERTFILE}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_CERTFILE}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_CIPHER_SUITE}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_CTX}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_DEMAND}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_HARD}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_KEYFILE}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_NEVER}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_RANDOM_FILE}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_REQUIRE_CERT}
\end{datadesc}

\begin{datadesc}{OPT_X_TLS_TRY}
\end{datadesc}


% --- 3.3. ---
% Exceptions are described using a ``excdesc'' block.  This has only
% one parameter: the exception name.  Exceptions defined as classes in
% the source code should be documented using this environment, but
% constructor parameters must be ommitted.

\subsection{Exceptions}
\label{subsec:exceptfrommeth}

The module defines the following exceptions:

\begin{excdesc}{LDAPError}
This is the base class of all execeptions raised by the module \module{ldap}.
Unlike the \C\ interface, errors are not returned as result codes, but
are instead turned into exceptions, raised as soon an the error condition 
is detected.

The exceptions are accompanied by a dictionary possibly
containing an string value for the key \constant{'desc'} 
(giving an English description of the error class)
and/or a string value for the key \constant{'info'}
(giving a string containing more information that the server may have sent).

A third possible field of this dictionary is \constant{'matched'} and
is set to a truncated form of the name provided or alias dereferenced
for the lowest entry (object or alias) that was matched.

\end{excdesc}

\begin{excdesc}{ADMINLIMIT_EXCEEDED}

\end{excdesc}
\begin{excdesc}{AFFECTS_MULTIPLE_DSAS}

\end{excdesc}
\begin{excdesc}{ALIAS_DEREF_PROBLEM}
A problem was encountered when dereferencing an alias.
(Sets the \constant{'matched'} field.)
\end{excdesc}
\begin{excdesc}{ALIAS_PROBLEM}
An alias in the directory points to a nonexistent entry.
(Sets the \constant{'matched'} field.)
\end{excdesc}
\begin{excdesc}{ALREADY_EXISTS}
The entry already exists. E.g. the \var{dn} specified with \method{add()}
already exists in the DIT.
\end{excdesc}
\begin{excdesc}{}

\end{excdesc}
\begin{excdesc}{AUTH_UNKNOWN}
The authentication method specified to \method{bind()} is not known.
\end{excdesc}
\begin{excdesc}{BUSY}
The DSA is busy.
\end{excdesc}
\begin{excdesc}{CLIENT_LOOP}

\end{excdesc}
\begin{excdesc}{COMPARE_FALSE}
A compare operation returned false.
(This exception should never be seen because \method{compare()} returns
a boolean result.)
\end{excdesc}
\begin{excdesc}{COMPARE_TRUE}
A compare operation returned true.
(This exception should never be seen because \method{compare()} returns
a boolean result.)
\end{excdesc}
\begin{excdesc}{CONFIDENTIALITY_REQUIRED}
Indicates that the session is not protected by a protocol such
as Transport Layer Security (TLS), which provides session
confidentiality.
\end{excdesc}
\begin{excdesc}{CONNECT_ERROR}

\end{excdesc}
\begin{excdesc}{CONSTRAINT_VIOLATION}
An attribute value specified or an operation started violates some
server-side constraint
(e.g., a postalAddress has too many lines or a line that is too long
or a password is expired).
\end{excdesc}
\begin{excdesc}{CONTROL_NOT_FOUND}

\end{excdesc}
\begin{excdesc}{DECODING_ERROR}
An error was encountered decoding a result from the LDAP server.
\end{excdesc}
\begin{excdesc}{ENCODING_ERROR}
An error was encountered encoding parameters to send to the LDAP server.
\end{excdesc}
\begin{excdesc}{FILTER_ERROR}
An invalid filter was supplied to method{search()}
(e.g. unbalanced parentheses).
\end{excdesc}
\begin{excdesc}{INAPPROPRIATE_AUTH}
Inappropriate authentication was specified (e.g. \constant{LDAP_AUTH_SIMPLE}
was specified and the entry does not have a userPassword attribute).
\end{excdesc}
\begin{excdesc}{INAPPROPRIATE_MATCHING}
Filter type not supported for the specified attribute.
\end{excdesc}
\begin{excdesc}{INSUFFICIENT_ACCESS}
The user has insufficient access to perform the operation.
\end{excdesc}
\begin{excdesc}{INVALID_CREDENTIALS}
Invalid credentials were presented during \method{bind()} or
\method{simple_bind()}.
(e.g., the wrong password).
\end{excdesc}
\begin{excdesc}{INVALID_DN_SYNTAX}
A syntactically invalid DN was specified. (Sets the \constant{'matched'} field.)
\end{excdesc}
\begin{excdesc}{INVALID_SYNTAX}
An attribute value specified by the client did not comply to the
syntax defined in the server-side schema.
\end{excdesc}
\begin{excdesc}{IS_LEAF}
The object specified is a leaf of the diretcory tree.
Sets the \constant{'matched'} field of the exception dictionary value.
\end{excdesc}
\begin{excdesc}{LOCAL_ERROR}
Some local error occurred. This is usually due to failed memory allocation.
\end{excdesc}
\begin{excdesc}{LOOP_DETECT}
A loop was detected.
\end{excdesc}
\begin{excdesc}{MORE_RESULTS_TO_RETURN}

\end{excdesc}
\begin{excdesc}{NAMING_VIOLATION}
A naming violation occurred. This is raised e.g. if the LDAP server
has constraints about the tree naming.
\end{excdesc}
\begin{excdesc}{NO_OBJECT_CLASS_MODS}
Modifying the objectClass attribute as requested is not allowed
(e.g. modifying structural object class of existing entry).
\end{excdesc}
\begin{excdesc}{NOT_ALLOWED_ON_NONLEAF}
The operation is not allowed on a non-leaf object.
\end{excdesc}
\begin{excdesc}{NOT_ALLOWED_ON_RDN}
The operation is not allowed on an RDN.
\end{excdesc}
\begin{excdesc}{NOT_SUPPORTED}

\end{excdesc}
\begin{excdesc}{NO_MEMORY}

\end{excdesc}
\begin{excdesc}{NO_OBJECT_CLASS_MODS}
Object class modifications are not allowed.
\end{excdesc}
\begin{excdesc}{NO_RESULTS_RETURNED}

\end{excdesc}
\begin{excdesc}{NO_SUCH_ATTRIBUTE}
The attribute type specified does not exist in the entry.
\end{excdesc}
\begin{excdesc}{NO_SUCH_OBJECT}
The specified object does not exist in the directory.
Sets the \constant{'matched'} field of the exception dictionary value.
\end{excdesc}
\begin{excdesc}{OBJECT_CLASS_VIOLATION}
An object class violation occurred when the LDAP server checked
the data sent by the client against the server-side schema
(e.g. a "must" attribute was missing in the entry data).
\end{excdesc}
\begin{excdesc}{OPERATIONS_ERROR}
An operations error occurred.
\end{excdesc}
\begin{excdesc}{OTHER}
An unclassified error occurred.
\end{excdesc}
\begin{excdesc}{PARAM_ERROR}
An ldap routine was called with a bad parameter.
\end{excdesc}
\begin{excdesc}{PARTIAL_RESULTS}
Partial results only returned. This exception is raised if
a referral is received when using LDAPv2.
(This exception should never be seen with LDAPv3.)
\end{excdesc}
\begin{excdesc}{PROTOCOL_ERROR}
A violation of the LDAP protocol was detected.
\end{excdesc}
\begin{excdesc}{RESULTS_TOO_LARGE}
The result does not fit into a UDP packet. This happens only when using
UDP-based CLDAP (connection-less LDAP) which is not supported anyway.
\end{excdesc}
\begin{excdesc}{SASL_BIND_IN_PROGRESS}

\end{excdesc}
\begin{excdesc}{SERVER_DOWN}
The  LDAP  library  can't  contact the LDAP server.
\end{excdesc}
\begin{excdesc}{SIZELIMIT_EXCEEDED}
An LDAP size limit was exceeded.
This could be due to a `sizelimit' configuration on the LDAP server.
\end{excdesc}
\begin{excdesc}{STRONG_AUTH_NOT_SUPPORTED}
The LDAP server does not support strong authentication.
\end{excdesc}
\begin{excdesc}{STRONG_AUTH_REQUIRED}
Strong authentication is required  for the operation.
\end{excdesc}
\begin{excdesc}{TIMELIMIT_EXCEEDED}
An LDAP time limit was exceeded.
\end{excdesc}
\begin{excdesc}{TIMEOUT}
A timelimit was exceeded while waiting for a result from the server.
\end{excdesc}
\begin{excdesc}{TYPE_OR_VALUE_EXISTS}
An  attribute  type or attribute value specified already 
exists in the entry.
\end{excdesc}
\begin{excdesc}{UNAVAILABLE}
The DSA is unavailable.
\end{excdesc}
\begin{excdesc}{UNAVAILABLE_CRITICAL_EXTENSION}
Indicates that the LDAP server was unable to satisfy a request
because one or more critical extensions were not available. Either
the server does not support the control or the control is not appropriate
for the operation type.
\end{excdesc}
\begin{excdesc}{UNDEFINED_TYPE}
An attribute type used is not defined in the server-side schema.
\end{excdesc}
\begin{excdesc}{UNWILLING_TO_PERFORM}
The  DSA  is  unwilling to perform the operation.
\end{excdesc}
\begin{excdesc}{USER_CANCELLED}
The operation was cancelled via the \method{abandon()} method.
\end{excdesc}

The above exceptions are raised when a result code from an underlying API
call does not indicate success.

% ---- 3.4. ----
% Other standard environments:
%
%  classdesc	- Python classes; same arguments are funcdesc
%  methoddesc	- methods, like funcdesc but has an optional parameter 
%		  to give the type name: \begin{methoddesc}[mytype]{name}{args}
%		  By default, the type name will be the name of the
%		  last class defined using classdesc.  The type name
%		  is required if the type is implemented in C (because 
%		  there's no classdesc) or if the class isn't directly 
%		  documented (if it's private).
%  memberdesc	- data members, like datadesc, but with an optional
%		  type name like methoddesc.

\subsection{LDAPObject class \label{ldap-objects}}

% This label is generally useful for referencing this section, but is
% also used to give a filename when generating HTML.

%\noindent
Instances of \class{ldap.LDAPObject} are returned by \function{initialize()}
and \function{open()} (deprecated). The connection is automatically unbound
and closed  when the LDAP object is deleted.

Most methods on LDAP objects initiate an asynchronous request to the
LDAP server and return a message id that can be used later to retrieve
the result with \method{result()}.
Methods with names ending in `\constant{_s}' are the synchronous form 
and wait for and return with the server's result, or with
\constant{None} if no data is expected.

LDAPObject instances, have the following methods:

%%------------------------------------------------------------
%% abandon

\begin{methoddesc}[LDAPObject]{abandon}{msgid}
Abandons or cancels an LDAP operation in progress. The \var{msgid} argument
should be the message ID of an outstanding LDAP operation as returned by
the asynchronous methods \method{search()}, \method{modify()}, etc. 
The caller can expect that the result
of an abandoned operation will not be returned from a future call to 
\method{result()}.
\end{methoddesc}

%%------------------------------------------------------------
%% add

\begin{methoddesc}[LDAPObject]{add}{dn, modlist} % -> int
     \methodline{add_s}{dn, modlist}
Performs an LDAP add operation. The \var{dn} argument is the distinguished
name (DN) of the entry to add, and \var{modlist} is a list of attributes to be
added. The modlist is similar the one passed to \method{modify()}, except that the
operation integer is omitted from the tuples in modlist. You might want to
look into sub-module l\refmodule{ldap.modlist} for generating the modlist.
\end{methoddesc}

%%------------------------------------------------------------
%% bind

\begin{methoddesc}[LDAPObject]{bind}{who, cred, method} % -> int
     \methodline[LDAPObject]{bind_s}{who, cred, method} % -> None
     \methodline[LDAPObject]{simple_bind}{\optional{who=\constant{''} \optional{, cred=\constant{''}}}} % -> int
     \methodline[LDAPObject]{simple_bind_s}{\optional{who=\constant{''} \optional{, cred=\constant{''}}}} % -> None
After an LDAP object is created, and before any other operations can be
attempted over the connection, a bind operation must be performed.

This method attempts to bind with the LDAP server using 
either simple authentication, or Kerberos (if available).
The first and most general method, \method{bind()},
takes a third parameter, \var{method}, which can currently solely
be \constant{AUTH_SIMPLE}.
\end{methoddesc}

%%------------------------------------------------------------
%% sasl_interactive_bind_s

\begin{methoddesc}[None]{sasl_interactive_bind_s}{who, auth} % -> None
This call is used to bind to the directory with a SASL bind request.
\end{methoddesc}

%%------------------------------------------------------------
%% 
\begin{methoddesc}[LDAPObject]{cancel}{
        cancelid,
        \optional{, serverctrls=\constant{None} 
        \optional{, clientctrls=\constant{None}}}}
  Send cancels extended operation for an LDAP operation specified by \var{cancelid}.
  The \var{cancelid} should be the message id of an outstanding LDAP operation as returned
  by the asynchronous methods search(), modify() etc.  The caller
  can expect that the result of an abandoned operation will not be
  returned from a future call to result().
  In opposite to abandon() this extended operation gets an result from
  the server and thus should be preferred if the server supports it.
\end{methoddesc}


%%------------------------------------------------------------
%% compare

\begin{methoddesc}[LDAPObject]{compare}{dn, attr, value} % -> int
     \methodline[LDAPObject]{compare_s}{dn, attr, value} % -> tuple
Perform an LDAP comparison between the attribute named \var{attr} of 
entry \var{dn}, and the value \var{value}. The synchronous form
returns \constant{0} for false, or \constant{1} for true.
The asynchronous form returns the message ID of the initiated request, 
and the result of the asynchronous compare can be obtained using 
\method{result()}.  

Note that the asynchronous technique yields the answer
by raising the exception objects \constant{COMPARE_TRUE} or
\constant{COMPARE_FALSE}.

\textbf{Note} A design fault in the LDAP API prevents \var{value} 
from containing nul characters.
\end{methoddesc}

%%------------------------------------------------------------
%% delete

\begin{methoddesc}[LDAPObject]{delete}{dn} % -> int
     \methodline[LDAPObject]{delete_s}{dn} % -> None
Performs an LDAP delete operation on \var{dn}. The asynchronous form
returns the message id of the initiated request, and the result can be obtained
from a subsequent call to \method{result()}.
\end{methoddesc}

%%------------------------------------------------------------
%% modify

\begin{methoddesc}[LDAPObject]{modify}{ dn, modlist } % -> int
     \methodline[LDAPObject]{modify_s}{ dn, modlist } % -> None
Performs an LDAP modify operation on an entry's attributes. 
The \var{dn} argument is the distinguished name (DN) of the entry to modify,
and \var{modlist} is a list of modifications to make to that entry.

Each element in the list \var{modlist} should be a tuple of the form 
\code{(mod_op,mod_type,mod_vals)},
where \var{mod_op} indicates the operation (one of \constant{MOD_ADD}, 
\constant{MOD_DELETE}, or \constant{MOD_REPLACE}),
\var{mod_type} is a string indicating the attribute type name, and 
\var{mod_vals} is either a string value or a list of string values to add, 
delete or replace respectively.  For the delete operation, \var{mod_vals}
may be \constant{None} indicating that all attributes are to be deleted.

The asynchronous method \method{modify()} returns the message ID of the 
initiated request.

You might want to look into sub-module \refmodule{ldap.modlist} for
generating \var{modlist}.
\end{methoddesc}

%%------------------------------------------------------------
%% modrdn

\begin{methoddesc}[LDAPObject]{modrdn}{dn, newrdn \optional{, delold=\constant{1}}}
		%-> int
     \methodline[LDAPObject]{modrdn_s}{dn, newrdn \optional{, delold=\constant{1}}}
		% -> None
Perform a `modify RDN' operation, (i.e. a renaming operation).
These routines take \var{dn} (the DN
of the entry whose RDN is to be changed, and \var{newrdn}, the new RDN to
give to the entry. The optional parameter \var{delold} is used to specify
whether the old RDN should be kept as an attribute of the entry or not.
The asynchronous version returns the initiated message id.

This operation is emulated by \method{rename()} and \method{rename_s()} methods
since the modrdn2* routines in the C library are deprecated.
\end{methoddesc}

%%------------------------------------------------------------
%% passwd

\begin{methoddesc}[LDAPObject]{passwd}{user,oldpw,newpw}
		%-> int
     \methodline[LDAPObject]{passwd_s}{user,oldpw,newpw}
		% -> None
Perform a `LDAP Password Modify Extended Operation' operation
on the entry specified by \var{user}.
The old password in \var{oldpw} is replaced with the new
password in \var{newpw} by a LDAP server supporting this operation.

The asynchronous version returns the initiated message id.

\begin{seealso}
\seerfc{3062}{LDAP Password Modify Extended Operation}{}
\end{seealso}

\end{methoddesc}


%%------------------------------------------------------------
%% rename

\begin{methoddesc}[LDAPObject]{rename}{dn, newrdn \optional{, newsuperior=\constant{None}} \optional{, delold=\constant{1}}}
		%-> int
     \methodline[LDAPObject]{rename_s}{dn, newrdn \optional{, newsuperior=\constant{None} \optional{, delold=\constant{1}}}}
		% -> None
Perform a `Rename' operation, (i.e. a renaming operation).
These routines take \var{dn} (the DN
of the entry whose RDN is to be changed, and \var{newrdn}, the new RDN to
give to the entry.
The optional parameter \var{newsuperior} is used to specify
a new parent DN for moving an entry in the tree
(not all LDAP servers support this).
The optional parameter \var{delold} is used to specify
whether the old RDN should be kept as an attribute of the entry or not.
\end{methoddesc}

%%------------------------------------------------------------
%% result

\begin{methoddesc}[LDAPObject]{result}{\optional{ msgid=\constant{RES_ANY} \optional{, all=\constant{1} \optional{, timeout=\constant{-1}}}}} % -> 2-tuple
This method is used to wait for and return the result of an operation
previously initiated by one of the LDAP \emph{asynchronous} operations
(eg \method{search()}, \method{modify()}, etc.) 

The \var{msgid} parameter is the integer identifier returned by that
method. 
The identifier is guaranteed to be unique across an LDAP session,
and tells the \method{result()} method to request the result of that
specific operation.

If a result is desired from any one of the in-progress operations,
\var{msgid} should be specified as the constant \constant{RES_ANY}
and the method \method{result2()} should be used instead.

The \var{all} parameter only has meaning for \method{search()} responses
and is used to select whether a single entry of the search
response should be returned, or to wait for all the results
of the search before returning.

A search response is made up of zero or more search entries
followed by a search result. If \var{all} is 0, search entries will
be returned one at a time as they come in, via separate calls
to \method{result()}. If all is 1, the search response will be returned
in its entirety, i.e. after all entries and the final search
result have been received.

For \var{all} set to 0, result tuples
trickle in (with the same message id), and with the result types
\constant{RES_SEARCH_ENTRY} and \constant{RES_SEARCH_REFERENCE},
until the final result which has a result
type of \constant{RES_SEARCH_RESULT} and a (usually) empty data field.
When all is set to 1, only one result is returned, with a
result type of RES_SEARCH_RESULT, and all the result tuples
listed in the data field.

The \var{timeout} parameter is a limit on the number of seconds that the
method will wait for a response from the server. 
If \var{timeout} is negative (which is the default),
the method will wait indefinitely for a response.
The timeout can be expressed as a floating-point value, and
a value of \constant{0} effects a poll.
If a timeout does occur, a \exception{TIMEOUT} exception is raised,
unless polling, in which case \constant{(None, None)} is returned.

The \method{result()} method returns a tuple of the form 
\code{(\textit{result-type}, \textit{result-data})}.
The first element, \textit{result-type} is a string, being one of
these module constants:
\constant{RES_BIND}, \constant{RES_SEARCH_ENTRY},
\constant{RES_SEARCH_REFERENCE}, \constant{RES_SEARCH_RESULT}, 
\constant{RES_MODIFY}, \constant{RES_ADD}, \constant{RES_DELETE}, 
\constant{RES_MODRDN}, or \constant{RES_COMPARE}.

If \var{all} is \constant{0}, one response at a time is returned on
each call to \method{result()}, with termination indicated by 
\textit{result-data} being an empty list.

See \method{search()} for a description of the search result's 
\var{result-data}, otherwise the \var{result-data} is normally meaningless.

\end{methoddesc}

\begin{methoddesc}[LDAPObject]{result2}{\optional{ msgid=\constant{RES_ANY} \optional{, all=\constant{1} \optional{, timeout=\constant{-1}}}}} % -> 3-tuple
This method behaves almost exactly like \method{result()}. But
it returns a 3-tuple also containing the message id of the
outstanding LDAP operation a particular result message belongs
to. This is especially handy if one needs to dispatch results
obtained with \var{msgid=\constant{RES_ANY}} to several consumer
threads which invoked a particular LDAP operation.
\end{methoddesc}

%%------------------------------------------------------------
%% search

\begin{methoddesc}[LDAPObject]{search}{base, scope \optional{,filterstr=\constant{'(objectClass=*)'} \optional{, 
	attrlist=\constant{None} \optional{, attrsonly=\constant{0}}}}} %->int
     \methodline[LDAPObject]{search_s}{base, scope \optional{,filterstr=\constant{'(objectClass=*)'} \optional{, 
     	attrlist=\constant{None} \optional{, attrsonly=\constant{0}}}}} 
		%->list|None
    \methodline[LDAPObject]{search_st}{base, scope \optional{,filterstr=\constant{'(objectClass=*)'} \optional{,
    	attrlist=\constant{None} \optional{, attrsonly=\constant{0} 
	\optional{, timeout=\constant{-1}}}}}}
    \methodline[LDAPObject]{search_ext}{
        base, scope
        \optional{,filterstr=\constant{'(objectClass=*)'}
        \optional{, attrlist=\constant{None} 
        \optional{, attrsonly=\constant{0} 
        \optional{, serverctrls=\constant{None} 
        \optional{, clientctrls=\constant{None} 
	\optional{, timeout=\constant{-1} 
        \optional{, sizelimit=\constant{0}}}}}}}}}
		%->int
    \methodline[LDAPObject]{search_ext_s}{
        base, scope
        \optional{,filterstr=\constant{'(objectClass=*)'}
        \optional{, attrlist=\constant{None} 
        \optional{, attrsonly=\constant{0} 
        \optional{, serverctrls=\constant{None} 
        \optional{, clientctrls=\constant{None} 
	\optional{, timeout=\constant{-1} 
        \optional{, sizelimit=\constant{0}}}}}}}}}
		%->list|None
Perform an LDAP search operation, with \var{base} as the DN of the entry
at which to start the search, \var{scope} being one of 
\constant{SCOPE_BASE} (to search the object itself), 
\constant{SCOPE_ONELEVEL} (to search the object's immediate children), or
\constant{SCOPE_SUBTREE} (to search the object and all its descendants).

The
\var{filterstr} argument is a string representation of the filter to apply in
the search.

\begin{seealso}
\seerfc{4515}{Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.}{}
\end{seealso}

Each result tuple is of the form \code{(\var{dn},\var{attrs})}, 
where \var{dn} is a string containing the DN (distinguished name) of the
entry, and \var{attrs} is a dictionary containing the attributes associated
with the entry. The keys of \var{attrs} are strings, and the associated
values are lists of strings.

The DN in \var{dn} is extracted using the underlying \cfunction{ldap_get_dn()}
function,
which may raise an exception if the DN is malformed.

If \var{attrsonly} is non-zero, the values of \var{attrs} will be meaningless
(they are not transmitted in the result).

The retrieved attributes can be limited with the \var{attrlist} parameter.
If \var{attrlist} is \constant{None}, all the attributes of each entry are returned.

\var{serverctrls} not implemented yet.

\var{clientctrls} not implemented yet.

The synchronous form with timeout, \method{search_st()} or \method{search_ext_s()},
will block for at most \var{timeout} seconds (or indefinitely if \var{timeout}
is negative). A \exception{TIMEOUT} exception is raised if no result is received
within the specified time.

The amount of search results retrieved can be limited with the
\var{sizelimit} parameter when using \method{search_ext()}
or \method{search_ext_s()} (client-side search limit). If non-zero
not more than \var{sizelimit} results are returned by the server.

\end{methoddesc}

%%------------------------------------------------------------
%% unbind

\begin{methoddesc}[LDAPObject]{unbind}{} % -> int
       \methodline{unbind_s}{} % -> None
This call is used to unbind from the directory, terminate the current
association, and free resources. Once called, the connection to the
LDAP server is closed and the LDAP object is marked invalid.
Further invocation of methods on the object will yield exceptions.

The \method{unbind()} and \method{unbind_s()} methods are both
synchronous in nature
\end{methoddesc}

%%------------------------------------------------------------
%% whoami_s

\begin{methoddesc}[LDAPObject]{whoami_s}{} % -> string
This synchronous method implements the LDAP "Who Am I?"
extended operation.

It is useful for finding out to find out which identity
is assumed by the LDAP server after a SASL bind.
\end{methoddesc}


\subsubsection{LDAP options}

\begin{methoddesc}[LDAPObject]{get_option}{option} % -> None
  This function returns the value of the LDAPObject option
  specified by \var{option}.
\end{methoddesc}

\begin{methoddesc}[LDAPObject]{set_option}{option, invalue} % -> None
  This function sets the value of the LDAPObject option
  specified by \var{option} to \var{invalue}.
\end{methoddesc}

%%------------------------------------------------------------
%% manage_dsa_it

\begin{methoddesc}[LDAPObject]{manage_dsa_it}{enable, \optional{, critical=\constant{0}}}
		%-> None
Enables or disables manageDSAit mode (see draft-zeilenga-ldap-namedref)
according to the specified integer flag \var{enable}. The
integer flag \var{critical} specifies if the use of this extended
control is marked critical.

\textbf{Note}
This method is somewhat immature and might vanish in future versions
if full support for extended controls will be implemented. You have been
warned!
\end{methoddesc}

%%============================================================
%% attributes

\subsubsection{Object attributes}

If the underlying library provides enough information,
each LDAP object will also have the following attributes.
These attributes are mutable unless described as read-only.

%%------------------------------------------------------------
%% deref

\begin{memberdesc}[LDAP]{deref} % -> int
    Controls whether aliases are automatically dereferenced.
    This must be one of
    \constant{DEREF_NEVER}, \constant{DEREF_SEARCHING}, \constant{DEREF_FINDING},
    or \constant{DEREF_ALWAYS}.
    This option is mapped to option constant \constant{OPT_DEREF}
    and used in the underlying OpenLDAP lib.
\end{memberdesc}

%%------------------------------------------------------------
%% network_timeout

\begin{memberdesc}[LDAP]{network_timeout} % -> int
    Limit on waiting for a network response, in seconds. 
    Defaults to \constant{NO_LIMIT}.
    This option is mapped to option constant \constant{OPT_NETWORK_TIMEOUT}
    and used in the underlying OpenLDAP lib.
\end{memberdesc}

%%------------------------------------------------------------
%% protocol_version

\begin{memberdesc}[LDAP]{protocol_version} % -> int
    Version of LDAP in use (either \constant{VERSION2} for LDAPv2
    or \constant{VERSION3} for LDAPv3).
    This option is mapped to option constant \constant{OPT_PROTOCOL_VERSION}
    and used in the underlying OpenLDAP lib.

\textbf{Note}
It is highly recommended to set the protocol version after establishing
a LDAP connection with \function{initialize()} and before submitting
the first request.
\end{memberdesc}

%%------------------------------------------------------------
%% sizelimit

\begin{memberdesc}[LDAP]{sizelimit} % -> int
    Limit on size of message to receive from server. 
    Defaults to \constant{NO_LIMIT}.
    This option is mapped to option constant \constant{OPT_SIZELIMIT}
    and used in the underlying OpenLDAP lib. Its use is deprecated
    in favour of \var{sizelimit} parameter when using \method{search_ext()}.
\end{memberdesc}

%%------------------------------------------------------------
%% timelimit

\begin{memberdesc}[LDAP]{timelimit} % -> int
    Limit on waiting for any response, in seconds. 
    Defaults to \constant{NO_LIMIT}.
    This option is mapped to option constant \constant{OPT_TIMELIMIT}
    and used in the underlying OpenLDAP lib. Its use is deprecated
    in favour of using \var{timeout}.
\end{memberdesc}

%%------------------------------------------------------------
%% timeout

\begin{memberdesc}[LDAP]{timeout} % -> int
    Limit on waiting for any response, in seconds. 
    Defaults to \constant{NO_LIMIT}.
    This option is used in the wrapper module.
\end{memberdesc}


% ==== 4. ====
% Now is probably a good time for a complete example.  (Alternatively,
% an example giving the flavor of the module may be given before the
% detailed list of functions.)

\subsection{Example \label{ldap-example}}

The following example demonstrates how to open a connection to an
LDAP server using the \module{ldap} module and invoke a synchronous
subtree search.

\begin{verbatim}
>>> import ldap
>>> l = ldap.initialize('ldap://localhost:1390')
>>> l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,('cn=fred*'),['cn','mail'])
[('cn=Fred Feuerstein,ou=Testing,dc=stroeder,dc=de', {'cn': ['Fred Feuerstein']})]
>>> r = l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,('objectClass=*'),['cn','mail'])
>>> for dn,entry in r:
>>>   print 'Processing',repr(dn)
>>>   handle_ldap_entry(entry)
\end{verbatim}

% ==== 5. ====
% If your module defines new object types (for a built-in module) or
% classes (for a module written in Python), you should list the
% methods and instance variables (if any) of each type or class in a
% separate subsection.