Platform SDK: Active Directory, ADSI, and Directory Services

IADsPropertyList::GetPropertyItem

The IADsPropertyList::GetPropertyItem method retrieves the item that matches the name from the list.

HRESULT GetPropertyItem(
  BSTR bstrName,
  LONG lnADsType,
  VARIANT * pVariant
);

Parameters

bstrName: [in] Name of the requested property.
lnADsType: [in] Type to be used in interpreting the requested property. Values are taken from the ADSTYPEENUM enumeration. If the type is not known, this parameter can be set to ADSTYPE_UNKNOWN. For schema-less servers, the user must specify the type.
pVariant: [out] Address of a method-allocated variant containing the requested property item. If this parameter is NULL on return, the requested item could not be obtained.

Return Values

This method supports the standard HRESULT return values, including S_OK. For other return values, see ADSI Error Codes.

Remarks

As a caller, you are responsible for freeing the VARIANT variable allocated by GetPropertyItem.

Example Code [Visual Basic]

The following Visual Basic code snippet shows how to retrieve a property entry using the GetPropertyItem method.

Dim propList As IADsPropertyList
Dim propEnty As IADsPropertyEntry
Dim propVal As IADsPropertyValue
 
Set propList = GetObject("LDAP://dc01/DC=Microsoft,DC=com")
propList.GetInfo
 
Set propEntry = propList.GetPropertyItem("dc", ADSTYPE_CASE_IGNORE_STRING)
 
For Each v In propEntry.Values
    Set propVal = v
    Debug.Print propVal.CaseIgnoreString
Next

Example Code [C++]

The following C++ code snippet shows how to retrieve a property entry using the GetPropertyItem method. It assumes that the IADsPropertyList interface has been properly obtained. For more information on how to load the property cache, see the code listing of the GetPropertyCache(LPWSTR) function given in IADsPropertyList.

#include <activeds.h>
#include <stdio.h>
 
/////////////////////////////////////////////////////////
// Function to retrieve a specified property entry 
// using the IADsPropertyList::GetPropertyItem method.
/////////////////////////////////////////////////////////
IADsPropertyEntry *GetPropertyItem(
      IADsPropertyList *pList, 
      LPWSTR entryName,
      long entryType)
{
   IADsPropertyEntry *pEntry;
   VARIANT var;
   VariantInit(&var);
 
   // get a property entry
   hr = pList->GetPropertyItem(entryName, entryType, &var);
   hr = V_DISPATCH(&var)->QueryInterface(IID_IADsPropertyEntry,
                                         (void**)&pEntry);
   VariantClear(&var);
 
   return pEntry;
}
 
///////////////////////////////////////////////////////
// Examine a property entry.
///////////////////////////////////////////////////////
IADsPropertyList *pList;
pList = GetPropertyCache(L"LDAP://dc01/DC=Microsoft,DC=COM");
 
IADsPropertyEntry *pEntry;
pEntry = GetPropertyItem(pList, L"dc", ADSTYPE_CASE_IGNORE_STRING)
 
BSTR nm;
HRESULT hr = pEntry->get_Name(&nm);
printf("Property name = %S\n",nm);
 
if(pList) pList->Release();
if(pEntry) pEntry->Release();
if(nm) SysFreeString(&nm);

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.