função WDF_WMI_BUFFER_APPEND_STRING (wdfwmi.h)

  • Artigo

[Aplica-se somente ao KMDF]

A função WDF_WMI_BUFFER_APPEND_STRING copia uma cadeia de caracteres Unicode especificada em um buffer especificado no formato exigido pelo WMI.

Sintaxe

NTSTATUS WDF_WMI_BUFFER_APPEND_STRING(
  [out] PVOID            Buffer,
  [in]  ULONG            BufferLength,
  [in]  PCUNICODE_STRING String,
  [out] PULONG           RequiredSize
);

Parâmetros

[out] Buffer

Um ponteiro para um buffer de destino que recebe a cadeia de caracteres.

[in] BufferLength

O comprimento, em bytes, do buffer de destino que recebe a cadeia de caracteres.

[in] String

Um ponteiro para uma estrutura UNICODE_STRING que contém a cadeia de caracteres a ser copiada.

[out] RequiredSize

Um ponteiro para um local que recebe o número de bytes necessários para armazenar a cadeia de caracteres especificada no buffer de destino.

Retornar valor

WDF_WMI_BUFFER_APPEND_STRING retornará STATUS_SUCCESS se a operação for bem-sucedida. Se o buffer de destino for muito pequeno para conter a cadeia de caracteres Unicode especificada pelo parâmetro String , a função retornará STATUS_BUFFER_TOO_SMALL.

Comentários

O WMI exige que as cadeias de caracteres que uma função de retorno de chamada EvtWmiInstanceQueryInstance retorne sejam precedidas por uma contagem de bytes. A função WDF_WMI_BUFFER_APPEND_STRING calcula a contagem de bytes, armazena-a no buffer de destino e copia a cadeia de caracteres da estrutura UNICODE_STRING para o buffer de destino.

Quando WDF_WMI_BUFFER_APPEND_STRING retorna, o local para o qual o parâmetro RequiredSize aponta contém o número total de bytes gravados no buffer. Para localizar o primeiro endereço de buffer que segue a cadeia de caracteres, o driver pode passar o valor RequiredSize para a macro WDF_PTR_ADD_OFFSET definida em Wdfcore.h.

Exemplos

O exemplo de código a seguir é do driver de exemplo serial . Este exemplo é uma função de retorno de chamada EvtWmiInstanceQueryInstance que obtém o nome simbólico de um dispositivo e copia o nome para o buffer de saída da função de retorno de chamada.

NTSTATUS
EvtWmiQueryPortName(
    IN  WDFWMIINSTANCE WmiInstance,
    IN  ULONG OutBufferSize,
    IN  PVOID OutBuffer,
    OUT PULONG BufferUsed
    )
{
    WDFDEVICE device;
    PSERIAL_DEVICE_EXTENSION pDevExt;
    WCHAR pRegName[SYMBOLIC_NAME_LENGTH];
    UNICODE_STRING string;
    USHORT nameSize = sizeof(pRegName);
    NTSTATUS status;

    PAGED_CODE();

    device = WdfWmiInstanceGetDevice(WmiInstance);
    pDevExt = SerialGetDeviceExtension(device);

    status = SerialReadSymName(
                               device,
                               pRegName,
                               &nameSize
                               );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    RtlInitUnicodeString(
                         &string,
                         pRegName
                         );
    return WDF_WMI_BUFFER_APPEND_STRING(
                                        OutBuffer,
                                        OutBufferSize,
                                        &string,
                                        BufferUsed
                                        );
}

Requisitos

Requisito Valor
Plataforma de Destino Universal
Versão mínima do KMDF 1.0
Cabeçalho wdfwmi.h (inclua Wdf.h)
Biblioteca Nenhum

Confira também

EvtWmiInstanceQueryInstance

UNICODE_STRING