Функция ResUtilPropertyListFromParameterBlock (resapi.h)

Статья
08/25/2023

Создает список свойств из таблицы свойств и блока параметров.

Синтаксис

DWORD ResUtilPropertyListFromParameterBlock(
  [in]            const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  [out, optional] PVOID                        pOutPropertyList,
  [in, out]       LPDWORD                      pcbOutPropertyListSize,
  [in]            const LPBYTE                 pInParams,
  [out]           LPDWORD                      pcbBytesReturned,
  [out]           LPDWORD                      pcbRequired
);

Параметры

[in] pPropertyTable

Указатель на таблицу свойств, описывающую свойства, которые будут включены в результирующий список свойств.

[out, optional] pOutPropertyList

Указатель на выходной буфер, который получает список свойств.

[in, out] pcbOutPropertyListSize

Указатель на размер выходного буфера в байтах.

[in] pInParams

Указатель на блок параметров, в котором хранятся значения свойств.

[out] pcbBytesReturned

Если функция возвращает ERROR_SUCCESS, pcbBytesReturned указывает на фактический размер байтов списка свойств, на который указывает pOutPropertyList. Если функция не возвращает ERROR_SUCCESS, pcbBytesReturned указывает на нулевое значение.

[out] pcbRequired

Если функция возвращает ERROR_MORE_DATA, pcbRequired указывает на размер байтов, необходимый для хранения списка свойств. Если функция не возвращает ERROR_MORE_DATA, pcbBytesReturned указывает на нулевое значение.

Возвращаемое значение

Если операция выполнена успешно, функция возвращает ERROR_SUCCESS.

Если операция завершается сбоем, функция возвращает код системной ошибки. Ниже приведены возможные коды ошибок.

Код возврата	Описание
ERROR_MORE_DATA	Выходной буфер слишком мал, чтобы содержать результирующий список свойств.
ERROR_BAD_ARGUMENTS	Один или несколько входных параметров были недопустимыми.
ERROR_NOT_ENOUGH_MEMORY	Произошла ошибка при выделении памяти.

В этой функции таблица свойств определяет порядок отображения свойств в списке свойств, а также имя и формат каждого свойства. Функция считывает таблицу свойств, чтобы определить имя и формат каждого свойства.

Блок параметров предоставляет значения свойств.

Примеры

В следующем примере определяются три свойства (Protocol, PortNumber и ConnectionName). Для создания списка свойств используется функция ResUtilPropertyListFromParameterBlock . В этом примере используется файл заголовка ClusDocEx.h , определенный в документации по отказоустойчивости кластера.

//////////////////////////////////////////////////////////////////////

//  Be sure to create the following file before you compile.
//  For a code listing, see "ClusDocEx.h".
    #include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

//  This example defines three fictional properties: 
//      Protocol (DWORD)
//      PortNumber (DWORD)
//      ConnectionName (PWSTR)
//  These properties are not associated with any cluster object.
//  They are used only to demonstrate the
//  ResUtilPropertyListFromParameterBlock function.

//  Protocol property constants
    #define PROP_NAME__PROTOCOL       L"Protocol"
    typedef enum PROTOCOLS{
        PROTOCOL_NONE = 0,
        PROTOCOL_BOTH = 1,
        PROTOCOL_TCP  = 2,
        PROTOCOL_UDP  = 3
    };
    #define PROP_MIN__PROTOCOL       (PROTOCOL_NONE)
    #define PROP_MAX__PROTOCOL       (PROTOCOL_UDP)
    #define PROP_DEFAULT__PROTOCOL   (PROTOCOL_BOTH)

//  PortNumber property
    #define PROP_NAME__PORTNUMBER     L"PortNumber"
    #define PROP_MIN__PORTNUMBER      (0)
    #define PROP_MAX__PORTNUMBER      (65536)
    #define PROP_DEFAULT__PORTNUMBER  (80)

//  ConnectionName property
    #define PROP_NAME__CONNECTIONNAME L"ConnectionName"

//  Parameter block
    typedef struct _PARAMBLOCK{
        DWORD dwProtocol;
        DWORD dwPortNumber;
        PWSTR pszConnectionName;
    } PARAMBLOCK; 
    
//  Property table
    RESUTIL_PROPERTY_ITEM
    pPropTable[] =
    {
        {   PROP_NAME__PROTOCOL, 
            NULL, 
            CLUSPROP_FORMAT_DWORD, 
            PROP_DEFAULT__PROTOCOL, 
            PROP_MIN__PROTOCOL, 
            PROP_MAX__PROTOCOL, 
            RESUTIL_PROPITEM_REQUIRED,  
            FIELD_OFFSET( _PARAMBLOCK, dwProtocol )        },

        {   PROP_NAME__PORTNUMBER,
            NULL, 
            CLUSPROP_FORMAT_DWORD, 
            PROP_DEFAULT__PORTNUMBER, 
            PROP_MIN__PORTNUMBER, 
            PROP_MAX__PORTNUMBER, 
            RESUTIL_PROPITEM_REQUIRED, 
            FIELD_OFFSET( _PARAMBLOCK, dwPortNumber )      },

        {   PROP_NAME__CONNECTIONNAME, 
            NULL, 
            CLUSPROP_FORMAT_SZ, 
                0, 0, 0, 0,
            FIELD_OFFSET( _PARAMBLOCK, pszConnectionName ) },

        { 0 }
    };

    int main()
    {
        DWORD nResult    = ERROR_SUCCESS,
              cbBufSize  = 1024,
              cbReturned = 0,
              cbRequired = 0;

        PVOID pPropList = LocalAlloc( LPTR, cbBufSize );

    //  Values for the property list
        PARAMBLOCK NewParams = { PROTOCOL_TCP, 21, L"FTP" };

        nResult = ResUtilPropertyListFromParameterBlock(
                      pPropTable,
                      pPropList,
                      &cbBufSize,
                      (LPBYTE) &NewParams,
                      &cbReturned,
                      &cbRequired );

        if( nResult == ERROR_MORE_DATA )
        {
            LocalFree( pPropList );

            cbBufSize = cbRequired;
            
            pPropList = LocalAlloc( LPTR, cbBufSize );

            nResult = ResUtilPropertyListFromParameterBlock(
                          pPropTable,
                          pPropList,
                          &cbBufSize,
                          (PBYTE) &NewParams,
                          &cbReturned,
                          &cbRequired );
        }

        ClusDocEx_DebugPrint( L"Results:", nResult );

        if( nResult == ERROR_SUCCESS )
            ClusDocEx_ShowBuffer( pPropList, cbReturned );    
    
        LocalFree( pPropList );
    
        return (int)( nResult != ERROR_SUCCESS );    
    }

Требования

Требование	Значение
Минимальная версия клиента	Ни одна версия не поддерживается
Минимальная версия сервера	Windows Server 2008 Корпоративная, Windows Server 2008 Datacenter
Целевая платформа	Windows
Header	resapi.h
Библиотека	ResUtils.lib
DLL	ResUtils.dll

См. также раздел

RESUTIL_PROPERTY_ITEM

Поделиться через