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.LdapControl.cs
27 // Sunil Kumar (Sunilk@novell.com)
29 // (C) 2003 Novell, Inc (http://www.novell.com)
33 using Novell.Directory.Ldap.Utilclass;
34 using Novell.Directory.Ldap.Asn1;
35 using Novell.Directory.Ldap.Rfc2251;
37 namespace Novell.Directory.Ldap
40 /// <summary> Encapsulates optional additional parameters or constraints to be applied to
41 /// an Ldap operation.
43 /// <p>When included with LdapConstraints or LdapSearchConstraints
44 /// on an LdapConnection or with a specific operation request, it is
45 /// sent to the server along with operation requests.</p>
48 /// <seealso cref="LdapConnection#getResponseControls">
50 /// <seealso cref="LdapSearchConstraints#getControls">
52 /// <seealso cref="LdapSearchConstraints#setControls">
54 public class LdapControl : System.ICloneable
56 /// <summary> Returns the identifier of the control.
59 /// <returns> The object ID of the control.
61 virtual public System.String ID
65 return new System.Text.StringBuilder(control.ControlType.stringValue()).ToString();
69 /// <summary> Returns whether the control is critical for the operation.
72 /// <returns> Returns true if the control must be supported for an associated
73 /// operation to be executed, and false if the control is not required for
76 virtual public bool Critical
80 return control.Criticality.booleanValue();
84 internal static RespControlVector RegisteredControls
90 return registeredControls;
94 /// <summary> Returns the RFC 2251 Control object.
97 /// <returns> An ASN.1 RFC 2251 Control.
99 virtual internal RfcControl Asn1Object
110 private static RespControlVector registeredControls;
112 private RfcControl control; // An RFC 2251 Control
114 /// <summary> Constructs a new LdapControl object using the specified values.
117 /// <param name="oid"> The OID of the control, as a dotted string.
120 /// <param name="critical"> True if the Ldap operation should be discarded if
121 /// the control is not supported. False if
122 /// the operation can be processed without the control.
125 /// <param name="values"> The control-specific data.
127 [CLSCompliantAttribute(false)]
128 public LdapControl(System.String oid, bool critical, sbyte[] values)
130 if ((System.Object) oid == null)
132 throw new System.ArgumentException("An OID must be specified");
136 control = new RfcControl(new RfcLdapOID(oid), new Asn1Boolean(critical));
140 control = new RfcControl(new RfcLdapOID(oid), new Asn1Boolean(critical), new Asn1OctetString(values));
145 /// <summary> Create an LdapControl from an existing control.</summary>
146 protected internal LdapControl(RfcControl control)
148 this.control = control;
152 /// <summary> Returns a copy of the current LdapControl object.
155 /// <returns> A copy of the current LdapControl object.
157 public System.Object Clone()
162 cont = (LdapControl) base.MemberwiseClone();
164 catch (System.Exception ce)
166 throw new System.SystemException("Internal error, cannot create clone");
168 sbyte[] vals = this.getValue();
173 // Yes even though the contructor above allocates a
174 // new Asn1OctetString, vals in that constuctor
175 // is only copied by reference
176 twin = new sbyte[vals.Length];
177 for (int i = 0; i < vals.Length; i++)
181 cont.control = new RfcControl(new RfcLdapOID(ID), new Asn1Boolean(Critical), new Asn1OctetString(twin));
186 /// <summary> Returns the control-specific data of the object.
189 /// <returns> The control-specific data of the object as a byte array,
190 /// or null if the control has no data.
192 [CLSCompliantAttribute(false)]
193 public virtual sbyte[] getValue()
195 sbyte[] result = null;
196 Asn1OctetString val = control.ControlValue;
199 result = val.byteValue();
205 /// <summary> Sets the control-specific data of the object. This method is for
206 /// use by an extension of LdapControl.
208 [CLSCompliantAttribute(false)]
209 protected internal virtual void setValue(sbyte[] controlValue)
211 control.ControlValue = new Asn1OctetString(controlValue);
215 /// <summary> Registers a class to be instantiated on receipt of a control with the
218 /// <p>Any previous registration for the OID is overridden. The
219 /// controlClass must be an extension of LdapControl.</p>
222 /// <param name="oid"> The object identifier of the control.
225 /// <param name="controlClass"> A class which can instantiate an LdapControl.
227 public static void register(System.String oid, System.Type controlClass)
229 registeredControls.registerResponseControl(oid, controlClass);
234 registeredControls = new RespControlVector(5, 5);