IADsPropertyList::GetPropertyItem method

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

Syntax

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

Parameters

bstrName

Contains the name of the requested property.

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.

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

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

See Also

ADSI Error Codes

ADSTYPEENUM

IADsPropertyList

IADsPropertyList Property Methods

IDispatch

VariantClear