Como especificar valores de comparação

Artigo
02/21/2024

Cada tipo de atributo tem uma sintaxe que determina o tipo de valores de comparação que você pode especificar em um filtro de pesquisa para esse atributo.

As seções a seguir descrevem os requisitos para cada sintaxe de atributo. Para obter mais informações sobre sintaxes de atributo, consulte Syntaxes for Attributes in Active Directory Domain Services.

Booleano

O valor especificado em um filtro deve ser um valor de cadeia de caracteres que seja "TRUE" ou "FALSE". Os exemplos a seguir mostram como especificar uma cadeia de comparação booleana.

O exemplo a seguir procurará objetos que tenham um showInAdvancedViewOnly definido como TRUE:

(showInAdvancedViewOnly=TRUE)

O exemplo a seguir procurará objetos que tenham um showInAdvancedViewOnly definido como FALSE:

(showInAdvancedViewOnly=FALSE)

Inteiro e enumeração

O valor especificado em um filtro deve ser um inteiro decimal. Os valores hexadecimais devem ser convertidos em decimais. Uma cadeia de comparação de valores assume a seguinte forma:

<attribute name>:<value>

"<nome> do atributo" é o lDAPDisplayName do atributo e "value>"< é o valor a ser usado para comparação.

O exemplo de código a seguir mostra um filtro que procurará objetos que tenham um valor groupType igual ao sinalizador ADS_GROUP_TYPE_UNIVERSAL_GROUP (8) e ao sinalizador ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000). As duas bandeiras combinadas são iguais 0x80000008, que convertidas em decimais é 2147483656.

(groupType=2147483656)

Os operadores de regra de correspondência LDAP também podem ser usados para realizar comparações bit a bit. Para obter mais informações sobre regras correspondentes, consulte Sintaxe do filtro de pesquisa. O exemplo de código a seguir mostra um filtro que procurará objetos que tenham um groupType com o ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) bit set.

(groupType:1.2.840.113556.1.4.803:=2147483648))

OctetString

O valor especificado em um filtro são os dados a serem encontrados. Os dados devem ser representados como uma cadeia de caracteres de bytes codificada de dois caracteres, onde cada byte é precedido por uma barra invertida (\). Por exemplo, o valor 0x05 aparecerá na cadeia de caracteres como "\05".

A função ADsEncodeBinaryData pode ser usada para criar uma representação de cadeia de caracteres codificada de dados binários. A função ADsEncodeBinaryData não codifica valores de byte que representam caracteres alfanuméricos. Em vez disso, ele colocará o caractere na cadeia de caracteres sem codificá-lo. Isso resulta na cadeia de caracteres que contém uma mistura de caracteres codificados e não codificados. Por exemplo, se os dados binários forem 0x05|0x1A|0x1B|0x43|0x32, a cadeia de caracteres codificada conterá "\05\1A\1BC2". Isso não tem efeito sobre o filtro e os filtros de pesquisa funcionarão corretamente com esses tipos de cadeias de caracteres.

Você pode usar curingas.

O exemplo de código a seguir mostra um filtro que contém sequência de caracteres codificada para schemaIDGUID com valor GUID de "{BF967ABA-0DE6-11D0-A285-00AA003049E2}":

(schemaidguid=\BA\7A\96\BF\E6\0D\D0\11\A2\85\00\AA\00\30\49\E2)

Sid

O valor especificado em um filtro é a representação de cadeia de caracteres de byte codificada do SID. Para obter mais informações sobre cadeias de caracteres de bytes codificados, consulte a seção anterior deste tópico que discute a sintaxe OctetString.

O exemplo de código a seguir mostra um filtro que contém uma cadeia de caracteres codificada para objectSid com valor de cadeia de caracteres SID de "S-1-5-21-1935655697-308236825-1417001333":

(ObjectSid=\01\04\00\00\00\00\00\05\15\00\00\00\11\C3\5Fs\19R\5F\12u\B9uT)

DN

Todo o nome distinto, a ser correspondido, deve ser fornecido.

Curingas não são aceitos.

Lembre-se de que o atributo objectCategory também permite especificar o lDAPDisplayName do conjunto de classes no atributo.

O exemplo a seguir mostra um filtro que especifica um membro que contém "CN=TestUser,DC=Fabrikam,DC=COM":

(member=CN=TestUser,DC=Fabrikam,DC=COM)

INTEGER8

O valor especificado em um filtro deve ser um inteiro decimal. Converter valores hexadecimais em decimais.

O exemplo de código a seguir mostra um filtro que especifica um creationTime definido como um FILETIME de "1999-12-31 23:59:59 (UTC/GMT)":

(creationTime=125911583990000000)

As funções a seguir criam um filtro de correspondência exata (=) para um atributo inteiro grande e verificam o atributo no esquema e sua sintaxe:

//***************************************************************************
//
//  CheckAttribute()
//
//***************************************************************************

HRESULT CheckAttribute(LPOLESTR szAttribute, LPOLESTR szSyntax)
{
    HRESULT hr = E_FAIL;
    BSTR bstr;
    IADsProperty *pObject = NULL;
    LPWSTR szPrefix = L"LDAP://schema/";
    LPWSTR szPath;
     
    if((!szAttribute) || (!szSyntax))
    {
        return E_POINTER;
    }

    // Allocate a buffer large enough to hold the ADsPath of the attribute.
    szPath = new WCHAR[lstrlenW(szPrefix) + lstrlenW(szAttribute) + 1];
    if(NULL == szPath)
    {
        return E_OUTOFMEMORY;
    }
     
    // Create the ADsPath of the attribute.
    wcscpy_s(szPath, szPrefix);
    wcscat_s(szPath, szAttribute);

    hr = ADsOpenObject( szPath,
                        NULL,
                        NULL,
                        ADS_SECURE_AUTHENTICATION, // Use Secure Authentication.
                        IID_IADsProperty,
                        (void**)&pObject);
    if(SUCCEEDED(hr)) 
    {
        hr = pObject->get_Syntax(&bstr);
        if (SUCCEEDED(hr)) 
        {
            if (0==lstrcmpiW(bstr, szSyntax)) 
            {
                hr = S_OK;
            }
            else
            {
                hr = S_FALSE;
            }
        }

        SysFreeString(bstr);
    }
    
    if(pObject)
    {
        pObject->Release();
    }

    delete szPath;
    
    return hr;
}

//***************************************************************************
//
//  CreateExactMatchFilterLargeInteger()
//
//***************************************************************************

HRESULT CreateExactMatchFilterLargeInteger( LPOLESTR szAttribute, 
                                            INT64 liValue, 
                                            LPOLESTR *pszFilter)
{
    HRESULT hr = E_FAIL;
     
    if ((!szAttribute) || (!pszFilter))
    {
        return E_POINTER;
    }
     
    // Verify that the attribute exists and has 
    // Integer8 (Large Integer) syntax.
     
    hr = CheckAttribute(szAttribute, L"Integer8");
    if (S_OK == hr) 
    {
        LPWSTR szFormat = L"%s=%I64d";
        LPWSTR szTempFilter = new WCHAR[lstrlenW(szFormat) + lstrlenW(szAttribute) + 20 + 1];

        if(NULL == szTempFilter)
        {
            return E_OUTOFMEMORY;
        }
        
        swprintf_s(szTempFilter, L"%s=%I64d", szAttribute, liValue);
     
        // Allocate buffer for the filter string.
        // Caller must free the buffer using CoTaskMemFree.
        *pszFilter = (OLECHAR *)CoTaskMemAlloc(sizeof(OLECHAR) * (lstrlenW(szTempFilter) + 1));
        if (*pszFilter) 
        {
            wcscpy_s(*pszFilter, szTempFilter);
            hr = S_OK;
        }
        else
        {
            hr = E_OUTOFMEMORY;
        }

        delete szTempFilter;
    }

    return hr;
}

PrintableString

Os atributos com essas sintaxes devem aderir a conjuntos de caracteres específicos. Para obter mais informações, consulte Syntaxes for Attributes in Active Directory Domain Services.

Atualmente, os Serviços de Domínio Active Directory não impõem esses conjuntos de caracteres.

O valor especificado em um filtro é uma cadeia de caracteres. A comparação diferencia maiúsculas de minúsculas.

Tempo Generalizado

O valor especificado em um filtro é uma cadeia de caracteres que representa a data da seguinte forma:

YYYYMMDDHHMMSS.0Z

"0Z" indica que não há diferencial de tempo. Lembre-se de que o servidor do Active Directory armazena data/hora como Greenwich Mean Time (GMT). Se um diferencial de tempo não for especificado, o padrão será GMT.

Se o fuso horário local não for GMT, use um valor diferencial para especificar o fuso horário local e aplique o diferencial ao GMT. O diferencial é baseado em: GMT=Local+diferencial.

Para especificar um diferencial, use:

YYYYMMDDHHMMSS.0[+/-]HHMM

O exemplo a seguir mostra um filtro que especifica um time whenCreated definido como 23/03/99 8:52:58 PM GMT:

(whenCreated=19990323205258.0Z)

O exemplo a seguir mostra um filtro que especifica um horário whenCreated definido como 23/03/99 8:52:58 PM Hora Padrão da Nova Zelândia (diferencial é +12 horas):

(whenCreated=19990323205258.0+1200)

O exemplo de código a seguir mostra como calcular o diferencial de fuso horário. A função retorna o diferencial entre o fuso horário local atual e o GMT. O valor retornado é uma cadeia de caracteres no seguinte formato:

[+/-]HHMM

Por exemplo, a hora padrão do Pacífico é -0800.

//***************************************************************************
//
//  GetLocalTimeZoneDifferential()
//
//***************************************************************************

HRESULT GetLocalTimeZoneDifferential(LPOLESTR *pszDifferential)
{
    if(NULL == pszDifferential)
    {
        return E_INVALIDARG;
    }
    
    HRESULT hr = E_FAIL;
    DWORD dwReturn;
    TIME_ZONE_INFORMATION timezoneinfo;
    LONG lTimeDifferential;
    LONG lHours;
    LONG lMinutes;
    
    dwReturn  = GetTimeZoneInformation(&timezoneinfo);

    switch (dwReturn)
    {
    case TIME_ZONE_ID_STANDARD:
        lTimeDifferential = timezoneinfo.Bias + timezoneinfo.StandardBias;
        
        // Bias is in minutes. Calculate the hours for HHMM format.
        lHours = -(lTimeDifferential/60);
        
        // Bias is in minutes. Calculate the minutes for HHMM format.
        lMinutes = lTimeDifferential%60L;

        hr = S_OK;
        break;

    case TIME_ZONE_ID_DAYLIGHT:
        lTimeDifferential = timezoneinfo.Bias + timezoneinfo.DaylightBias;
        
        // Bias is in minutes. Calculate the hours for HHMM format.
        // Apply the additive inverse.
        // Bias is based on GMT=Local+Bias.
        // A differential, based on GMT=Local-Bias, is required.
        lHours = -(lTimeDifferential/60);
        
        // Bias is in minutes. Calculate the minutes for HHMM format.
        lMinutes = lTimeDifferential%60L;
        
        hr = S_OK;
        break;

    case TIME_ZONE_ID_INVALID:
    default:
        hr = E_FAIL;
        break;
    }
     
    if (SUCCEEDED(hr))
    {
        // The caller must free the memory using CoTaskMemFree.
        *pszDifferential = (OLECHAR *)CoTaskMemAlloc(sizeof(OLECHAR) * (3 + 2 + 1));
        if (*pszDifferential)
        {
            swprintf_s(*pszDifferential, L"%+03d%02d", lHours, lMinutes);
            
            hr = S_OK;
        }
        else
        {
            hr = E_OUTOFMEMORY;
        }
    }
     
    return hr;
}

UTCTime

O valor especificado em um filtro é uma cadeia de caracteres que representa a data da seguinte forma:

YYMMDDHHMMSSZ

Z indica que não há diferencial de tempo. Lembre-se de que o servidor do Active Directory armazena data e hora como hora GMT. Se um diferencial de tempo não for especificado, GMT será o padrão.

O valor de segundos ("SS") é opcional.

Se GMT não for o fuso horário local, aplique um valor diferencial local para especificar o fuso horário local. O diferencial é: GMT=Local+diferencial.

Para especificar um diferencial, use o seguinte formulário:

YYMMDDHHMMSS[+/-]HHMM

O exemplo a seguir mostra um filtro que especifica um horário myTimeAttrib definido como 23/03/99 8:52:58 PM GMT:

(myTimeAttrib=990323205258Z)

O exemplo a seguir mostra um filtro que especifica um tempo myTimeAttrib definido como 23/03/99 20:52:58 PM sem segundos especificados:

(myTimeAttrib=9903232052Z)

O exemplo a seguir mostra um filtro que especifica um horário myTimeAttrib definido como 23/03/99 20:52:58 PM Hora Padrão da Nova Zelândia (diferencial é de 12 horas). Isso equivale a 23/03/99 08:52:58 AM GMT.

(myTimeAttrib=990323205258+1200)

DirectoryString

O valor especificado em um filtro é uma cadeia de caracteres. DirectoryString pode conter caracteres Unicode. A comparação não diferencia maiúsculas de minúsculas.

OID

Todo o OID a ser correspondido deve ser fornecido.

Curingas não são aceitos.

O atributo objectCategory permite especificar o lDAPDisplayName do conjunto de classes para o atributo.

O exemplo a seguir mostra um filtro que especifica governsID para a classe de volume:

(governsID=1.2.840.113556.1.5.36)

Dois filtros equivalentes que especificam o atributo systemMustContain que contém uNCName, que tem um OID de 1.2.840.113556.1.4.137:

(SystemMustContain=uNCName)
 
(SystemMustContain=1.2.840.113556.1.4.137)

Outras Sintaxe

As seguintes sintaxes são avaliadas em um filtro semelhante a uma cadeia de caracteres de octeto:

ObjectSecurityDescriptor
AccessPointDN
PresentationAddresses
ReplicaLink
DNWithString
DNWithOctetString
ORName

Como especificar valores de comparação

Comentários

Comentários

Recursos adicionais