1 /******************************************************************************
3 * Copyright (c) 2003 Novell Inc. www.novell.com
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:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
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
22 *******************************************************************************/
24 // Novell.Directory.Ldap.LdapSearchRequest.cs
27 // Sunil Kumar (Sunilk@novell.com)
29 // (C) 2003 Novell, Inc (http://www.novell.com)
33 using Novell.Directory.Ldap.Asn1;
34 using Novell.Directory.Ldap.Rfc2251;
36 namespace Novell.Directory.Ldap
39 /// <summary> Represents an Ldap Search request.
42 /// <seealso cref="LdapConnection.SendRequest">
45 * SearchRequest ::= [APPLICATION 3] SEQUENCE {
51 * derefAliases ENUMERATED {
52 * neverDerefAliases (0),
53 * derefInSearching (1),
54 * derefFindingBaseObj (2),
56 * sizeLimit INTEGER (0 .. maxInt),
57 * timeLimit INTEGER (0 .. maxInt),
60 * attributes AttributeDescriptionList }
62 public class LdapSearchRequest:LdapMessage
64 /// <summary> Retrieves the Base DN for a search request.
67 /// <returns> the base DN for a search request
69 virtual public System.String DN
73 return Asn1Object.RequestDN;
77 /// <summary> Retrieves the scope of a search request.</summary>
78 /// <returns> scope of a search request
81 /// <seealso cref="Novell.Directory.Ldap.LdapConnection.SCOPE_BASE">
83 /// <seealso cref="Novell.Directory.Ldap.LdapConnection.SCOPE_ONE">
85 /// <seealso cref="Novell.Directory.Ldap.LdapConnection.SCOPE_SUB">
87 virtual public int Scope
91 //element number one stores the scope
92 return ((Asn1Enumerated) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(1)).intValue();
96 /// <summary> Retrieves the behaviour of dereferencing aliases on a search request.</summary>
97 /// <returns> integer representing how to dereference aliases
100 /// <seealso cref="Novell.Directory.Ldap.LdapSearchConstraints.DEREF_ALWAYS">
102 /// <seealso cref="Novell.Directory.Ldap.LdapSearchConstraints.DEREF_FINDING">
104 /// <seealso cref="Novell.Directory.Ldap.LdapSearchConstraints.DEREF_NEVER">
106 /// <seealso cref="Novell.Directory.Ldap.LdapSearchConstraints.DEREF_SEARCHING">
108 virtual public int Dereference
112 //element number two stores the dereference
113 return ((Asn1Enumerated) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(2)).intValue();
117 /// <summary> Retrieves the maximum number of entries to be returned on a search.
120 /// <returns> Maximum number of search entries.
122 virtual public int MaxResults
126 //element number three stores the max results
127 return ((Asn1Integer) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(3)).intValue();
131 /// <summary> Retrieves the server time limit for a search request.
134 /// <returns> server time limit in nanoseconds.
136 virtual public int ServerTimeLimit
140 //element number four stores the server time limit
141 return ((Asn1Integer) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(4)).intValue();
145 /// <summary> Retrieves whether attribute values or only attribute types(names) should
146 /// be returned in a search request.
148 /// <returns> true if only attribute types (names) are returned, false if
149 /// attributes types and values are to be returned.
151 virtual public bool TypesOnly
155 //element number five stores types value
156 return ((Asn1Boolean) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(5)).booleanValue();
160 /// <summary> Retrieves an array of attribute names to request for in a search.</summary>
161 /// <returns> Attribute names to be searched
163 virtual public System.String[] Attributes
167 RfcAttributeDescriptionList attrs = (RfcAttributeDescriptionList) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(7);
169 System.String[] rAttrs = new System.String[attrs.size()];
170 for (int i = 0; i < rAttrs.Length; i++)
172 rAttrs[i] = ((RfcAttributeDescription) attrs.get_Renamed(i)).stringValue();
178 /// <summary> Creates a string representation of the filter in this search request.</summary>
179 /// <returns> filter string for this search request
181 virtual public System.String StringFilter
185 return this.RfcFilter.filterToString();
189 /// <summary> Retrieves an SearchFilter object representing a filter for a search request</summary>
190 /// <returns> filter object for a search request.
192 private RfcFilter RfcFilter
196 return (RfcFilter) ((RfcSearchRequest) (this.Asn1Object).get_Renamed(1)).get_Renamed(6);
200 /// <summary> Retrieves an Iterator object representing the parsed filter for
201 /// this search request.
203 /// The first object returned from the Iterator is an Integer indicating
204 /// the type of filter component. One or more values follow the component
205 /// type as subsequent items in the Iterator. The pattern of Integer
206 /// component type followed by values continues until the end of the
209 /// Values returned as a byte array may represent UTF-8 characters or may
210 /// be binary values. The possible Integer components of a search filter
211 /// and the associated values that follow are:
213 /// <li>AND - followed by an Iterator value</li>
214 /// <li>OR - followed by an Iterator value</li>
215 /// <li>NOT - followed by an Iterator value</li>
216 /// <li>EQUALITY_MATCH - followed by the attribute name represented as a
217 /// String, and by the attribute value represented as a byte array</li>
218 /// <li>GREATER_OR_EQUAL - followed by the attribute name represented as a
219 /// String, and by the attribute value represented as a byte array</li>
220 /// <li>LESS_OR_EQUAL - followed by the attribute name represented as a
221 /// String, and by the attribute value represented as a byte array</li>
222 /// <li>APPROX_MATCH - followed by the attribute name represented as a
223 /// String, and by the attribute value represented as a byte array</li>
224 /// <li>PRESENT - followed by a attribute name respresented as a String</li>
225 /// <li>EXTENSIBLE_MATCH - followed by the name of the matching rule
226 /// represented as a String, by the attribute name represented
227 /// as a String, and by the attribute value represented as a
229 /// <li>SUBSTRINGS - followed by the attribute name represented as a
230 /// String, by one or more SUBSTRING components (INITIAL, ANY,
231 /// or FINAL) followed by the SUBSTRING value.</li>
235 /// <returns> Iterator representing filter components
237 virtual public System.Collections.IEnumerator SearchFilter
241 return RfcFilter.getFilterIterator();
245 //*************************************************************************
246 // Public variables for Filter
247 //*************************************************************************
249 /// <summary> Search Filter Identifier for an AND component.</summary>
250 public const int AND = 0;
251 /// <summary> Search Filter Identifier for an OR component.</summary>
252 public const int OR = 1;
253 /// <summary> Search Filter Identifier for a NOT component.</summary>
254 public const int NOT = 2;
255 /// <summary> Search Filter Identifier for an EQUALITY_MATCH component.</summary>
256 public const int EQUALITY_MATCH = 3;
257 /// <summary> Search Filter Identifier for a SUBSTRINGS component.</summary>
258 public const int SUBSTRINGS = 4;
259 /// <summary> Search Filter Identifier for a GREATER_OR_EQUAL component.</summary>
260 public const int GREATER_OR_EQUAL = 5;
261 /// <summary> Search Filter Identifier for a LESS_OR_EQUAL component.</summary>
262 public const int LESS_OR_EQUAL = 6;
263 /// <summary> Search Filter Identifier for a PRESENT component.</summary>
264 public const int PRESENT = 7;
265 /// <summary> Search Filter Identifier for an APPROX_MATCH component.</summary>
266 public const int APPROX_MATCH = 8;
267 /// <summary> Search Filter Identifier for an EXTENSIBLE_MATCH component.</summary>
268 public const int EXTENSIBLE_MATCH = 9;
270 /// <summary> Search Filter Identifier for an INITIAL component of a SUBSTRING.
271 /// Note: An initial SUBSTRING is represented as "value*".
273 public const int INITIAL = 0;
274 /// <summary> Search Filter Identifier for an ANY component of a SUBSTRING.
275 /// Note: An ANY SUBSTRING is represented as "*value*".
277 public const int ANY = 1;
278 /// <summary> Search Filter Identifier for a FINAL component of a SUBSTRING.
279 /// Note: A FINAL SUBSTRING is represented as "*value".
281 public const int FINAL = 2;
283 /// <summary> Constructs an Ldap Search Request.
286 /// <param name="base"> The base distinguished name to search from.
289 /// <param name="scope"> The scope of the entries to search. The following
290 /// are the valid options:
292 /// <li>SCOPE_BASE - searches only the base DN</li>
294 /// <li>SCOPE_ONE - searches only entries under the base DN</li>
296 /// <li>SCOPE_SUB - searches the base DN and all entries
297 /// within its subtree</li>
300 /// <param name="filter"> The search filter specifying the search criteria.
303 /// <param name="attrs"> The names of attributes to retrieve.
304 /// operation exceeds the time limit.
307 /// <param name="dereference">Specifies when aliases should be dereferenced.
308 /// Must be one of the constants defined in
309 /// LdapConstraints, which are DEREF_NEVER,
310 /// DEREF_FINDING, DEREF_SEARCHING, or DEREF_ALWAYS.
313 /// <param name="maxResults">The maximum number of search results to return
314 /// for a search request.
315 /// The search operation will be terminated by the server
316 /// with an LdapException.SIZE_LIMIT_EXCEEDED if the
317 /// number of results exceed the maximum.
320 /// <param name="serverTimeLimit">The maximum time in seconds that the server
321 /// should spend returning search results. This is a
322 /// server-enforced limit. A value of 0 means
326 /// <param name="typesOnly"> If true, returns the names but not the values of
327 /// the attributes found. If false, returns the
328 /// names and values for attributes found.
331 /// <param name="cont"> Any controls that apply to the search request.
335 /// <seealso cref="Novell.Directory.Ldap.LdapConnection.Search">
337 /// <seealso cref="Novell.Directory.Ldap.LdapSearchConstraints">
339 public LdapSearchRequest(System.String base_Renamed, int scope, System.String filter, System.String[] attrs, int dereference, int maxResults, int serverTimeLimit, bool typesOnly, LdapControl[] cont):base(LdapMessage.SEARCH_REQUEST, new RfcSearchRequest(new RfcLdapDN(base_Renamed), new Asn1Enumerated(scope), new Asn1Enumerated(dereference), new Asn1Integer(maxResults), new Asn1Integer(serverTimeLimit), new Asn1Boolean(typesOnly), new RfcFilter(filter), new RfcAttributeDescriptionList(attrs)), cont)
344 /// <summary> Constructs an Ldap Search Request with a filter in Asn1 format.
347 /// <param name="base"> The base distinguished name to search from.
350 /// <param name="scope"> The scope of the entries to search. The following
351 /// are the valid options:
353 /// <li>SCOPE_BASE - searches only the base DN</li>
355 /// <li>SCOPE_ONE - searches only entries under the base DN</li>
357 /// <li>SCOPE_SUB - searches the base DN and all entries
358 /// within its subtree</li>
361 /// <param name="filter"> The search filter specifying the search criteria.
364 /// <param name="attrs"> The names of attributes to retrieve.
365 /// operation exceeds the time limit.
368 /// <param name="dereference">Specifies when aliases should be dereferenced.
369 /// Must be either one of the constants defined in
370 /// LdapConstraints, which are DEREF_NEVER,
371 /// DEREF_FINDING, DEREF_SEARCHING, or DEREF_ALWAYS.
374 /// <param name="maxResults">The maximum number of search results to return
375 /// for a search request.
376 /// The search operation will be terminated by the server
377 /// with an LdapException.SIZE_LIMIT_EXCEEDED if the
378 /// number of results exceed the maximum.
381 /// <param name="serverTimeLimit">The maximum time in seconds that the server
382 /// should spend returning search results. This is a
383 /// server-enforced limit. A value of 0 means
387 /// <param name="typesOnly"> If true, returns the names but not the values of
388 /// the attributes found. If false, returns the
389 /// names and values for attributes found.
392 /// <param name="cont"> Any controls that apply to the search request.
396 /// <seealso cref="Novell.Directory.Ldap.LdapConnection.Search">
398 /// <seealso cref="Novell.Directory.Ldap.LdapSearchConstraints">
400 public LdapSearchRequest(System.String base_Renamed, int scope, RfcFilter filter, System.String[] attrs, int dereference, int maxResults, int serverTimeLimit, bool typesOnly, LdapControl[] cont):base(LdapMessage.SEARCH_REQUEST, new RfcSearchRequest(new RfcLdapDN(base_Renamed), new Asn1Enumerated(scope), new Asn1Enumerated(dereference), new Asn1Integer(maxResults), new Asn1Integer(serverTimeLimit), new Asn1Boolean(typesOnly), filter, new RfcAttributeDescriptionList(attrs)), cont)