Função WdfPdoInitAddDeviceText (wdfpdo.h)

[Aplica-se somente ao KMDF]

O método WdfPdoInitAddDeviceText adiciona uma descrição do dispositivo e o local do dispositivo a um dispositivo para uma localidade especificada.

Sintaxe

NTSTATUS WdfPdoInitAddDeviceText(
  [in] PWDFDEVICE_INIT  DeviceInit,
  [in] PCUNICODE_STRING DeviceDescription,
  [in] PCUNICODE_STRING DeviceLocation,
  [in] LCID             LocaleId
);

Parâmetros

[in] DeviceInit

Um ponteiro para uma estrutura WDFDEVICE_INIT .

[in] DeviceDescription

Um ponteiro para uma estrutura UNICODE_STRING que contém uma descrição do dispositivo, formatada para a localidade fornecida. O driver pode alocar o buffer da cadeia de caracteres do pool paginado.

[in] DeviceLocation

Um ponteiro para uma estrutura UNICODE_STRING que contém uma descrição do local no barramento em que o dispositivo pai encontrou o filho. O driver pode alocar o buffer da cadeia de caracteres do pool paginado.

[in] LocaleId

Um LCID (identificador de localidade) que representa a localidade das cadeias de caracteres Unicode. Para obter mais informações, consulte Identificadores de localidade.

Retornar valor

Se a operação for bem-sucedida, o método retornará STATUS_SUCCESS. Os valores de retorno adicionais incluem:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	O driver está inicializando um FDO em vez de um PDO.
STATUS_INSUFFICIENT_RESOURCES	O driver não pôde alocar espaço para armazenar as cadeias de caracteres.

 

O método também pode retornar outros valores NTSTATUS.

Comentários

A estrutura armazena o texto do dispositivo especificado e o passa para o gerenciador PnP em resposta a uma solicitação de IRP_MN_QUERY_DEVICE_TEXT . O texto que você fornece deve ajudar o usuário a identificar o dispositivo. Às vezes, o gerenciador PnP exibe o texto ao tentar instalar drivers adicionais para o dispositivo.

Você pode chamar WdfPdoInitAddDeviceText várias vezes, adicionando texto do dispositivo para várias localidades. Quando o sistema exibe o texto, ele escolhe o texto que corresponde à localidade atual, se disponível. Caso contrário, ele usará a cadeia de caracteres para a localidade padrão. O driver pode especificar a localidade padrão do driver chamando WdfPdoInitSetDefaultLocale.

O driver deve chamar WdfPdoInitAddDeviceText antes de chamar WdfDeviceCreate. Para obter mais informações sobre como chamar WdfDeviceCreate, consulte Criando um objeto de dispositivo de estrutura.

Exemplos

O exemplo de código a seguir fornece cadeias de caracteres Unicode para o local e a descrição de um dispositivo. A descrição inclui um número de instância. Para obter um exemplo completo que usa WdfPdoInitAddDeviceText, consulte o driver de exemplo KbFiltr .

DECLARE_CONST_UNICODE_STRING(deviceLocation,L"Keyboard Filter\0" );
DECLARE_UNICODE_STRING_SIZE(buffer, MAX_ID_LEN);

status = RtlUnicodeStringPrintf(
                                &buffer,
                                L"Keyboard_Filter_%02d",
                                InstanceNo
                                );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}
status = WdfPdoInitAddDeviceText(
                                 pDeviceInit,
                                 &buffer,
                                 &deviceLocation,
                                 0x409
                                 );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfpdo.h (include Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	ChildDeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCallback(kmdf), PdoInitFreeDeviceCreate(kmdf)

Confira também

WdfPdoInitSetDefaultLocale