Método IADsPropertyList::GetPropertyItem (iads.h)

Artigo
08/24/2023

O método IADsPropertyList::GetPropertyItem recupera o item que corresponde ao nome da lista.

Sintaxe

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

Parâmetros

[in] bstrName

Contém o nome da propriedade solicitada.

[in] lnADsType

Contém um dos valores de enumeração ADSTYPEENUM que determina o tipo de dados a ser usado na interpretação da propriedade solicitada. Se o tipo for desconhecido, esse parâmetro poderá ser definido como ADSTYPE_UNKNOWN. Para servidores sem esquema, o usuário deve especificar o tipo.

[in, out] pVariant

Endereço de uma variável VARIANT alocada pelo chamador. No retorno , VARIANT contém o ponteiro da interface IDispatch do objeto que implementa a interface IADsPropertyEntry para o atributo recuperado.

Qualquer memória alocada para esse parâmetro deve ser liberada com a função VariantClear quando os dados não forem mais necessários.

Retornar valor

Esse método dá suporte aos valores de retorno HRESULT padrão, incluindo S_OK. Se o item de propriedade solicitado não for encontrado, o método retornará ADS_PROPERTY_NOT_FOUND. Para obter mais informações e outros valores retornados, consulte Códigos de erro ADSI.

Comentários

A propriedade do objeto IADsPropertyValue retornado por esse método que pode ser usado dependerá do tipo especificado em lnADsType. A tabela a seguir mapeia o tipo de dados para a propriedade IADsPropertyEntry apropriada.

Valor lnADsType	Propriedade IADsPropertyValue a ser usada
ADSTYPE_INVALID	Não disponível.
ADSTYPE_DN_STRING	DNString
ADSTYPE_CASE_EXACT_STRING	CaseExactString
ADSTYPE_CASE_IGNORE_STRING	CaseIgnoreString
ADSTYPE_PRINTABLE_STRING	PrintableString
ADSTYPE_NUMERIC_STRING	NumericString
ADSTYPE_BOOLEAN	Booliano
ADSTYPE_INTEGER	Inteiro
ADSTYPE_OCTET_STRING	OctetString
ADSTYPE_UTC_TIME	UTCTime
ADSTYPE_LARGE_INTEGER	LargeInteger
ADSTYPE_PROV_SPECIFIC	Usar IADsPropertyValue2::GetObjectProperty (VT_ARRAY \| VT_UI1).
ADSTYPE_OBJECT_CLASS	Não disponível.
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	Não disponível.
ADSTYPE_DN_WITH_BINARY	Use IADsPropertyValue2::GetObjectProperty (IADsDNWithBinary).
ADSTYPE_DN_WITH_STRING	Use IADsPropertyValue2::GetObjectProperty (IADsDNWithString).

Exemplos

O exemplo de código a seguir mostra como recuperar uma entrada de propriedade usando o método 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

O exemplo de código a seguir mostra como recuperar uma entrada de propriedade usando o método GetPropertyItem . Ele pressupõe que a interface IADsPropertyList foi recuperada corretamente. Para obter mais informações sobre como carregar o cache de propriedades, consulte a função de exemplo GetPropertyCache em 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();

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	iads.h
DLL	Activeds.dll