4.2.1 IADs

IADs is a COM interface that is defined by Active Directory. It provides basic functionality that is required by all Active Directory objects:

Identifying information that indicates the name and type of the object.

Binding information that uniquely identifies the object instance in a directory tree.

A way to retrieve an interface pointer on the parent container object.

A way to retrieve the access control dependent object for the host object

A way tio retrieve the access control dependent object(s) for properties on the host object

A way to retrieve the schema definition of the object.

A simple caching system.

The interface definition is as follows:

[ object, uuid(IID_IADs), oleautomation, dual ]
interface IADs: IDispatch
{
// Read-only properties.
[propget]
HRESULT Name ([out, retval]BSTR *pbstrName);
[propget]
HRESULT Class ([out, retval]BSTR *pbstrClass);
[propget]
HRESULT GUID ([out, retval]BSTR *pbstrGUID);
[propget]
HRESULT ADsPath ([out, retval]BSTR *pbstrADsPath);
[propget]
HRESULT Parent ([out, retval]BSTR *pbstrParentContainer);
[propget]
HRESULT Schema ([out, retval]BSTR *pbstrSchemaClassObject);

// Methods.
HRESULT Access ([out, retval]IADsAccess **ppComponentAccessControl);
HRESULT PropAccess ([in]BSTR bstrPropName,
   [out, retval]IADsAccess **ppComponentAccessControl);
HRESULT GetInfo ([in,optional]VARIANT vHints);
HRESULT SetInfo (void);
HRESULT Get ([in]BSTR bstrName, [out, retval]VARIANT *pvProp);
HRESULT Put ([in]BSTR bstrName, [in]VARIANT vProp);
HRESULT GetEx ([in]BSTR bstrname, [out, retval] VARIANT *pvProp);
HRESULT PutEx ([in]LONG lnControlCode,[in]BSTR bstrName, [in]VARIANT vProp);
};

Method	Syntax	Remark
Name	String	Gets the relative name of the object as named within the underlying namespace.
ADsPath	ADsPath	Gets the ADsPath string of the object that uniquely identifies the object in a heterogeneous environment.
Class	String	Gets the name of the schema class of this object. See the object extensions section for more details.
GUID	String	Gets the unique identifier for objects of this schema class. NOTE: Each Active Directory object type is uniquely identified by a GUID. This GUID is the Active Directory abstraction of the globally unique identifier for the schema class, analogous to an ASN.1 OID.
Parent	ADsPath	Gets the ADsPath string of the parent container.
Schema	ADsPath	Gets the ADsPath string of the object that represents this schema class in the schema. See the object extensions chapter for details.
Access	Method	Obtains the IADsAccess interface on the access control object that corresponds to the security permissions on this DS object. See Chapter 5,"Dependent objects," for more details.
PropAccess	Method	Returns a pointer to the IADsAccess interface on the access control dependent object that represents the access control on a property directly hosted by this object, as indicated by bstrPropName. See "Access Control Objects" later in this chapter for more details.
GetInfo	Method	Reloads the object with the property values that exist within the directory service. The vHints parameter allows the client to indicate which properties should be loaded, so the provider can attempt to optimize network access. If no hints are specified, the VARIANT vHints is marked as empty, and the provider is expected to provide as much smart network access as possible. Otherwise, each entry in the array should have the following format: <HintEntry>::=<PropName> where <PropName> is a BSTR value a property found in the schema.
SetInfo	Method	Mechanism for committing changes on an object. If properties have been changed on an object, the SetInfo method will cause the properties to be changed within the directory service.
Get	Method	retrieves the value for a named property. The Property is specified in the bstrName argument as <"PropertyName">. The property value is returned in the passed VARIANT structure.
Put	Method.	Sets the value for a named property. The property is specified in the bstrName argument as a string in the form <"PropertyName">. The property value to set is provided in the passed VARIANT structure. NOTE: to remove a property from an object, call the PutEx method with the lnControlCode value set to ADS_PROP_CLEAR.
GetEx	Method	retrieves the values for a named single or multi-valued property. The Property is specified in the bstrName argument as <"PropertyName">. The property values are returned as a variant array in the passed VARIANT structure.
PutEx	Method	Sets the value(s) for a named single- or multi-valued property. The property is specified in the bstrName argument as a string in the form <"PropertyName">. Valid values for lnControlCode are: ADS_PROP_CLEAR: remove the property from the object. ADS_PROP_OVERWRITE: replaces the current value with the element(s) in the passed variant array, ADS_PROP_APPEND: appends the element(s) in the passed variant array to the current value.

4.2.1.1 Active Directory Object Type GUIDs

The Active Directory Object GUID should not be confused with a CLSID.

Active Directory Object Type GUIDs provide consistent identification for well-known objects that is consistent across providers. Well-known objects are those that are defined by Active Directory. The GUID is the Interface ID (IID) for the primary COM interface on the object (see 0).

CLSIDs identify the class code associated with COM objects.

Active Directory objects that are instantiated on behalf of a given Active Directory provider are COM objects with CLSIDs unique to the provider. The Active Directory Object Type GUID will be the same for all well-known objects of a type, regardless of provider. For example, if three Active Directory providers are installed on a given machine, there will be 3 different CLSIDs for the Active Directory User object, one for each provider. All 3 user objects will have the same Active Directory Type, IID_IADsUser, indicating that the objects are implementations of the Active Directory User object.

4.2.1.2 GetInfo and SetInfo

The GetInfo and SetInfo methods provide simple caching capabilities for properties in Active Directory components. Operations that involve getting and setting properties occur in cached mode. No changes are made to an object's properties within the namespace until the SetInfo method is executed. All changes to properties are cached locally until the SetInfo method is called.

GetInfo does not apply to container operations. SetInfo only applies to the creation of a new object in a container. See 0, below.

The GetInfo method refreshes the contents of the object's local cache. If the GetInfo method is executed after changes are made to the local object's cache but before the SetInfo method is executed, the changes are lost. GetInfo allows the client to provide hints about which properties it uses, so that the provider can optimize network access.

A caller can obtain a property value from an Active Directory object at any time after obtaining the object (for example, via GetObject or via Active Directory enumeration). The caller need not call GetInfo first. If the property in question has not been previously retrieved, the provider is responsible for retrieving and caching it to satisfy the request. Subsequent requests will be satisfied from the cached value.

GetInfo is called to explicitly refresh the object's cached properties from the underlying namespace; by calling GetInfo, the caller ensures that the property values are current as of the time of the GetInfo call.

Both GetInfo and SetInfo may require multiple accesses to the underlying namespace to load or store the properties in the Active Directory object. It is technically possible for a GetInfo or SetInfo operation to be only partially successful. Active Directory providers are expected to complete as much of the requested operation as possible before returning. Active Directory provides several standard error codes to indicate that a request was not completely processed. Users should consult the documentation for the specific providers in use to determine what Active Directory errors are returned for their providers.

Non-property methods are executed as soon as the method call is received and are not processed in cached mode.

The following example modifies a user object in a simple demonstration of the caching system.

Example 1: The Caching System (Visual Basic)

'Example 1: The Caching System (Visual Basic) Dim MyUser As IADsUser '' Bind to a user object. Set MyUser = GetObject("WinNT://ntserver/1") '' Change the nickname and title of the user. '' Changes are stored in the Active Directory object cache until '' SetInfo is called. MyUser.FullName = "Johnny" '' Call SetInfo to commit the changes to the network. MyUser.SetInfo '' Now change the user's password - this is a non-property method '' and is executed immediately. MyUser.SetPassword ("Argus") '' Now refresh the Active Directory object cache with a GetInfo call. MyUser.GetInfo ' Display some properties. Debug.Print MyUser.FullName

Example 1: The Caching System (C/C++)

IADsUser    *pUser;
BSTR    bstrNickName;
BSTR    bstrTitle;
VARIANT    vHints;

//
// Bind to the user object.
//
ADsGetObject(TEXT("WinNT://MSFT/Users/John"),
IID_IADsUser,
(void**)&pUser);

//
// Allocate the strings for the changes.
//
bstrNickName = SysAllocString(TEXT("Johnny"));
bstrTitle = SysAllocString(TEXT("General Manager"));
bstrPassword = SysAllocString(TEXT("Argus"));

//
// Change the nickname and title of the user.  The changes
// are made in the local cache only.
//
pUser->put_NickName(bstrNickName);
pUser->put_Title(bstrTitle);

//
// Call SetInfo to commit the changes to the network.
//
pUser->SetInfo();

//
// Now change the user's password - this non-property method
// executes immediately.
//
pUser->SetPassword(bstrPassword);

//
// Refresh the Active Directory object with a call to GetInfo.  No hints
// are specified.
//
VariantInit(&vHints);
V_VT(&vHints) = VT_EMPTY;
pUser->GetInfo(vHints);

//
// Clean up and reuse the strings.
//
SysFreeString(bstrNickName);
SysFreeString(bstrTitle);
SysFreeString(bstrPassword);

//
// Retrieve values from the object.
//
pUser->get_Description(&bstrNickName);
pUser->get_Location(&bstrTitle);
printf("%s, %s", bstrNickName, bstrTitle);

//
// Release all interfaces.
//
pUser->Release();

The following example demonstrates how to use caching hints to minimize network traffic. A print queue is polled periodically for its status.

Example 2: Caching Hints (Visual Basic)

Dim PrintQueue as IADsPrintQueue Dim Hints as Variant Dim Counter as Long ' Bind to a print queue object. Set PrintQueue = GetObject("WinNT://MSFT/Printers/Queue26") ' In this case we are interested in polling the print queue for ' it's status. Set up the hints to identify this. Hints = Array("Status") ' Loop to poll the queue. For Counter = 1 to 1000 ' Show the queue status. Debug.Print PrintQueue.Status ' Wait the polling interval. Call Sleep(1000) ' Refresh the object cache. PrintQueue.GetInfo(Hints) Next Counter

Example 2: Caching Hints (C/C++)

IADsPrintQueue        *pPrintQueue;
IADsPrintQueueOperations *pOperation;
long    *pStatus;

BSTR    bstrStatusString;
BSTR    bstrHint;
DWORD    dwStatusCode;
SAFEARRAY    *psaHints;
SAFEARRAYBOUND rgsabound[1];
VARIANT    vHints;
long    ix[1];
DWORD    dwCounter;

//
// Bind to the print queue object.  Get the Operation Interface and the IADs 
// interface
//
ADsGetObject(TEXT("WinNT://MSFT/Printers/Queue26"),
IID_IADsPrintQueueOperations,
(void**)&pOperation);
pOperation->QueryInterface(IID_IADs,(void **)&pPrintQueue);
//
// In this case we are interested in polling thw queue for
// it's status.  Set up the hints to identify this.
//
bstrHint = SysAllocString(TEXT("Status"));
rgsabound[0].lLBound = 0;
rgsabound[0].cElements = 1;
psaHints = SafeArrayCreate(VT_BSTR, 1, rgsabound);
ix[0]=1;
SafeArrayPutElement(psaHints, ix, bstrHint);
VariantInit(&vHints);
V_VT(&vHints) = VT_BSTR|VT_ARRAY;
V_ARRAY(&vHints) = psaHints;

//
// Loop to poll the queue.
//
For(dwCounter=1;dwCounter<=1000;dwCounter++)
{

//
// Get and report values.
//
pOperation->get_Status(&dwStatusCode);
printf("%d, \n", dwStatusCode);

//
// Wait the polling interval.
//
Sleep(1000);

//
// Refresh the object cache and destroy old placeholders.
//
pPrintQueue->GetInfo(vHints);
SysFreeString(bstrStatusString);
}

//
// Cleanup.
//
SafeArrayDestroy(psaHints);
pOperation->Release();
pPrintQueue->Release();