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] Contains the name of the requested property.
lnADsType: [in] 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: [in, out] 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 Values

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.

Example Code [Visual Basic]

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

[Visual Basic]
Dim propList As IADsPropertyList
Dim propEntry As IADsPropertyEntry
Dim propVal As IADsPropertyValue

On Error GoTo Cleanup
 
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
	Debug.Print propVal.CaseIgnoreString
Next

Cleanup:
	If (Err.Number<>0) Then
		MsgBox("An error has occurred. " & Err.Number)
	End If

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

Example Code [C++]

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

[C++]
#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

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.