IADsPropertyList::GetPropertyItem method (iads.h)

Article
10/13/2021

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.

lnADsType value	IADsPropertyValue property to use
ADSTYPE_INVALID	Not available.
ADSTYPE_DN_STRING	DNString
ADSTYPE_CASE_EXACT_STRING	CaseExactString
ADSTYPE_CASE_IGNORE_STRING	CaseIgnoreString
ADSTYPE_PRINTABLE_STRING	PrintableString
ADSTYPE_NUMERIC_STRING	NumericString
ADSTYPE_BOOLEAN	Boolean
ADSTYPE_INTEGER	Integer
ADSTYPE_OCTET_STRING	OctetString
ADSTYPE_UTC_TIME	UTCTime
ADSTYPE_LARGE_INTEGER	LargeInteger
ADSTYPE_PROV_SPECIFIC	Use IADsPropertyValue2::GetObjectProperty (VT_ARRAY \| VT_UI1).
ADSTYPE_OBJECT_CLASS	Not available.
ADSTYPE_CASEIGNORE_LIST	Use IADsPropertyValue2::GetObjectProperty (IADsCaseIgnoreList).
ADSTYPE_OCTET_LIST	Use IADsPropertyValue2::GetObjectProperty (IADsOctetList).
ADSTYPE_PATH	Use IADsPropertyValue2::GetObjectProperty (IADsPath).
ADSTYPE_POSTALADDRESS	Use IADsPropertyValue2::GetObjectProperty (IADsPostalAddress).
ADSTYPE_TIMESTAMP	Use IADsPropertyValue2::GetObjectProperty (IADsTimestamp).
ADSTYPE_BACKLINK	Use IADsPropertyValue2::GetObjectProperty (IADsBackLink).
ADSTYPE_TYPEDNAME	Use IADsPropertyValue2::GetObjectProperty (IADsTypedName).
ADSTYPE_HOLD	Use IADsPropertyValue2::GetObjectProperty (IADsHold).
ADSTYPE_NETADDRESS	Use IADsPropertyValue2::GetObjectProperty (IADsNetAddress).
ADSTYPE_REPLICAPOINTER	Use IADsPropertyValue2::GetObjectProperty (IADsReplicaPointer).
ADSTYPE_FAXNUMBER	Use IADsPropertyValue2::GetObjectProperty (IADsFaxNumber).
ADSTYPE_EMAIL	Use IADsPropertyValue2::GetObjectProperty (IADsEmail).
ADSTYPE_NT_SECURITY_DESCRIPTOR	SecurityDescriptor
ADSTYPE_UNKNOWN	Not available.
ADSTYPE_DN_WITH_BINARY	Use IADsPropertyValue2::GetObjectProperty (IADsDNWithBinary).
ADSTYPE_DN_WITH_STRING	Use IADsPropertyValue2::GetObjectProperty (IADsDNWithString).

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

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	iads.h
DLL	Activeds.dll