mcs/class/Novell.Directory.Ldap/Novell.Directory.Ldap/LdapModification.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.LdapModification.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> A single add, delete, or replace operation to an LdapAttribute.
  38         ///
  39         /// An LdapModification contains information on the type of modification
  40         /// being performed, the name of the attribute to be replaced, and the new
  41         /// value.  Multiple modifications are expressed as an array of modifications,
  42         /// i.e., <code>LdapModification[]</code>.
  43         ///
  44         /// An LdapModification or an LdapModification array enable you to modify
  45         /// an attribute of an Ldap entry. The entire array of modifications must
  46         /// be performed by the server as a single atomic operation in the order they
  47         /// are listed. No changes are made to the directory unless all the operations
  48         /// succeed. If all succeed, a success result is returned to the application.
  49         /// It should be noted that if the connection fails during a modification,
  50         /// it is indeterminate whether the modification occurred or not.
  51         ///
  52         /// There are three types of modification operations: Add, Delete,
  53         /// and Replace.
  54         ///
  55         /// <b>Add: </b>Creates the attribute if it doesn't exist, and adds
  56         /// the specified values. This operation must contain at least one value, and
  57         /// all values of the attribute must be unique.
  58         ///
  59         /// <b>Delete: </b>Deletes specified values from the attribute. If no
  60         /// values are specified, or if all existing values of the attribute are
  61         /// specified, the attribute is removed. Mandatory attributes cannot be
  62         /// removed.
  63         ///
  64         /// <b>Replace: </b>Creates the attribute if necessary, and replaces
  65         /// all existing values of the attribute with the specified values.
  66         /// If you wish to keep any existing values of a multi-valued attribute,
  67         /// you must include these values in the replace operation.
  68         /// A replace operation with no value will remove the entire attribute if it
  69         /// exists, and is ignored if the attribute does not exist.
  70         ///
  71         /// Additional information on Ldap modifications is available in section 4.6
  72         /// of <a href="http://www.ietf.org/rfc/rfc2251.txt">rfc2251.txt</a>
  73         ///
  74         ///
  75         /// </summary>
  76         /// <seealso cref="LdapConnection.Modify">
  77         /// </seealso>
  78         /// <seealso cref="LdapAttribute">
  79         /// </seealso>
  80         public class LdapModification
  81         {
  82                 /// <summary> Returns the attribute to modify, with any existing values.
  83                 ///
  84                 /// </summary>
  85                 /// <returns> The attribute to modify.
  86                 /// </returns>
  87                 virtual public LdapAttribute Attribute
  88                 {
  89                         get
  90                         {
  91                                 return attr;
  92                         }
  93
  94                 }
  95                 /// <summary> Returns the type of modification specified by this object.
  96                 ///
  97                 /// The type is one of the following:
  98                 /// <ul>
  99                 /// <li>LdapModification.ADD</li>
 100                 /// <li>LdapModification.DELETE</li>
 101                 /// <li>LdapModification.REPLACE</li>
 102                 /// </ul>
 103                 ///
 104                 /// </summary>
 105                 /// <returns> The type of modification specified by this object.
 106                 /// </returns>
 107                 virtual public int Op
 108                 {
 109                         get
 110                         {
 111                                 return op;
 112                         }
 113
 114                 }
 115
 116                 private int op;
 117                 private LdapAttribute attr;
 118
 119                 /// <summary> Adds the listed values to the given attribute, creating
 120                 /// the attribute if it does not already exist.
 121                 ///
 122                 /// ADD = 0
 123                 /// </summary>
 124                 public const int ADD = 0;
 125
 126                 /// <summary> Deletes the listed values from the given attribute,
 127                 /// removing the entire attribute (1) if no values are listed or
 128                 /// (2) if all current values of the attribute are listed for
 129                 /// deletion.
 130                 ///
 131                 /// DELETE = 1
 132                 /// </summary>
 133                 public const int DELETE = 1;
 134
 135                 /// <summary> Replaces all existing values of the given attribute
 136                 /// with the new values listed, creating the attribute if it
 137                 /// does not already exist.
 138                 ///
 139                 ///  A replace with no value deletes the entire attribute if it
 140                 /// exists, and is ignored if the attribute does not exist.
 141                 ///
 142                 /// REPLACE = 2
 143                 /// </summary>
 144                 public const int REPLACE = 2;
 145
 146                 /// <summary> Specifies a modification to be made to an attribute.
 147                 ///
 148                 /// </summary>
 149                 /// <param name="op">      The type of modification to make, which can be
 150                 /// one of the following:
 151                 /// <ul>
 152                 /// <li>LdapModification.ADD - The value should be added to
 153                 /// the attribute</li>
 154                 ///
 155                 /// <li>LdapModification.DELETE - The value should be removed
 156                 /// from the attribute </li>
 157                 ///
 158                 /// <li>LdapModification.REPLACE - The value should replace all
 159                 /// existing values of the
 160                 /// attribute </li>
 161                 /// </ul>
 162                 /// </param>
 163                 /// <param name="attr">    The attribute to modify.
 164                 ///
 165                 /// </param>
 166                 public LdapModification(int op, LdapAttribute attr)
 167                 {
 168                         this.op = op;
 169                         this.attr = attr;
 170                         return ;
 171                 }
 172         }
 173 }