如何指定比較值

發行項
05/11/2022

每個屬性類型都有一個語法，可決定您可以在該屬性的搜尋篩選中指定的比較數值型別。

下列各節說明每個屬性語法的需求。如需屬性語法的詳細資訊，請參閱Active Directory 網域服務中屬性的語法。

布林

篩選中指定的值必須是「TRUE」或「FALSE」的字串值。下列範例示範如何指定布林比較字串。

下列範例會搜尋 showInAdvancedViewOnly 設定為 TRUE的物件：

(showInAdvancedViewOnly=TRUE)

下列範例會搜尋 showInAdvancedViewOnly 設定為 FALSE的物件：

(showInAdvancedViewOnly=FALSE)

整數和列舉

篩選中指定的值必須是十進位整數。十六進位值必須轉換成十進位。值比較字串的格式如下：

<attribute name>:<value>

「 < attribute name > 」是屬性的 lDAPDisplayName ，而「 < value > 」是要用於比較的值。

下列程式碼範例顯示篩選準則，其會搜尋 groupType 值等於 ADS_GROUP_TYPE_UNIVERSAL_GROUP ( 8) 旗標和 ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000) 旗標的物件。這兩個旗標會結合相等0x80000008，其轉換成十進位2147483656。

(groupType=2147483656)

LDAP 比對規則運算子也可以用來執行位比較。如需比對規則的詳細資訊，請參閱搜尋篩選語法。下列程式碼範例顯示篩選準則，其會搜尋具有 groupType 且具有 ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) 位集的物件。

(groupType:1.2.840.113556.1.4.803:=2147483648))

OctetString

篩選中指定的值是要找到的資料。資料必須以兩個字元編碼的位元組字串表示，其中每個位元組前面都有反斜線 (\) 。例如，0x05的值會顯示在字串中為「\05」。

ADsEncodeBinaryData函式可用來建立二進位資料的編碼字串表示。 ADsEncodeBinaryData函式不會編碼代表英數位元的位元組值。相反地，它會將字元放入字串中，而不需編碼。這會產生包含編碼和未編碼字元混合的字串。例如，如果二進位資料0x05|0x1A|0x1B|0x43|0x32，編碼字串將會包含「\05\1A\1BC2」。這不會影響篩選準則，而且搜尋篩選準則會使用這些類型的字串正確運作。

可使用萬用字元。

下列程式碼範例顯示包含 SCHEMAIDGUID 編碼字串的篩選，其 GUID 值為「{BF967ABA-0DE6-11D0-A285-00AA003049E2}」：

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

希

篩選中指定的值是 SID 的編碼位元組字串表示。如需已編碼位元組字串的詳細資訊，請參閱本主題中的上一節，討論 OctetString 語法。

下列程式碼範例顯示包含 objectSid 編碼字串的篩選準則，其 SID 字串值為「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

必須提供要比對的整個辨別名稱。

不接受萬用字元。

請注意 ，objectCategory 屬性也可讓您在屬性上指定類別集的 lDAPDisplayName 。

下列範例顯示一個篩選，指定包含「CN=TestUser，DC=Fabrikam，DC=COM」 的成員 ：

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

INTEGER8

篩選中指定的值必須是十進位整數。將十六進位值轉換成十進位。

下列程式碼範例顯示一個篩選，指定creationTime設定為「1999-12-31 23：59：59 (UTC/GMT) 」：

(creationTime=125911583990000000)

下列函式會針對大型整數屬性建立完全相符 (=) 篩選，並確認架構及其語法中的屬性：

//***************************************************************************
//
//  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

具有這些語法的屬性應遵守特定的字元集。如需詳細資訊，請參閱Active Directory 網域服務中屬性的語法。

目前，Active Directory 網域服務不會強制執行這些字元集。

篩選中指定的值為字串。比較會區分大小寫。

GeneralizedTime

篩選中指定的值是字串，代表下列格式的日期：

YYYYMMDDHHMMSS.0Z

「0Z」表示沒有時間差異。請注意，Active Directory 伺服器會將日期/時間儲存為 Greenwich Mean Time (GMT) 。如果未指定時間差異，預設值為 GMT。

如果當地時區不是 GMT，請使用差異值來指定當地時區，並將差異套用至 GMT。差異是以：GMT=Local+differential 為基礎。

若要指定差異，請使用：

YYYYMMDDHHMMSS.0[+/-]HHMM

下列範例顯示一個篩選，指定 WhenCreated time 設為 3/23/99 8：52：58 PM GMT：

(whenCreated=19990323205258.0Z)

下列範例顯示一個篩選，指定 當建立 時間設定為 3/23/99 8：52：58 PM New Zealand Standard Time (差異為 +12 小時) ：

(whenCreated=19990323205258.0+1200)

下列程式碼範例示範如何計算時區差異。函式會傳回目前當地時區與 GMT 之間的差異。傳回的值是下列格式的字串：

[+/-]HHMM

例如，太平洋標準時間是 -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

篩選中指定的值是字串，代表下列格式的日期：

YYMMDDHHMMSSZ

Z 表示沒有時間差異。請注意，Active Directory 伺服器會將日期和時間儲存為 GMT 時間。如果未指定時間差異，GMT 是預設值。

秒值 (「SS」) 是選擇性的。

如果 GMT 不是當地時區，請套用本機差異值來指定您的當地時區。差異為：GMT=Local+differential。

若要指定差異，請使用下列形式：

YYMMDDHHMMSS[+/-]HHMM

下列範例顯示一個篩選，指定 myTimeAttrib 時間設定為 3/23/99 8：52：58 PM GMT：

(myTimeAttrib=990323205258Z)

下列範例顯示一個篩選，指定 myTimeAttrib 時間設定為 3/23/99 8：52：58 PM 且未指定秒：

(myTimeAttrib=9903232052Z)

下列範例顯示一個篩選準則，指定 myTimeAttrib 時間設定為 3/23/99 下午 8：52：58 PM 紐西蘭標準時間 (差異為 12 小時) 。這相當於 3/23/99 上午 8：52：58 GMT。

(myTimeAttrib=990323205258+1200)

DirectoryString

篩選中指定的值為字串。 DirectoryString 可以包含 Unicode 字元。此比較不區分大小寫。

老

必須提供要比對的整個 OID。

不接受萬用字元。

objectCategory屬性可讓您指定屬性之類別集的lDAPDisplayName。

下列範例顯示指定 volume 類別 governsID 的篩選準則：

(governsID=1.2.840.113556.1.5.36)

兩個對等篩選準則，指定包含uNCName的 systemMustContain屬性，其 OID 為 1.2.840.113556.1.4.137：

(SystemMustContain=uNCName)
 
(SystemMustContain=1.2.840.113556.1.4.137)

其他語法

下列語法會在類似八位字串的篩選中進行評估：

ObjectSecurityDescriptor
AccessPointDN
PresentationAddresses
ReplicaLink
DNWithString
DNWithOctetString
ORName