?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
2010-03-02 Jb Evain <jbevain@novell.com>
[mcs.git] / class / Novell.Directory.Ldap / Novell.Directory.Ldap.Controls / LdapVirtualListControl.cs
blob9aa97a812d81747ed1c08bdef16d5a5a49014e55
1 /******************************************************************************
2 * The MIT License
3 * Copyright (c) 2003 Novell Inc. www.novell.com
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the Software), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 * SOFTWARE.
22 *******************************************************************************/
23 //
24 // Novell.Directory.Ldap.Controls.LdapVirtualListControl.cs
25 //
26 // Author:
27 // Sunil Kumar (Sunilk@novell.com)
28 //
29 // (C) 2003 Novell, Inc (http://www.novell.com)
30 //
31
32 using System;
33 using Novell.Directory.Ldap;
34 using Novell.Directory.Ldap.Asn1;
35
36 namespace Novell.Directory.Ldap.Controls
37 {
38
39 /* The following is the ASN.1 of the VLV Request packet:
40 *
41 * VirtualListViewRequest ::= SEQUENCE {
42 * beforeCount INTEGER (0..maxInt),
43 * afterCount INTEGER (0..maxInt),
44 * CHOICE {
45 * byoffset [0] SEQUENCE {
46 * offset INTEGER (0 .. maxInt),
47 * contentCount INTEGER (0 .. maxInt) },
48 * greaterThanOrEqual [1] AssertionValue },
49 * contextID OCTET STRING OPTIONAL }
50 *
51 */
52
53 /// <summary> LdapVirtualListControl is a Server Control used to specify
54 /// that results from a search are to be returned in pages - which are
55 /// subsets of the entire virtual result set.
56 ///
57 /// On success, an updated LdapVirtualListResponse object is
58 /// returned as a response Control, containing information on the virtual
59 /// list size and the actual first index. This object can then be used
60 /// by the client with a new requested position or length and sent to the
61 /// server to obtain a different segment of the virtual list.
62 ///
63 /// </summary>
64 public class LdapVirtualListControl:LdapControl
65 {
66 /// <summary> Returns the number of entries after the top/center one to return per
67 /// page of results.
68 /// </summary>
69 virtual public int AfterCount
70 {
71 get
72 {
73 return m_afterCount;
74 }
75
76 }
77 /// <summary> Returns the number of entries before the top/center one to return per
78 /// page of results.
79 /// </summary>
80 virtual public int BeforeCount
81 {
82 get
83 {
84 return m_beforeCount;
85 }
86
87 }
88 /// <summary> Returns the size of the virtual search results list. For a newly
89 /// constructed control - one which is not the result of parseResponse on
90 /// a control returned by a server - the method returns -1.
91 /// </summary>
92 /// <summary> Sets the assumed size of the virtual search results list. This will
93 /// typically be a number returned on a previous virtual list request in
94 /// an LdapVirtualListResponse.
95 /// </summary>
96 virtual public int ListSize
97 {
98 get
99 {
100 return m_contentCount;
101 }
102
103 set
104 {
105 m_contentCount = value;
106
107 /* since we just changed a field we need to rebuild the ber
108 * encoded control
109 */
110 BuildIndexedVLVRequest();
111
112 /* Set the request data field in the in the parent LdapControl to
113 * the ASN.1 encoded value of this control. This encoding will be
114 * appended to the search request when the control is sent.
115 */
116 setValue(m_vlvRequest.getEncoding(new LBEREncoder()));
117 }
118
119 }
120 /// <summary> Returns the cookie used by some servers to optimize the processing of
121 /// virtual list requests.
122 /// </summary>
123 /// <summary> Sets the cookie used by some servers to optimize the processing of
124 /// virtual list requests. It should be the context field returned in a
125 /// virtual list response control for the same search.
126 /// </summary>
127 virtual public System.String Context
128 {
129 get
130 {
131 return m_context;
132 }
133
134 set
135 {
136 /* Index of the context field if one exists in the ber
137 */
138 int CONTEXTIDINDEX = 3;
139
140 /* Save off the new value in private variable
141 */
142 m_context = value;
143
144 /* Is there a context field that is already in the ber
145 */
146 if (m_vlvRequest.size() == 4)
147 {
148 /* If YES then replace it */
149 m_vlvRequest.set_Renamed(CONTEXTIDINDEX, new Asn1OctetString(m_context));
150 }
151 else if (m_vlvRequest.size() == 3)
152 {
153 /* If no then add a new one */
154 m_vlvRequest.add(new Asn1OctetString(m_context));
155 }
156
157 /* Set the request data field in the in the parent LdapControl to
158 * the ASN.1 encoded value of this control. This encoding will be
159 * appended to the search request when the control is sent.
160 */
161 setValue(m_vlvRequest.getEncoding(new LBEREncoder()));
162 }
163
164 }
165
166 /* The ASN.1 for the VLV Request has CHOICE field. These private
167 * variables represent differnt ids for these different options
168 */
169 private static int BYOFFSET = 0;
170 private static int GREATERTHANOREQUAL = 1;
171
172
173 /// <summary> The Request OID for a VLV Request</summary>
174 private static System.String requestOID = "2.16.840.1.113730.3.4.9";
175
176 /*
177 * The Response stOID for a VLV Response
178 */
179 private static System.String responseOID = "2.16.840.1.113730.3.4.10";
180
181 /*
182 * The encoded ASN.1 VLV Control is stored in this variable
183 */
184 private Asn1Sequence m_vlvRequest;
185
186
187 /* Private instance variables go here.
188 * These variables are used to store copies of various fields
189 * that can be set in a VLV control. One could have managed
190 * without really defining these private variables by reverse
191 * engineering each field from the ASN.1 encoded control.
192 * However that would have complicated and slowed down the code.
193 */
194 private int m_beforeCount;
195 private int m_afterCount;
196 private System.String m_jumpTo;
197 private System.String m_context = null;
198 private int m_startIndex = 0;
199 private int m_contentCount = - 1;
200
201 /// <summary> Constructs a virtual list control using the specified filter
202 /// expression.
203 ///
204 /// The expression specifies the first entry to be used for the
205 /// virtual search results. The other two paramers are the number of
206 /// entries before and after a located index to be returned.
207 ///
208 /// </summary>
209 /// <param name="jumpTo"> A search expression that defines the first
210 /// element to be returned in the virtual search results. The filter
211 /// expression in the search operation itself may be, for example,
212 /// "objectclass=person" and the jumpTo expression in the virtual
213 /// list control may be "cn=m*", to retrieve a subset of entries
214 /// starting at or centered around those with a common name beginning
215 /// with the letter "M".
216 ///
217 /// </param>
218 /// <param name="beforeCount"> The number of entries before startIndex (the
219 /// reference entry) to be returned.
220 ///
221 /// </param>
222 /// <param name="afterCount"> The number of entries after startIndex to be
223 /// returned.
224 /// </param>
225 public LdapVirtualListControl(System.String jumpTo, int beforeCount, int afterCount):this(jumpTo, beforeCount, afterCount, null)
226 {
227 return ;
228 }
229
230
231
232 /// <summary> Constructs a virtual list control using the specified filter
233 /// expression along with an optional server context.
234 ///
235 /// The expression specifies the first entry to be used for the
236 /// virtual search results. The other two paramers are the number of
237 /// entries before and after a located index to be returned.
238 ///
239 /// </summary>
240 /// <param name="jumpTo"> A search expression that defines the first
241 /// element to be returned in the virtual search results. The filter
242 /// expression in the search operation itself may be, for example,
243 /// "objectclass=person" and the jumpTo expression in the virtual
244 /// list control may be "cn=m*", to retrieve a subset of entries
245 /// starting at or centered around those with a common name beginning
246 /// with the letter "M".
247 ///
248 /// </param>
249 /// <param name="beforeCount">The number of entries before startIndex (the
250 /// reference entry) to be returned.
251 ///
252 /// </param>
253 /// <param name="afterCount">The number of entries after startIndex to be
254 /// returned.
255 ///
256 /// </param>
257 /// <param name="context">Used by some implementations to process requests
258 /// more efficiently. The context should be null on the first search,
259 /// and thereafter it should be whatever was returned by the server in the
260 /// virtual list response control.
261 /// </param>
262 public LdapVirtualListControl(System.String jumpTo, int beforeCount, int afterCount, System.String context):base(requestOID, true, null)
263 {
264
265 /* Save off the fields in local variables
266 */
267 m_beforeCount = beforeCount;
268 m_afterCount = afterCount;
269 m_jumpTo = jumpTo;
270 m_context = context;
271
272 /* Call private method to build the ASN.1 encoded request packet.
273 */
274 BuildTypedVLVRequest();
275
276 /* Set the request data field in the in the parent LdapControl to
277 * the ASN.1 encoded value of this control. This encoding will be
278 * appended to the search request when the control is sent.
279 */
280 setValue(m_vlvRequest.getEncoding(new LBEREncoder()));
281 return ;
282 }
283
284 /// <summary>Private method used to construct the ber encoded control
285 /// Used only when using the typed mode of VLV Control.
286 /// </summary>
287 private void BuildTypedVLVRequest()
288 {
289 /* Create a new Asn1Sequence object */
290 m_vlvRequest = new Asn1Sequence(4);
291
292 /* Add the beforeCount and afterCount fields to the sequence */
293 m_vlvRequest.add(new Asn1Integer(m_beforeCount));
294 m_vlvRequest.add(new Asn1Integer(m_afterCount));
295
296 /* The next field is dependent on the type of indexing being used.
297 * A "typed" VLV request uses a ASN.1 OCTET STRING to index to the
298 * correct object in the list. Encode the ASN.1 CHOICE corresponding
299 * to this option (as indicated by the greaterthanOrEqual field)
300 * in the ASN.1.
301 */
302 m_vlvRequest.add(new Asn1Tagged(new Asn1Identifier(Asn1Identifier.CONTEXT, false, GREATERTHANOREQUAL), new Asn1OctetString(m_jumpTo), false));
303
304 /* Add the optional context string if one is available.
305 */
306 if ((System.Object) m_context != null)
307 m_vlvRequest.add(new Asn1OctetString(m_context));
308
309 return ;
310 }
311
312 /// <summary> Use this constructor to fetch a subset when the size of the
313 /// virtual list is known,
314 ///
315 ///
316 /// </summary>
317 /// <param name="beforeCount">The number of entries before startIndex (the
318 /// reference entry) to be returned.
319 ///
320 /// </param>
321 /// <param name="afterCount"> The number of entries after startIndex to be
322 /// returned.
323 ///
324 /// </param>
325 /// <param name="startIndex">The index of the reference entry to be returned.
326 ///
327 /// </param>
328 /// <param name="contentCount">The total number of entries assumed to be in the
329 /// list. This is a number returned on a previous search, in the
330 /// LdapVirtualListResponse. The server may use this number to adjust
331 /// the returned subset offset.
332 /// </param>
333 public LdapVirtualListControl(int startIndex, int beforeCount, int afterCount, int contentCount):this(startIndex, beforeCount, afterCount, contentCount, null)
334 {
335 return ;
336 }
337
338
339
340 /// <summary> Use this constructor to fetch a subset when the size of the
341 /// virtual list is known,
342 ///
343 ///
344 /// </summary>
345 /// <param name="beforeCount"> The number of entries before startIndex (the
346 /// reference entry) to be returned.
347 ///
348 /// </param>
349 /// <param name="afterCount"> The number of entries after startIndex to be
350 /// returned.
351 ///
352 /// </param>
353 /// <param name="startIndex"> The index of the reference entry to be
354 /// returned.
355 ///
356 /// </param>
357 /// <param name="contentCount"> The total number of entries assumed to be in the
358 /// list. This is a number returned on a previous search, in the
359 /// LdapVirtualListResponse. The server may use this number to adjust
360 /// the returned subset offset.
361 ///
362 /// </param>
363 /// <param name="context"> Used by some implementations to process requests
364 /// more efficiently. The context should be null on the first search,
365 /// and thereafter it should be whatever was returned by the server in the
366 /// virtual list response control.
367 /// </param>
368 public LdapVirtualListControl(int startIndex, int beforeCount, int afterCount, int contentCount, System.String context):base(requestOID, true, null)
369 {
370
371
372 /* Save off the fields in local variables
373 */
374 m_beforeCount = beforeCount;
375 m_afterCount = afterCount;
376 m_startIndex = startIndex;
377 m_contentCount = contentCount;
378 m_context = context;
379
380 /* Call private method to build the ASN.1 encoded request packet.
381 */
382 BuildIndexedVLVRequest();
383
384 /* Set the request data field in the in the parent LdapControl to
385 * the ASN.1 encoded value of this control. This encoding will be
386 * appended to the search request when the control is sent.
387 */
388 setValue(m_vlvRequest.getEncoding(new LBEREncoder()));
389 return ;
390 }
391
392 /// <summary>Private method used to construct the ber encoded control
393 /// Used only when using the Indexed mode of VLV Control
394 /// </summary>
395 private void BuildIndexedVLVRequest()
396 {
397 /* Create a new Asn1Sequence object */
398 m_vlvRequest = new Asn1Sequence(4);
399
400 /* Add the beforeCount and afterCount fields to the sequence */
401 m_vlvRequest.add(new Asn1Integer(m_beforeCount));
402 m_vlvRequest.add(new Asn1Integer(m_afterCount));
403
404 /* The next field is dependent on the type of indexing being used.
405 * An "indexed" VLV request uses a ASN.1 SEQUENCE to index to the
406 * correct object in the list. Encode the ASN.1 CHOICE corresponding
407 * to this option (as indicated by the byoffset fieldin the ASN.1.
408 */
409 Asn1Sequence byoffset = new Asn1Sequence(2);
410 byoffset.add(new Asn1Integer(m_startIndex));
411 byoffset.add(new Asn1Integer(m_contentCount)); ;
412
413 /* Add the ASN.1 sequence to the encoded data
414 */
415 m_vlvRequest.add(new Asn1Tagged(new Asn1Identifier(Asn1Identifier.CONTEXT, true, BYOFFSET), byoffset, false));
416
417 /* Add the optional context string if one is available.
418 */
419 if ((System.Object) m_context != null)
420 m_vlvRequest.add(new Asn1OctetString(m_context));
421
422 return ;
423 }
424
425
426
427 /// <summary> Sets the center or starting list index to return, and the number of
428 /// results before and after.
429 ///
430 ///
431 /// </summary>
432 /// <param name="listIndex"> The center or starting list index to be
433 /// returned.
434 ///
435 /// </param>
436 /// <param name="beforeCount"> The number of entries before "listIndex" to be
437 /// returned.
438 ///
439 /// </param>
440 /// <param name="afterCount"> The number of entries after "listIndex" to be
441 /// returned.
442 /// </param>
443 public virtual void setRange(int listIndex, int beforeCount, int afterCount)
444 {
445
446 /* Save off the fields in local variables
447 */
448 m_beforeCount = beforeCount;
449 m_afterCount = afterCount;
450 m_startIndex = listIndex;
451
452 /* since we just changed a field we need to rebuild the ber
453 * encoded control
454 */
455 BuildIndexedVLVRequest();
456
457 /* Set the request data field in the in the parent LdapControl to
458 * the ASN.1 encoded value of this control. This encoding will be
459 * appended to the search request when the control is sent.
460 */
461 setValue(m_vlvRequest.getEncoding(new LBEREncoder()));
462 }
463
464 // PROPOSED ADDITION TO NEXT VERSION OF DRAFT (v7)
465 /// <summary> Sets the center or starting list index to return, and the number of
466 /// results before and after.
467 ///
468 ///
469 /// </summary>
470 /// <param name="jumpTo">A search expression that defines the first
471 /// element to be returned in the virtual search results. The filter
472 /// expression in the search operation itself may be, for example,
473 /// "objectclass=person" and the jumpTo expression in the virtual
474 /// list control may be "cn=m*", to retrieve a subset of entries
475 /// starting at or centered around those with a common name
476 /// beginning with the letter "M".
477 ///
478 /// </param>
479 /// <param name="beforeCount"> The number of entries before "listIndex" to be
480 /// returned.
481 ///
482 /// </param>
483 /// <param name="afterCount">The number of entries after "listIndex" to be
484 /// returned.
485 /// </param>
486
487 public virtual void setRange(System.String jumpTo, int beforeCount, int afterCount)
488 {
489 /* Save off the fields in local variables
490 */
491 m_beforeCount = beforeCount;
492 m_afterCount = afterCount;
493 m_jumpTo = jumpTo;
494
495 /* since we just changed a field we need to rebuild the ber
496 * encoded control
497 */
498 BuildTypedVLVRequest();
499
500 /* Set the request data field in the in the parent LdapControl to
501 * the ASN.1 encoded value of this control. This encoding will be
502 * appended to the search request when the control is sent.
503 */
504 setValue(m_vlvRequest.getEncoding(new LBEREncoder()));
505 }
506 static LdapVirtualListControl()
507 {
508 /*
509 * This is where we register the control responses
510 */
511 {
512 /* Register the VLV Sort Control class which is returned by the server
513 * in response to a VLV Sort Request
514 */
515 try
516 {
517 LdapControl.register(responseOID, System.Type.GetType("Novell.Directory.Ldap.Controls.LdapVirtualListResponse"));
518 }
519 catch (System.Exception e)
520 {
521 }
522 }
523 }
524 }
525 }
git-svn mirror of mcs