Skip to content

IAdmObjectSnapshot

The IAdmObjectSnapshot interface represents a serialized instance of a directory object. You can get a snapshot of a directory object and further use it to manage the object properties locally without the need to query the directory store. This is often used to improve performance and reduce network traffic between the client and the service.

Inheritance: The IAdmObjectSnapshot interface inherits from the IUnknown interface.

Methods

  • Method

  • Description

  • Get()

  • Gets the value for a property by name.

  • GetEx()

  • Gets the value for a single or multi-valued property by name.

  • Put()

  • Sets a value for a given property by name.

  • PutEx()

  • Sets a value for a single or multi-valued property by name.

Properties

  • Property

  • Description

  • ADsPath

  • Gets the object ADS path that uniquely identifies this directory object among all others.

  • Class

  • Gets the name of the schema class of the object.

  • GUID

  • Gets the globally unique identifier (GUID) of the object as stored in the directory.

  • Name

  • Gets the object relative name (RDN).

  • Parent

  • Gets the ADS path string for the parent container or Organizational Unit of the object.

  • Schema

  • Gets the ADS path string to the schema class object for this directory object.

  • PropertyList

  • Gets the property list of the directory object.

  • IsObjectBound

  • Use this property to identify whether the object is bound to the directory or not.

Details

Get()

Gets the value for a property by name. The property can be either single-valued, or multi-valued. The property value is represented as either an Object for a single-valued property or an Object[] array for a property that allows multiple values.

Object Get(String name)

Parameters

The name parameter specifies the property name.

Return value

An Object that represents the value of the property. For a multi-valued property, the method returns an Object[] array, unless the property is a binary type. In this latter case, the method returns an array of bytes (Byte[]).

Remarks

  • The method requires that you handle the single- and multi-valued property values differently. Thus, if you know that the requested property is either single- or multi-valued, use this method to retrieve the property value.
  • You can also use the GetEx method to retrieve property values. The method returns property values as an Object[] array, regardless of whether the property is single-valued or multi-valued. This saves you the effort of validating the data types when unsure whether the data to be returned has single or multiple values.

GetEx()

Gets the value for a single or multi-valued property by name. The returned property values can be either single-valued or multi-valued. Unlike the Get method, this method returns property values as an Object[] array. A single-valued property is therefore represented as an array of a single element.

Object GetEx(String name)

Parameters

The name parameter specifies the property name.

Return value

An Object[] array of property values.

Remarks

The Get and GetEx methods return different data structures for a single-valued property value. For example, if the property is a string, Get returns a String object, whereas GetEx returns a String[] array with a single element. Thus, if you are unsure whether a multi-valued property is to return a single value or multiple values, use the GetEx method.


Put()

Sets a value for a given property by name.

void Put(String name, Object value)

Parameters

  • name - Specifies the property name to be updated.
  • value - Specifies the new values for the property.

Remarks

To manipulate property values beyond simple assignment, use PutEx in order to append a value to or remove it from an existing array of property values.


PutEx()

Sets a value for a single or multi-valued property by name. For properties that allow multiple values, you may append additional values to an existing set of values, modify values in the set, remove specified values from the set, or delete values from the set.

void PutEx(ADS_PROPERTY_OPERATION_ENUM controlCode, 
           String name, 
           Object[] value)

Parameters

  • controlCode - Control code that indicates the mode of modification: Append, Replace, Remove or Delete.
  • name - Specifies the property name.
  • value - Represents an Object[] array that contains the new value or values of the property. A single-valued property is represented as an array of a single element. If the parameter is set to ADS_PROPERTY_CLEAR, the value parameter is irrelevant.

Remarks

  • This method is usually used to set values on multi-valued properties.
  • This method enables you to append values to an existing set of values in a multi-valued property using the ADS_PROPERTY_APPEND control code. Active Directory does not accept duplicate values on a multi-valued property. If you call this method to append a duplicate value to a multi-valued property of a directory object, the call succeeds, but the duplicate value is ignored.
  • Similarly, if you use this method to delete one or more values from a multi-valued property of a directory object, the operation succeeds, that is, it will not produce an error, even if any or all of the specified values are not set for the property.

ADsPath

Gets the object ADS path that uniquely identifies this directory object among all others. The object can always be retrieved using this path.

  • Type:
  • String
  • Access:
  • Read-only

Class

Gets the name of the schema class of the object.

  • Type:
  • String
  • Access:
  • Read-only

GUID

Gets the globally unique identifier (GUID) of the object as stored in the directory. The IAdmObjectSnapshot interface converts the GUID from an octet string, as stored on the directory server, into the string format.

  • Type:
  • String
  • Access:
  • Read-only

Remarks

The GUID returned by the GUID property is a string of hexadecimals. Use this GUID to bind to the directory object directly.

Adaxes://servername/<GUID=xxx>

where xxx is the value returned from the GUID property.


Name

Gets the object relative name (RDN). This name distinguishes this object among its siblings. Example: CN=John Smith.

  • Type:
  • String
  • Access:
  • Read-only

Parent

Gets the ADS path string for the parent container or Organizational Unit of the object.

  • Type:
  • String
  • Access:
  • Read-only

Schema

Gets the ADS path string to the schema class object for this directory object.

  • Type:
  • String
  • Access:
  • Read-only

PropertyList

Gets the property list of the directory object. The list is represented by the IAdmPropertyList interface, which allows you to read and update the list of property entries in the property cache of the object.


IsObjectBound

Use this property to identify whether the object is bound to the directory or not.

  • Type:
  • Boolean
  • Access:
  • Read-only

Requirements

Minimum required version: 2009.1

See also