reference/ldap/controls.xml
b37727abaf0e731a05c516fd85b44e86f4bf5c75
...
...
@@ -0,0 +1,234 @@
1
+
<?xml version="1.0" encoding="utf-8"?>
2
+
<!-- $Revision$ -->
3
+

4
+
<chapter xml:id="ldap.controls" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
+
<title>LDAP controls</title>
6
+
<para>
7
+
Controls are special objects which may be sent alongside an
8
+
LDAP request to alter LDAP server behavior while performing
9
+
the request. There may also be controls sent by the server
10
+
alongside the response to provide more information, usually
11
+
to answer a control object from the request.
12
+
<note>
13
+
<para>
14
+
Not all controls are supported by all LDAP servers. To know which controls
15
+
are supported by a server, you need to query the root DSE by reading an
16
+
empty dn with the filter (objectClass=*).
17
+
</para>
18
+
<example>
19
+
<title>Testing support for paged result control</title>
20
+
<programlisting role="php">
21
+
<![CDATA[
22
+
<?php
23
+

24
+
// $ds is a valid link identifier for a directory server
25
+

26
+
$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
27
+
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
28
+
die("This server does not support paged result control");
29
+
}
30
+

31
+
?>
32
+
]]>
33
+
</programlisting>
34
+
</example>
35
+
</note>
36
+
</para>
37
+

38
+
<para>
39
+
As of PHP 7.3, you can send controls with your request in all
40
+
request functions using the <parameter>controls</parameter> parameter. When a ext
41
+
version of a function exists, you should use it if you want to
42
+
get access to the full response object and be able to parse
43
+
response controls from it using <function>ldap_parse_result</function>.
44
+
</para>
45
+

46
+
<para>
47
+
<parameter>controls</parameter> must be an array containing an array for each control to send,
48
+
containing the following keys:
49
+
<variablelist>
50
+
<varlistentry>
51
+
<term>
52
+
oid
53
+
(<type>string</type>)
54
+
</term>
55
+
<listitem>
56
+
<simpara>
57
+
The OID of the control. You should use constants starting with
58
+
LDAP_CONTROL_ for this. See <link linkend="ldap.constants">LDAP Constants</link>.
59
+
</simpara>
60
+
</listitem>
61
+
</varlistentry>
62
+
<varlistentry>
63
+
<term>
64
+
iscritical
65
+
(<type>bool</type>)
66
+
</term>
67
+
<listitem>
68
+
<simpara>
69
+
If a control is noted as critical, the request will fail if the
70
+
control is not supported by the server, or if it fails to be
71
+
applied. Note that some controls should always be marked as critical
72
+
as noted in the RFC introducing them. Defaults to &false;.
73
+
</simpara>
74
+
</listitem>
75
+
</varlistentry>
76
+
<varlistentry>
77
+
<term>
78
+
value
79
+
(<type>mixed</type>)
80
+
</term>
81
+
<listitem>
82
+
<simpara>
83
+
If applicable, the value of the control. Read below for more information.
84
+
</simpara>
85
+
</listitem>
86
+
</varlistentry>
87
+
</variablelist>
88
+

89
+
</para>
90
+

91
+
<para>
92
+
Most control values are sent to the server BER-encoded.
93
+
You may either BER-encode the value yourself, or you can instead
94
+
pass an array with the correct keys so that the encoding is done
95
+
for you.
96
+
Supported controls to be passed as an array are:
97
+
<itemizedlist>
98
+
<listitem>
99
+
<para>
100
+
<constant>LDAP_CONTROL_PAGEDRESULTS</constant>
101
+
Expected keys are [size] and [cookie]
102
+
</para>
103
+
</listitem>
104
+
<listitem>
105
+
<para>
106
+
<constant>LDAP_CONTROL_ASSERT</constant>
107
+
Expected key is filter
108
+
</para>
109
+
</listitem>
110
+
<listitem>
111
+
<para>
112
+
<constant>LDAP_CONTROL_VALUESRETURNFILTER</constant>
113
+
Expected key is filter
114
+
</para>
115
+
</listitem>
116
+
<listitem>
117
+
<para>
118
+
<constant>LDAP_CONTROL_PRE_READ</constant>
119
+
Expected key is attrs
120
+
</para>
121
+
</listitem>
122
+
<listitem>
123
+
<para>
124
+
<constant>LDAP_CONTROL_POST_READ</constant>
125
+
Expected key is attrs
126
+
</para>
127
+
</listitem>
128
+
<listitem>
129
+
<para>
130
+
<constant>LDAP_CONTROL_SORTREQUEST</constant>
131
+
Expects an array of arrays with keys attr, [oid], [reverse].
132
+
</para>
133
+
</listitem>
134
+
<listitem>
135
+
<para>
136
+
<constant>LDAP_CONTROL_VLVREQUEST</constant>
137
+
Expected keys are before, after, attrvalue|(offset, count), [context]
138
+
</para>
139
+
</listitem>
140
+
</itemizedlist>
141
+
</para>
142
+

143
+
<para>
144
+
The following controls do not need any value:
145
+
<itemizedlist>
146
+
<listitem>
147
+
<para>
148
+
<constant>LDAP_CONTROL_PASSWORDPOLICYREQUEST</constant>
149
+
</para>
150
+
</listitem>
151
+
<listitem>
152
+
<para>
153
+
<constant>LDAP_CONTROL_MANAGEDSAIT</constant>
154
+
</para>
155
+
</listitem>
156
+
<listitem>
157
+
<para>
158
+
<constant>LDAP_CONTROL_DONTUSECOPY</constant>
159
+
</para>
160
+
</listitem>
161
+
</itemizedlist>
162
+
</para>
163
+

164
+
<para>
165
+
The control <constant>LDAP_CONTROL_PROXY_AUTHZ</constant> is a special case
166
+
as its value is not expected to be BER-encoded, so you can directly
167
+
use a string for its value.
168
+
</para>
169
+

170
+
<para>
171
+
When controls are parsed by <function>ldap_parse_result</function>, values are
172
+
turned into an array if supported.
173
+
This is supported for:
174
+
<itemizedlist>
175
+
<listitem>
176
+
<para>
177
+
<constant>LDAP_CONTROL_PASSWORDPOLICYRESPONSE</constant>
178
+
Keys are expire, grace, [error]
179
+
</para>
180
+
</listitem>
181
+
<listitem>
182
+
<para>
183
+
<constant>LDAP_CONTROL_PAGEDRESULTS</constant>
184
+
Keys are size, cookie
185
+
</para>
186
+
</listitem>
187
+
<listitem>
188
+
<para>
189
+
<constant>LDAP_CONTROL_PRE_READ</constant>
190
+
Keys are dn and LDAP attributes names
191
+
</para>
192
+
</listitem>
193
+
<listitem>
194
+
<para>
195
+
<constant>LDAP_CONTROL_POST_READ</constant>
196
+
Keys are dn and LDAP attributes names
197
+
</para>
198
+
</listitem>
199
+
<listitem>
200
+
<para>
201
+
<constant>LDAP_CONTROL_SORTRESPONSE</constant>
202
+
Keys are errcode, [attribute]
203
+
</para>
204
+
</listitem>
205
+
<listitem>
206
+
<para>
207
+
<constant>LDAP_CONTROL_VLVRESPONSE</constant>
208
+
Keys are target, count, errcode, context
209
+
</para>
210
+
</listitem>
211
+
</itemizedlist>
212
+
</para>
213
+
</chapter>
214
+

215
+
<!-- Keep this comment at the end of the file
216
+
Local variables:
217
+
mode: sgml
218
+
sgml-omittag:t
219
+
sgml-shorttag:t
220
+
sgml-minimize-attributes:nil
221
+
sgml-always-quote-attributes:t
222
+
sgml-indent-step:1
223
+
sgml-indent-data:t
224
+
indent-tabs-mode:nil
225
+
sgml-parent-document:nil
226
+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
227
+
sgml-exposed-tags:nil
228
+
sgml-local-catalogs:nil
229
+
sgml-local-ecat-files:nil
230
+
End:
231
+
vim600: syn=xml fen fdm=syntax fdl=2 si
232
+
vim: et tw=78 syn=sgml
233
+
vi: ts=1 sw=1
234
+
-->
0
235



Tools (Spanish Manual)