Método IWDFUnifiedPropertyStore::SetPropertyData (wudfddi.h)

Artigo
02/27/2024

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método SetPropertyData modifica a configuração atual de uma propriedade de dispositivo.

Sintaxe

HRESULT SetPropertyData(
  [in]           const DEVPROPKEY *PropertyKey,
  [in]           LCID             Lcid,
  [in]           ULONG            Flags,
  [in]           DEVPROPTYPE      PropertyType,
  [in]           ULONG            PropertyDataSize,
  [in, optional] PVOID            PropertyData
);

Parâmetros

[in] PropertyKey

Um ponteiro para uma estrutura DEVPROPKEY que especifica a chave de propriedade do dispositivo.

[in] Lcid

Especifica um identificador de localidade. Defina esse parâmetro como um valor LCID específico do idioma ou para LOCALE_NEUTRAL. O LCID LOCALE_NEUTRAL especifica que a propriedade é neutra em idioma (ou seja, não é específica de nenhum idioma). Não defina esse parâmetro como LOCALE_SYSTEM_DEFAULT ou LOCALE_USER_DEFAULT. Para obter mais informações sobre valores LCID específicos do idioma, consulte Estrutura LCID.

[in] Flags

Reservado. Os drivers devem definir esse valor como 0.

[in] PropertyType

Um ponteiro para um valor DEVPROPTYPE que especifica o tipo dos dados fornecidos no buffer PropertyData .

[in] PropertyDataSize

O tamanho, em bytes, do buffer para o qual PropertyData aponta.

[in, optional] PropertyData

Um ponteiro para os dados da propriedade do dispositivo. Defina esse parâmetro como NULL para excluir a propriedade especificada.

Retornar valor

SetPropertyData retornará S_OK se a operação for bem-sucedida. Caso contrário, o método poderá retornar os valores a seguir.

Código de retorno	Descrição
E_OUTOFMEMORY	Falha na tentativa da estrutura de alocar memória.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Se o driver especificar WdfPropertyStoreRootClassDeviceInterfaceKey, a interface solicitada deverá ser aquela que o driver UMDF registrou anteriormente.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	O driver pode modificar os dados da propriedade da interface do dispositivo apenas começando com Windows 8.

Esse método pode retornar um valor do tipo HRESULT correspondente a um dos outros valores que Winerror.h contém.

Comentários

Os drivers baseados em estrutura usam o método SetPropertyData para modificar as propriedades do dispositivo definidas como parte do modelo de propriedade do dispositivo unificado.

Em particular, você pode usar esse método para modificar a chave de hardware de um dispositivo ou uma instância de uma classe de interface do dispositivo. Quando você chamar IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, defina o membro RootClass do parâmetro RootSpecifier como WdfPropertyStoreRootClassHardwareKey ou WdfPropertyStoreRootClassDeviceInterfaceKey.

Se você especificar WdfPropertyStoreRootClassHardwareKey, ao chamar SetPropertyData, deverá fornecer um valor DEVPROPKEY personalizado no parâmetro PropertyKey e não uma chave definida por PnP. O valor deve ter sido definido anteriormente chamando SetPropertyData, uma função de propriedade de dispositivo SetupDI ou usando a diretiva INF AddProperty.

Se o driver especificar WdfPropertyStoreRootClassDeviceInterfaceKey, a interface solicitada deverá ser aquela que o driver UMDF registrou anteriormente no runtime.

Se o driver registrar uma interface em seu arquivo INF, ele também deverá definir propriedades associadas no INF.

Para obter mais informações sobre como acessar o registro, consulte Usando o Registro em Drivers baseados em UMDF.

Exemplos

HRESULT
SetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    WCHAR friendlyName[] = L"UMDF OSR USB Fx2 Test Device";

    hr = pUnifiedPropertyStore->SetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            DEVPROP_TYPE_STRING, //Type
            sizeof(friendlyName),
            friendlyName
            );

    if (FAILED(hr))
    {
        TraceEvents(
            TRACE_LEVEL_ERROR,
            TEST_TRACE_DEVICE,             
            "SetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }

exit:
    return hr;
}

Requisitos

Requisito	Valor
Fim do suporte	Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1.11
Cabeçalho	wudfddi.h
DLL	WUDFx.dll