Accessing an Individual Property in the Property Cache

Individual properties in the property cache can be referenced in several ways. From Automation languages, you use the property name directly. This is the ADSI property name, for example, Name or Class, both properties defined on IADs. You can also use the property names as it is defined in the schema object. Then you can use the IADs::Get or any of its related interfaces, GetEx, Put, and PutEx. In each of these cases, you pass the name of the property as it is defined in the schema as the first parameter.

From non-Automation languages, you can also use the IADs::Get method and its related methods as described above. In addition, you can use the get_propertyname and put_propertyname methods supported on all ADSI interfaces.

To find the property names supported by an object, first get the IADs interface pointer for that object. Use IADs::Schema to find the schema object, and IADs::Class to look up the class definition. Using the IADsClass interface on the class definition, use property methods MandatoryProperties and OptionalProperties to see the list of properties defined for each object of this type.

Note  In the following discussion, "get methods" include IADs::Get, IADs::GetEx, and any get_ property method defined on an ADSI interface. Similarly, "put methods" include IADs::Put, IADs::PutEx, and any put_ property method defined on an ADSI interface.

When an object is created, its property cache is empty. You can force all the properties to load by calling GetInfo. When you call one of the get methods and the cache is empty, an implicit GetInfo occurs. Once the cache is filled, all subsequent get and put requests are filled from the current contents of the cache, eliminating network calls. Only another explicit GetInfo refreshes the cache.

One consequence of this design occurs for the following scenario:

If the cache already has values, and you then set a previously undefined property in the underlying directory service, and you get that property, the cache will not have the value and the error return is E_ADS_PROPERTY_NOT_FOUND. You must explicitly call GetInfo to see the new value.

If you use a put method to change a value in the cache for a property and subsequently use a get method for that property, you retrieve the value you just put there. If you explicitly call GetInfo after you have changed values in the cache but before you call SetInfo, the values in the cache are refreshed from the underlying directory service and any changes you made are over-written.

SetInfo is always an explicit call, never called implicitly.

For more information, see IADs.

Examples of get and put methods for properties for Automation clients include the following:

MyObject.xxxx
Get by using object.property syntax on the right side of an assignment operation (=) or in an expression. Put by using object.property syntax on the left side of an assignment operator (=).
Value=(User.FullName)
Get by passing the name of the property. Use GetEx for multivalued properties.
MyObject.Put("Property_X", value)
Put by passing the name of the property. Use PutEx for multivalued properties.

The following Automation example shows both styles of setting the IADsUser::FullName property in the cache.

' Visual Basic example
Dim User as IADsUser
Dim MyObject as IADs
Dim Name as Variant

Set FullName as "John Q. Public"
Set User = GetObject("WinNT://MSFT/Users/John")

//Set using IADsUser::put_Fullname property method
User.FullName = Name

//Set using IADs::PutMethod
User.Put("FullName",Name)
 

Examples of get methods for properties for non-Automation clients include the following:

IADsXXXX::get_xxxx
An interface's compile-time property method beginning with get_ on a named property.
IADs::Get("Property_X")
A runtime get by property name.
// For non-Automation clients
IADsUser     *pUser; 
IADs         *PObject;
ADsGetObject(
     TEXT("WinNT://MSFT/Users/John"), 
     IID_IADsUser, 
     (void**) &pUser);
// Set using IADsUser::put_FullName property method
pUser->put_FullName(TEXT("John Q. Public"));
// Set using IADs::Put method
pUser->QueryInterface(IID_IADs,(void **) &pObject);
pObject->Put("FullName",TEXT("John Q. Public"))