CLUSPROP_BUFFER_HELPER union (clusapi.h)
Used to build or parse a property list or, a value list.
Syntax
typedef union CLUSPROP_BUFFER_HELPER {
BYTE *pb;
WORD *pw;
DWORD *pdw;
LONG *pl;
LPWSTR psz;
PCLUSPROP_LIST pList;
PCLUSPROP_SYNTAX pSyntax;
PCLUSPROP_PROPERTY_NAME pName;
PCLUSPROP_VALUE pValue;
PCLUSPROP_BINARY pBinaryValue;
PCLUSPROP_WORD pWordValue;
PCLUSPROP_DWORD pDwordValue;
PCLUSPROP_LONG pLongValue;
PCLUSPROP_ULARGE_INTEGER pULargeIntegerValue;
PCLUSPROP_LARGE_INTEGER pLargeIntegerValue;
PCLUSPROP_SZ pStringValue;
PCLUSPROP_MULTI_SZ pMultiSzValue;
PCLUSPROP_SECURITY_DESCRIPTOR pSecurityDescriptor;
PCLUSPROP_RESOURCE_CLASS pResourceClassValue;
PCLUSPROP_RESOURCE_CLASS_INFO pResourceClassInfoValue;
PCLUSPROP_DISK_SIGNATURE pDiskSignatureValue;
PCLUSPROP_SCSI_ADDRESS pScsiAddressValue;
PCLUSPROP_DISK_NUMBER pDiskNumberValue;
PCLUSPROP_PARTITION_INFO pPartitionInfoValue;
PCLUSPROP_REQUIRED_DEPENDENCY pRequiredDependencyValue;
PCLUSPROP_PARTITION_INFO_EX pPartitionInfoValueEx;
PCLUSPROP_PARTITION_INFO_EX2 pPartitionInfoValueEx2;
PCLUSPROP_FILETIME pFileTimeValue;
} CLUSPROP_BUFFER_HELPER, *PCLUSPROP_BUFFER_HELPER;
Members
pb
Pointer to a buffer containing an array of bytes.
pw
Pointer to a buffer containing an array of WORD values.
pdw
Pointer to a buffer containing an array of DWORD values.
pl
Pointer to a buffer containing an array of signed long values.
psz
Pointer to a buffer containing a NULL-terminated Unicode string value.
pList
Pointer to a CLUSPROP_LIST structure describing the beginning of a property list.
pSyntax
Pointer to a CLUSPROP_SYNTAX structure describing the format and type of a value.
pName
Pointer to a CLUSPROP_PROPERTY_NAME structure containing a property name value.
pValue
Pointer to a CLUSPROP_VALUE structure describing the format, type, and length of a data value.
pBinaryValue
Pointer to a CLUSPROP_BINARY structure containing a binary data value.
pWordValue
Pointer to a CLUSPROP_WORD structure containing a numeric value.
pDwordValue
Pointer to a CLUSPROP_DWORD structure containing a numeric value.
pLongValue
Pointer to a CLUSPROP_LONG structure containing a signed long value.
pULargeIntegerValue
Pointer to a CLUSPROP_ULARGE_INTEGER structure containing an unsigned large integer value.
pLargeIntegerValue
Pointer to a CLUSPROP_LARGE_INTEGER structure containing a large integer value.
pStringValue
Pointer to a CLUSPROP_SZ structure containing a NULL-terminated Unicode string value.
pMultiSzValue
Pointer to a CLUSPROP_MULTI_SZ structure containing multiple null-terminated Unicode string values.
pSecurityDescriptor
Pointer to a CLUSPROP_SECURITY_DESCRIPTOR structure containing a security descriptor.
pResourceClassValue
Pointer to a CLUSPROP_RESOURCE_CLASS structure containing a resource class value.
pResourceClassInfoValue
Pointer to a CLUSPROP_RESOURCE_CLASS_INFO structure containing a resource class information value.
pDiskSignatureValue
Pointer to a CLUSPROP_DISK_SIGNATURE structure containing a disk signature value.
pScsiAddressValue
Pointer to a CLUSPROP_SCSI_ADDRESS structure containing an SCSI address value.
pDiskNumberValue
Pointer to a CLUSPROP_DISK_NUMBER structure containing a disk number value.
pPartitionInfoValue
Pointer to a CLUSPROP_PARTITION_INFO structure containing a partition information value.
pRequiredDependencyValue
Pointer to a CLUSPROP_REQUIRED_DEPENDENCY structure containing a resource dependency value.
pPartitionInfoValueEx
Pointer to a CLUSPROP_PARTITION_INFO_EX structure containing a partition information value.
pPartitionInfoValueEx2
A pointer to a CLUSPROP_PARTITION_INFO_EX2 structure that contains a partition information value.
Windows Server 2012 R2, Windows Server 2012, Windows Server 2008 R2 and Windows Server 2008: This member is not available before Windows Server 2016.
pFileTimeValue
Pointer to a CLUSPROP_FILETIME structure containing a date/time value.
Remarks
The CLUSPROP_BUFFER_HELPER structure is useful in working with property and value lists. Applications can use a generic CLUSPROP_BUFFER_HELPER pointer to advance by offsets through the entries of a property list or value list, retrieving or setting values without having to cast to the appropriate data type.
An alternate structure, RESUTIL_PROPERTY_ITEM, can also be used to work with multiple properties.
Use caution when referencing large integer values in DWORD-aligned structures such as value lists, property lists, and parameter blocks. For Windows Server for Itanium-based systems, a naturally-aligned large integer value always begins on an address ending in 0 or 8h. DWORD alignment can cause large values to begin on unaligned boundaries (addresses ending in 4h or C), which will cause an alignment fault when the data is read or written. You can avoid alignment faults by handling the high and low parts of large values separately, or by using local variables, which are guaranteed to be naturally aligned.
Examples
In addition to the following example, see Creating Property Lists, Parsing Property Lists, Creating Value Lists, and Parsing a Value List.
//////////////////////////////////////////////////////////////////////
//
// HOW TO USE CLUSPROP_BUFFER HELPER
//
// (1) Position cbh to the next read or write location.
// (2) Read or write data using an appropriate pointer.
// (3) Check position within buffer.
//
// Repeat (1)(2)(3)
//
//////////////////////////////////////////////////////////////////////
void ClusDocEx_UsingCBH()
{
LPVOID lp = LocalAlloc( LPTR, 100 ); // It is important for cbh
// to know the allocated
// size.
CLUSPROP_BUFFER_HELPER cbh;
// ( 1 )
//
// Position cbh. The pb member is convenient for
// targeting single bytes.
//
cbh.pb = (LPBYTE) lp;
//
// The pb member points to the first byte of lp.
//
// lp -----> 0 0 0 0 0 0 0 0 0 0 0 ... 0
//
// cbh.pb-->|-|
//
//
// Note what happens when different cbh pointer types are used:
//
// lp -----> 0 0 0 0 0 0 0 0 0 0 0 0 ... 0
//
// cbh.pdw -->|-------|
// cbh.psz -->|-|
// cbh.pValue -->|---------------|
// cbh.pValue->Syntax.dw-->|-------|
// cbh.pValue->cbLength -->|-------|
//
//
// The configuration of bytes that will be affected by a read
// or write operation depends on the type of pointer used.
//
// ( 2 )
//
// Read or write data to the present location. Note how the
// structure pointers let you "reach over" intervening members.
//
cbh.pValue->Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
cbh.pValue->cbLength = sizeof( DWORD );
cbh.pDwordValue->dw = 0x0000EEEEL;
//
// Result: lp ----->| syntax | length | value | 0 0 0 0 ... 0
//
// ( 3 )
//
// Check your remaining space. Be sure you have room to advance
// cbh past the current data and perform a read operation on the
// next value.
//
DWORD cbPosition = cbh.pb - (LPBYTE) lp;
DWORD cbAdvance = ClusDocEx_ListEntrySize( sizeof( DWORD ) ); // See "ClusDocEx.h"
if( ( cbPosition + cbAdvance + sizeof( DWORD ) ) > 100 )
{
// handle the fact that there's more data than the reported size of the buffer
}
//
// Repeat ( 1 ), ( 2 ), and ( 3 ) for the next value:
//
// Position cbh
cbh.pb += cbAdvance;
// Write next entry
cbh.pStringValue->Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
cbh.pStringValue->cbLength = ( lstrlenW( L"String Value" ) + 1 ) * sizeof( WCHAR );
StringCchCopyW( cbh.pStringValue->sz, cbh.pStringValue->cbLength, L"String Value" );
// Check space
cbPosition = cbh.pb - (LPBYTE) lp;
cbAdvance = ClusDocEx_ListEntrySize( cbh.pStringValue->cbLength );
if( ( cbPosition + cbAdvance + sizeof( DWORD ) ) > 100 )
{
//
}
//
// Repeat ( 1 ), ( 2 ), and ( 3 ) until all values have been written or read.
//
cbh.pb = NULL;
LocalFree( lp );
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | None supported |
| Minimum supported server | Windows Server 2008 Enterprise, Windows Server 2008 Datacenter |
| Header | clusapi.h |