mcs/class/Novell.Directory.Ldap/Novell.Directory.Ldap/LdapSearchConstraints.cs

   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.LdapSearchConstraints.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
  34 namespace Novell.Directory.Ldap
  35 {
  36
  37         /// <summary>
  38         /// Defines the options controlling search operations.
  39         ///
  40         /// An LdapSearchConstraints object is always associated with an
  41         /// LdapConnection object; its values can be changed with the
  42         /// LdapConnection.setConstraints method, or overridden by passing
  43         /// an LdapSearchConstraints object to the search operation.
  44         ///
  45         /// </summary>
  46         /// <seealso cref="LdapConstraints">
  47         /// </seealso>
  48         /// <seealso cref="LdapConnection.Constraints">
  49         /// </seealso>
  50         public class LdapSearchConstraints:LdapConstraints
  51         {
  52                 private void  InitBlock()
  53                 {
  54                         dereference = DEREF_NEVER;
  55                 }
  56                 /// <summary> Returns the number of results to block on during receipt of search
  57                 /// results.
  58                 ///
  59                 /// This should be 0 if intermediate reults are not needed,
  60                 /// and 1 if results are to be processed as they come in. A value of
  61                 /// indicates block until all results are received.  Default:
  62                 ///
  63                 /// </summary>
  64                 /// <returns> The the number of results to block on.
  65                 ///
  66                 /// </returns>
  67                 /// <seealso cref="BatchSize">
  68                 /// </seealso>
  69                 /// <summary>  Specifies the number of results to return in a batch.
  70                 /// Specifying 0 means to block until all results are received.
  71                 /// Specifying 1 means to return results one result at a time.  Default: 1
  72                 ///
  73                 ///
  74                 /// This should be 0 if intermediate results are not needed,
  75                 /// and 1 if results are to be processed as they come in.  The
  76                 /// default is 1.
  77                 ///
  78                 /// </summary>
  79                 /// <param name="batchSize">     The number of results to block on.
  80                 ///
  81                 /// </param>
  82                 /// <seealso cref="BatchSize">
  83                 /// </seealso>
  84                 virtual public int BatchSize
  85                 {
  86                         get
  87                         {
  88                                 return batchSize;
  89                         }
  90
  91                         set
  92                         {
  93                                 this.batchSize = value;
  94                                 return ;
  95                         }
  96
  97                 }
  98                 /// <summary> Specifies when aliases should be dereferenced.
  99                 ///
 100                 /// Returns one of the following:
 101                 /// <ul>
 102                 /// <li>DEREF_NEVER</li>
 103                 /// <li>DEREF_FINDING</li>
 104                 /// <li>DEREF_SEARCHING</li>
 105                 /// <li>DEREF_ALWAYS</li>
 106                 /// </ul>
 107                 ///
 108                 /// </summary>
 109                 /// <returns> The setting for dereferencing aliases.
 110                 ///
 111                 /// </returns>
 112                 /// <seealso cref="Dereference">
 113                 /// </seealso>
 114                 /// <summary> Sets a preference indicating whether or not aliases should be
 115                 /// dereferenced, and if so, when.
 116                 ///
 117                 ///
 118                 /// </summary>
 119                 /// <param name="dereference"> Specifies how aliases are dereference and can be set
 120                 /// to one of the following:
 121                 /// <ul>
 122                 /// <li>DEREF_NEVER - do not dereference aliases</li>
 123                 /// <li>DEREF_FINDING - dereference aliases when finding
 124                 /// the base object to start the search</li>
 125                 /// <li>DEREF_SEARCHING - dereference aliases when
 126                 /// searching but not when finding the base
 127                 /// object to start the search</li>
 128                 /// <li>DEREF_ALWAYS - dereference aliases when finding
 129                 /// the base object and when searching</li>
 130                 /// </ul>
 131                 ///
 132                 /// </param>
 133                 /// <seealso cref="Dereference">
 134                 /// </seealso>
 135                 virtual public int Dereference
 136                 {
 137                         get
 138                         {
 139                                 return dereference;
 140                         }
 141
 142                         set
 143                         {
 144                                 this.dereference = value;
 145                                 return ;
 146                         }
 147
 148                 }
 149                 /// <summary> Returns the maximum number of search results to be returned for
 150                 /// a search operation. A value of 0 means no limit.  Default: 1000
 151                 /// The search operation will be terminated with an
 152                 /// LdapException.SIZE_LIMIT_EXCEEDED if the number of results
 153                 /// exceed the maximum.
 154                 ///
 155                 /// </summary>
 156                 /// <returns> The value for the maximum number of results to return.
 157                 ///
 158                 /// </returns>
 159                 /// <seealso cref="MaxResults">
 160                 /// </seealso>
 161                 /// <seealso cref="LdapException.SIZE_LIMIT_EXCEEDED">
 162                 /// </seealso>
 163                 /// <summary> Sets the maximum number of search results to be returned from a
 164                 /// search operation. The value 0 means no limit.  The default is 1000.
 165                 /// The search operation will be terminated with an
 166                 /// LdapException.SIZE_LIMIT_EXCEEDED if the number of results
 167                 /// exceed the maximum.
 168                 ///
 169                 /// </summary>
 170                 /// <param name="maxResults">    Maximum number of search results to return.
 171                 ///
 172                 /// </param>
 173                 /// <seealso cref="MaxResults">
 174                 /// </seealso>
 175                 /// <seealso cref="LdapException.SIZE_LIMIT_EXCEEDED">
 176                 /// </seealso>
 177                 virtual public int MaxResults
 178                 {
 179                         get
 180                         {
 181                                 return maxResults;
 182                         }
 183
 184                         set
 185                         {
 186                                 this.maxResults = value;
 187                                 return ;
 188                         }
 189
 190                 }
 191                 /// <summary> Returns the maximum number of seconds that the server waits when
 192                 /// returning search results.
 193                 /// The search operation will be terminated with an
 194                 /// LdapException.TIME_LIMIT_EXCEEDED if the operation exceeds the time
 195                 /// limit.
 196                 ///
 197                 /// </summary>
 198                 /// <returns> The maximum number of seconds the server waits for search'
 199                 /// results.
 200                 ///
 201                 /// </returns>
 202                 /// <seealso cref="ServerTimeLimit">
 203                 /// </seealso>
 204                 /// <seealso cref="LdapException.TIME_LIMIT_EXCEEDED">
 205                 /// </seealso>
 206                 /// <summary> Sets the maximum number of seconds that the server is to wait when
 207                 /// returning search results.
 208                 /// The search operation will be terminated with an
 209                 /// LdapException.TIME_LIMIT_EXCEEDED if the operation exceeds the time
 210                 /// limit.
 211                 ///
 212                 /// The parameter is only recognized on search operations.
 213                 ///
 214                 /// </summary>
 215                 /// <param name="seconds">The number of seconds to wait for search results.
 216                 ///
 217                 /// </param>
 218                 /// <seealso cref="ServerTimeLimit">
 219                 /// </seealso>
 220                 /// <seealso cref="LdapException.TIME_LIMIT_EXCEEDED">
 221                 /// </seealso>
 222                 virtual public int ServerTimeLimit
 223                 {
 224                         get
 225                         {
 226                                 return serverTimeLimit;
 227                         }
 228
 229                         set
 230                         {
 231                                 this.serverTimeLimit = value;
 232                                 return ;
 233                         }
 234
 235                 }
 236
 237                 private int dereference;
 238                 private int serverTimeLimit = 0;
 239                 private int maxResults = 1000;
 240                 private int batchSize = 1;
 241                 new private static System.Object nameLock; // protect agentNum
 242                 private static int lSConsNum = 0; // Debug, LdapConnection number
 243                 new private System.String name; // String name for debug
 244
 245                 /// <summary> Indicates that aliases are never dereferenced.
 246                 ///
 247                 ///  DEREF_NEVER = 0
 248                 ///
 249                 /// </summary>
 250                 /// <seealso cref="Dereference">
 251                 /// </seealso>
 252                 /// <seealso cref="Dereference">
 253                 /// </seealso>
 254                 public const int DEREF_NEVER = 0;
 255
 256                 /// <summary> Indicates that aliases are are derefrenced when
 257                 /// searching the entries beneath the starting point of the search,
 258                 /// but not when finding the starting entry.
 259                 ///
 260                 ///  DEREF_SEARCHING = 1
 261                 ///
 262                 /// </summary>
 263                 /// <seealso cref="Dereference">
 264                 /// </seealso>
 265                 /// <seealso cref="Dereference">
 266                 /// </seealso>
 267                 public const int DEREF_SEARCHING = 1;
 268
 269                 /// <summary> Indicates that aliases are dereferenced when
 270                 /// finding the starting point for the search,
 271                 /// but not when searching under that starting entry.
 272                 ///
 273                 ///  DEREF_FINDING = 2
 274                 ///
 275                 /// </summary>
 276                 /// <seealso cref="Dereference">
 277                 /// </seealso>
 278                 /// <seealso cref="Dereference">
 279                 /// </seealso>
 280                 public const int DEREF_FINDING = 2;
 281
 282                 /// <summary> Indicates that aliases are always dereferenced, both when
 283                 /// finding the starting point for the search, and also when
 284                 /// searching the entries beneath the starting entry.
 285                 ///
 286                 ///  DEREF_ALWAYS = 3
 287                 ///
 288                 /// </summary>
 289                 /// <seealso cref="Dereference">
 290                 /// </seealso>
 291                 /// <seealso cref="Dereference">
 292                 /// </seealso>
 293                 public const int DEREF_ALWAYS = 3;
 294
 295                 /// <summary> Constructs an LdapSearchConstraints object with a default set
 296                 /// of search constraints.
 297                 /// </summary>
 298                 public LdapSearchConstraints():base()
 299                 {
 300                         InitBlock();
 301                         // Get a unique connection name for debug
 302                 }
 303
 304                 /// <summary> Constructs an LdapSearchConstraints object initialized with values
 305                 /// from an existing constraints object (LdapConstraints
 306                 /// or LdapSearchConstraints).
 307                 /// </summary>
 308                 public LdapSearchConstraints(LdapConstraints cons):base(cons.TimeLimit, cons.ReferralFollowing, cons.getReferralHandler(), cons.HopLimit)
 309                 {
 310                         InitBlock();
 311                         LdapControl[] lsc = cons.getControls();
 312                         if (lsc != null)
 313                         {
 314                                 LdapControl[] generated_var = new LdapControl[lsc.Length];
 315                                 lsc.CopyTo(generated_var, 0);
 316                                 base.setControls(generated_var);
 317                         }
 318                         System.Collections.Hashtable lp = cons.Properties;
 319                         if (lp != null)
 320                         {
 321                                 base.Properties = (System.Collections.Hashtable) lp.Clone();
 322                         }
 323
 324                         if (cons is LdapSearchConstraints)
 325                         {
 326                                 LdapSearchConstraints scons = (LdapSearchConstraints) cons;
 327                                 this.serverTimeLimit = scons.ServerTimeLimit;
 328                                 this.dereference = scons.Dereference;
 329                                 this.maxResults = scons.MaxResults;
 330                                 this.batchSize = scons.BatchSize;
 331                         }
 332                         // Get a unique connection name for debug
 333                         return ;
 334                 }
 335
 336                 /// <summary> Constructs a new LdapSearchConstraints object and allows the
 337                 /// specification operational constraints in that object.
 338                 ///
 339                 /// </summary>
 340                 /// <param name="msLimit"> The maximum time in milliseconds to wait for results.
 341                 /// The default is 0, which means that there is no
 342                 /// maximum time limit. This limit is enforced for an
 343                 /// operation by the API, not by the server.
 344                 /// The operation will be abandoned and terminated by the
 345                 /// API with an LdapException.Ldap_TIMEOUT if the
 346                 /// operation exceeds the time limit.
 347                 ///
 348                 /// </param>
 349                 /// <param name="serverTimeLimit">The maximum time in seconds that the server
 350                 /// should spend returning search results. This is a
 351                 /// server-enforced limit.  The default of 0 means
 352                 /// no time limit.
 353                 /// The operation will be terminated by the server with an
 354                 /// LdapException.TIME_LIMIT_EXCEEDED if the search
 355                 /// operation exceeds the time limit.
 356                 ///
 357                 /// </param>
 358                 /// <param name="dereference">Specifies when aliases should be dereferenced.
 359                 /// Must be either DEREF_NEVER, DEREF_FINDING,
 360                 /// DEREF_SEARCHING, or DEREF_ALWAYS from this class.
 361                 /// Default: DEREF_NEVER
 362                 ///
 363                 /// </param>
 364                 /// <param name="maxResults">The maximum number of search results to return
 365                 /// for a search request.
 366                 /// The search operation will be terminated by the server
 367                 /// with an LdapException.SIZE_LIMIT_EXCEEDED if the
 368                 /// number of results exceed the maximum.
 369                 /// Default: 1000
 370                 ///
 371                 /// </param>
 372                 /// <param name="doReferrals">Determines whether to automatically follow
 373                 /// referrals or not. Specify true to follow
 374                 /// referrals automatically, and false to throw
 375                 /// an LdapException.REFERRAL if the server responds
 376                 /// with a referral.
 377                 /// It is ignored for asynchronous operations.
 378                 /// Default: false
 379                 ///
 380                 /// </param>
 381                 /// <param name="batchSize">The number of results to return in a batch. Specifying
 382                 /// 0 means to block until all results are received.
 383                 /// Specifying 1 means to return results one result at a
 384                 /// time.  Default: 1
 385                 ///
 386                 ///
 387                 /// </param>
 388                 /// <param name="handler">  The custom authentication handler called when
 389                 /// LdapConnection needs to authenticate, typically on
 390                 /// following a referral.  A null may be specified to
 391                 /// indicate default authentication processing, i.e.
 392                 /// referrals are followed with anonymous authentication.
 393                 /// ThE object may be an implemention of either the
 394                 /// the LdapBindHandler or LdapAuthHandler interface.
 395                 /// It is ignored for asynchronous operations.
 396                 ///
 397                 /// </param>
 398                 /// <param name="hop_limit">The maximum number of referrals to follow in a
 399                 /// sequence during automatic referral following.
 400                 /// The default value is 10. A value of 0 means no limit.
 401                 /// It is ignored for asynchronous operations.
 402                 /// The operation will be abandoned and terminated by the
 403                 /// API with an LdapException.REFERRAL_LIMIT_EXCEEDED if the
 404                 /// number of referrals in a sequence exceeds the limit.
 405                 ///
 406                 /// </param>
 407                 /// <seealso cref="LdapException.Ldap_TIMEOUT">
 408                 /// </seealso>
 409                 /// <seealso cref="LdapException.REFERRAL">
 410                 /// </seealso>
 411                 /// <seealso cref="LdapException.SIZE_LIMIT_EXCEEDED">
 412                 /// </seealso>
 413                 /// <seealso cref="LdapException.TIME_LIMIT_EXCEEDED">
 414                 /// </seealso>
 415                 public LdapSearchConstraints(int msLimit, int serverTimeLimit, int dereference, int maxResults, bool doReferrals, int batchSize, LdapReferralHandler handler, int hop_limit):base(msLimit, doReferrals, handler, hop_limit)
 416                 {
 417                         InitBlock();
 418                         this.serverTimeLimit = serverTimeLimit;
 419                         this.dereference = dereference;
 420                         this.maxResults = maxResults;
 421                         this.batchSize = batchSize;
 422                         // Get a unique connection name for debug
 423                         return ;
 424                 }
 425                 static LdapSearchConstraints()
 426                 {
 427                         nameLock = new System.Object();
 428                 }
 429         }
 430 }