ホーム › Networking.ActiveDirectory › ADsEncodeBinaryData

ADsEncodeBinaryData

関数

バイナリデータをエスケープ済み文字列へエンコードする。

DLLACTIVEDS.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// ACTIVEDS.dll
#include <windows.h>

HRESULT ADsEncodeBinaryData(
    BYTE* pbSrcData,
    DWORD dwSrcLen,
    LPWSTR* ppszDestData
);

パラメーター

名前	型	方向	説明
pbSrcData	BYTE*	inout	変換する BLOB。
dwSrcLen	DWORD	in	BLOB のサイズ (バイト単位)。
ppszDestData	LPWSTR*	out	変換されたデータを受け取る、null で終わる Unicode 文字列へのポインター。

戻り値の型: HRESULT

公式ドキュメント

ADsEncodeBinaryData 関数は、バイナリラージオブジェクト (BLOB) を、検索フィルターに埋め込むのに適した Unicode 形式に変換します。

戻り値

型: HRESULT

このメソッドは、標準の戻り値に加えて次の値をサポートします。

解説(Remarks)

ADSI では、検索フィルターは Unicode 文字列でなければなりません。フィルターには、通常は不透明なデータの BLOB として表現されるデータが含まれる場合があります。たとえば、バイナリデータであるオブジェクトのセキュリティ識別子を検索フィルターに含めたい場合があります。この場合、まず ADsEncodeBinaryData 関数を呼び出して、バイナリデータを Unicode 文字列形式に変換する必要があります。データが不要になったら、FreeADsMem 関数を呼び出して、変換された Unicode 文字列 (すなわち ppszDestData) を解放します。

ADsEncodeBinaryData 関数は、英数字を表すバイト値をエンコードしません。代わりに、その文字をエンコードせずに文字列へ格納します。その結果、文字列にはエンコードされた文字とエンコードされていない文字が混在します。たとえば、バイナリデータが 0x05|0x1A|0x1B|0x43|0x32 の場合、エンコードされた文字列は "\05\1A\1BC2" になります。これはフィルターに影響を与えず、検索フィルターはこの種の文字列でも正しく動作します。

例

次のコード例は、この関数の使用方法を示しています。

// フィルター内でバイナリ値をテストし、ExecuteSearch では
// 文字列フィルターではなくバイナリ フィルターを使用します。

LPWSTR pszPrefix = L"objectSid=%s";
LPWSTR pszBinaryFilter = NULL;
LPWSTR pszDest = NULL;
HRESULT hr = S_OK;
 
BYTE column[] = {
  0x01, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00, 0x05, 0x15, 0x00,
  0x00, 0x00, 0x59, 0x51, 0xb8, 0x17, 0x66, 0x72, 0x5d, 0x25,
  0x64, 0x63, 0x3b, 0x0b, 0x29, 0x99, 0x21, 0x00 };

DWORD dwSize = sizeof(column)/sizeof(BYTE);
 
hr = ADsEncodeBinaryData (
    column,
    dwSize,
    &pszDest
    );

if(hr==S_OK)
{
    dwSize = wcslen(pszPrefix) + wcslen(pszDest) + 1;
    pszBinaryFilter = new WCHAR[dwSize];
    sprintf_s(pszBinaryFilter,pszPrefix,pszDest);
}
else
{
    return hr;
}


 
// pszDest をフィルター文字列として検索を実行します。コードは省略。
. . . 
// 検索が完了したら、変換された文字列を解放します。
FreeADsMem( pszDest );

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ACTIVEDS.dll
#include <windows.h>

HRESULT ADsEncodeBinaryData(
    BYTE* pbSrcData,
    DWORD dwSrcLen,
    LPWSTR* ppszDestData
);

[DllImport("ACTIVEDS.dll", ExactSpelling = true)]
static extern int ADsEncodeBinaryData(
    IntPtr pbSrcData,   // BYTE* in/out
    uint dwSrcLen,   // DWORD
    IntPtr ppszDestData   // LPWSTR* out
);

<DllImport("ACTIVEDS.dll", ExactSpelling:=True)>
Public Shared Function ADsEncodeBinaryData(
    pbSrcData As IntPtr,   ' BYTE* in/out
    dwSrcLen As UInteger,   ' DWORD
    ppszDestData As IntPtr   ' LPWSTR* out
) As Integer
End Function

' pbSrcData : BYTE* in/out
' dwSrcLen : DWORD
' ppszDestData : LPWSTR* out
Declare PtrSafe Function ADsEncodeBinaryData Lib "activeds" ( _
    ByVal pbSrcData As LongPtr, _
    ByVal dwSrcLen As Long, _
    ByVal ppszDestData As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

ADsEncodeBinaryData = ctypes.windll.activeds.ADsEncodeBinaryData
ADsEncodeBinaryData.restype = ctypes.c_int
ADsEncodeBinaryData.argtypes = [
    ctypes.POINTER(ctypes.c_ubyte),  # pbSrcData : BYTE* in/out
    wintypes.DWORD,  # dwSrcLen : DWORD
    ctypes.c_void_p,  # ppszDestData : LPWSTR* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ACTIVEDS.dll')
ADsEncodeBinaryData = Fiddle::Function.new(
  lib['ADsEncodeBinaryData'],
  [
    Fiddle::TYPE_VOIDP,  # pbSrcData : BYTE* in/out
    -Fiddle::TYPE_INT,  # dwSrcLen : DWORD
    Fiddle::TYPE_VOIDP,  # ppszDestData : LPWSTR* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "activeds")]
extern "system" {
    fn ADsEncodeBinaryData(
        pbSrcData: *mut u8,  // BYTE* in/out
        dwSrcLen: u32,  // DWORD
        ppszDestData: *mut *mut u16  // LPWSTR* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ACTIVEDS.dll")]
public static extern int ADsEncodeBinaryData(IntPtr pbSrcData, uint dwSrcLen, IntPtr ppszDestData);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ACTIVEDS_ADsEncodeBinaryData' -Namespace Win32 -PassThru
# $api::ADsEncodeBinaryData(pbSrcData, dwSrcLen, ppszDestData)

#uselib "ACTIVEDS.dll"
#func global ADsEncodeBinaryData "ADsEncodeBinaryData" sptr, sptr, sptr
; ADsEncodeBinaryData varptr(pbSrcData), dwSrcLen, varptr(ppszDestData)   ; 戻り値は stat
; pbSrcData : BYTE* in/out -> "sptr"
; dwSrcLen : DWORD -> "sptr"
; ppszDestData : LPWSTR* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ACTIVEDS.dll"
#cfunc global ADsEncodeBinaryData "ADsEncodeBinaryData" var, int, var
; res = ADsEncodeBinaryData(pbSrcData, dwSrcLen, ppszDestData)
; pbSrcData : BYTE* in/out -> "var"
; dwSrcLen : DWORD -> "int"
; ppszDestData : LPWSTR* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ACTIVEDS.dll"
#cfunc global ADsEncodeBinaryData "ADsEncodeBinaryData" sptr, int, sptr
; res = ADsEncodeBinaryData(varptr(pbSrcData), dwSrcLen, varptr(ppszDestData))
; pbSrcData : BYTE* in/out -> "sptr"
; dwSrcLen : DWORD -> "int"
; ppszDestData : LPWSTR* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。