ADsEncodeBinaryData function

The ADsEncodeBinaryData function converts a binary large object (BLOB) to the Unicode format suitable to be embedded in a search filter.

Syntax


HRESULT ADsEncodeBinaryData(
  _In_   PBYTE pbSrcData,
  _In_   DWORD dwSrcLen,
  _Out_  LPWSTR *ppszDestData
);

Parameters

pbSrcData [in]

Type: PBYTE

BLOB to be converted.

dwSrcLen [in]

Type: DWORD

Size, in bytes, of the BLOB.

ppszDestData [out]

Type: LPWSTR*

Pointer to a null-terminated Unicode string that receives the converted data.

Return value

Type: HRESULT

This method supports the standard return values, as well as the following.

Return codeDescription
E_ADS_BAD_PARAMETER

Invalid parameters. For example, the length of the source data is zero.

E_OUTOFMEMORY

Memory allocation failed.

S_OK

Operation succeeded.

 

Remarks

In ADSI, search filters must be Unicode strings. Sometimes, a filter contains data that is normally represented by an opaque BLOB of data. For example, you may want to include an object security identifier in a search filter, which is of binary data. In this case, you must first call the ADsEncodeBinaryData function to convert the binary data to the Unicode string format. When the data is no longer required, call the FreeADsMem function to free the converted Unicode string; that is, ppszDestData.

The ADsEncodeBinaryData function does not encode byte values that represent alpha-numeric characters. It will, instead, place the character into the string without encoding it. This results in the string containing a mixture of encoded and unencoded characters. For example, if the binary data is 0x05|0x1A|0x1B|0x43|0x32, the encoded string will contain "\05\1A\1BC2". This has no effect on the filter and the search filters will work correctly with these types of strings.

Examples

The following code example shows how to use this function.


// Test binary values in filters and use
// a binary filter instead of a string filter in 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;
}


 
// Perform the search with the pszDest as the filter string. Code omitted.
. . . 
// Done with the search and free the converted string.
FreeADsMem( pszDest );

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Adshlp.h

Library

Activeds.lib

DLL

Activeds.dll;
AdsLdpc.dll

See also

ADSI Error Codes
ADSI Functions
FreeADsMem

 

 

Show:
© 2014 Microsoft