IADsPropertyList：：GetPropertyItem 方法 (iads.h)

發行項
03/05/2024

IADsPropertyList：：GetPropertyItem 方法會從清單中擷取符合名稱的專案。

語法

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

參數

[in] bstrName

包含要求屬性的名稱。

[in] lnADsType

包含其中一個 ADSTYPEENUM 列舉值，可決定要用於解譯所要求屬性的數據類型。如果類型未知，則可以將此參數設定為 ADSTYPE_UNKNOWN。對於無架構伺服器，用戶必須指定類型。

[in, out] pVariant

呼叫端配置的 VARIANT 變數位址。傳回時， VARIANT 包含物件的 IDispatch 介面指標，該指標會實作所擷取屬性的 IADsPropertyEntry 介面。

當不再需要數據時，必須使用 VariantClear 函式釋放為此參數配置的任何記憶體。

傳回值

這個方法支持標準 HRESULT 傳回值，包括 S_OK。如果找不到要求的屬性專案，方法會傳回 ADS_PROPERTY_NOT_FOUND。如需詳細資訊和其他傳回值，請參閱 ADSI 錯誤碼。

備註

這個方法所傳回之 IADsPropertyValue 物件的屬性，將取決於 lnADsType 中指定的類型。下表會將數據類型對應至適當的 IADsPropertyEntry 屬性。

lnADsType 值	要使用的 IADsPropertyValue 屬性
ADSTYPE_INVALID	不適用。
ADSTYPE_DN_STRING	DNString
ADSTYPE_CASE_EXACT_STRING	CaseExactString
ADSTYPE_CASE_IGNORE_STRING	CaseIgnoreString
ADSTYPE_PRINTABLE_STRING	PrintableString
ADSTYPE_NUMERIC_STRING	NumericString
ADSTYPE_BOOLEAN	布林值
ADSTYPE_INTEGER	整數
ADSTYPE_OCTET_STRING	OctetString
ADSTYPE_UTC_TIME	UTCTime
ADSTYPE_LARGE_INTEGER	LargeInteger
ADSTYPE_PROV_SPECIFIC	使用 IADsPropertyValue2：：GetObjectProperty (VT_ARRAY \|VT_UI1) 。
ADSTYPE_OBJECT_CLASS	不適用。
ADSTYPE_CASEIGNORE_LIST	使用 IADsPropertyValue2：：GetObjectProperty (IADsCaseIgnoreList) 。
ADSTYPE_OCTET_LIST	使用 IADsPropertyValue2：：GetObjectProperty (IADsOctetList) 。
ADSTYPE_PATH	使用 IADsPropertyValue2：：GetObjectProperty (IADsPath) 。
ADSTYPE_POSTALADDRESS	使用 IADsPropertyValue2：：GetObjectProperty (IADsPostalAddress) 。
ADSTYPE_TIMESTAMP	使用 IADsPropertyValue2：：GetObjectProperty (IADsTimestamp) 。
ADSTYPE_BACKLINK	使用 IADsPropertyValue2：：GetObjectProperty (IADsBackLink) 。
ADSTYPE_TYPEDNAME	使用 IADsPropertyValue2：：GetObjectProperty (IADsTypedName) 。
ADSTYPE_HOLD	使用 IADsPropertyValue2：：GetObjectProperty (IADsHold) 。
ADSTYPE_NETADDRESS	使用 IADsPropertyValue2：：GetObjectProperty (IADsNetAddress) 。
ADSTYPE_REPLICAPOINTER	使用 IADsPropertyValue2：：GetObjectProperty (IADsReplicaPointer) 。
ADSTYPE_FAXNUMBER	使用 IADsPropertyValue2：：GetObjectProperty (IADsFaxNumber) 。
ADSTYPE_EMAIL	使用 IADsPropertyValue2：：GetObjectProperty (IADsEmail) 。
ADSTYPE_NT_SECURITY_DESCRIPTOR	SecurityDescriptor
ADSTYPE_UNKNOWN	不適用。
ADSTYPE_DN_WITH_BINARY	使用 IADsPropertyValue2：：GetObjectProperty (IADsDNWithBinary) 。
ADSTYPE_DN_WITH_STRING	使用 IADsPropertyValue2：：GetObjectProperty (IADsDNWithString) 。

範例

下列程式代碼範例示範如何使用 GetPropertyItem 方法來擷取屬性專案。

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

下列程式代碼範例示範如何使用 GetPropertyItem 方法來擷取屬性專案。它假設已正確擷取 IADsPropertyList 介面。如需如何載入屬性快取的詳細資訊，請參閱 IADsPropertyList 中的 GetPropertyCache 範例函式。

#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();