IADsPropertyList::GetPropertyItem method (iads.h)

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

Syntax

HRESULT GetPropertyItem(
  [in]      BSTR    bstrName,
  [in]      LONG    lnADsType,
  [in, out] VARIANT *pVariant
);

Parameters

[in] bstrName

Contains the name of the requested property.

[in] lnADsType

Contains one of the ADSTYPEENUM enumeration values that determines the data type to be used in interpreting the requested property. If the type is unknown, this parameter can be set to ADSTYPE_UNKNOWN. For schemaless servers, the user must specify the type.

[in, out] pVariant

Address of a caller-allocated VARIANT variable. On return, the VARIANT contains the IDispatch interface pointer of the object which implements the IADsPropertyEntry interface for the retrieved attribute.

Any memory allocated for this parameter must be released with the VariantClear function when the data is no longer required.

Return value

This method supports the standard HRESULT return values, including S_OK. If the requested property item is not found, the method returns ADS_PROPERTY_NOT_FOUND. For more information and other return values, see ADSI Error Codes.

Remarks

The property of the IADsPropertyValue object returned by this method that can be used will depend on the type specified in lnADsType. The following table maps the data type to the appropriate IADsPropertyEntry property.

Examples

The following code example shows how to retrieve a property entry using the GetPropertyItem method.

Const ADSTYPE_CASE_IGNORE_STRING = 3
Dim propList As IADsPropertyList
Dim propEntry As IADsPropertyEntry
Dim propVal As IADsPropertyValue

Set propList = GetObject("LDAP://dc01/DC=Fabrikam,DC=com")
propList.GetInfo
 
Set propEntry = propList.GetPropertyItem("dc", ADSTYPE_CASE_IGNORE_STRING)
 
For Each v In propEntry.Values
    Set propVal = v

    ' Use the CaseIgnoreString property because the ADSTYPE_CASE_IGNORE_STRING 
    ' type was requested in GetPropertyItem.
    Debug.Print propVal.CaseIgnoreString
Next

Set propList = Nothing
Set propEntry = Nothing
Set propVal = Nothing

The following code example shows how to retrieve a property entry using the GetPropertyItem method. It assumes that the IADsPropertyList interface has been properly retrieved. For more information about how to load the property cache, see the GetPropertyCache example function in IADsPropertyList.

#include <activeds.h>
#include <stdio.h>
 
/////////////////////////////////////////////////////////
// Function to retrieve a specified property entry 
// using the IADsPropertyList::GetPropertyItem method.
/////////////////////////////////////////////////////////
IADsPropertyEntry *GetPropertyItem(
      IADsPropertyList *pList, 
      BSTR entryName,
      long entryType)
{
   IADsPropertyEntry *pEntry;
   VARIANT var;
   VariantInit(&var);

   if(!pList || !entryName)
   {
      _tprintf("Invalid argument...");
      return NULL;
   }
 
   // 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 = NULL;
IADsPropertyEntry *pEntry = NULL;

pList = GetPropertyCache(L"LDAP://dc01/DC=Fabrikam,DC=COM");
 
if(pList)
{
    pEntry = GetPropertyItem(pList, L"dc", ADSTYPE_CASE_IGNORE_STRING);
}

if(pEntry)
{ 
    BSTR nm;
    HRESULT hr = pEntry->get_Name(&nm);
    if(SUCCEEDED(hr))
    {
        printf("Property name = %S\n",nm);
        SysFreeString(nm);
    }
}
 
if(pList)
    pList->Release();
if(pEntry)
    pEntry->Release();

Requirements

See also

ADSI Error Codes

ADSTYPEENUM

IADsPropertyList

IADsPropertyList Property Methods

IDispatch

VariantClear