Função ScsiPortWmiSetInstanceName (scsiwmi.h)

  • Artigo

A rotina ScsiPortWmiSetInstanceName atualiza a estrutura WNODE_ALL_DATA dentro do contexto de solicitação para especificar a posição e o comprimento de um nome de instância.

Nota O driver de porta SCSI e os modelos de driver de miniporta SCSI podem ser alterados ou indisponíveis no futuro. Em vez disso, recomendamos usar os modelos de driver storport e driver de miniporto Storport .
 

Sintaxe

PWCHAR ScsiPortWmiSetInstanceName(
  [in]      PSCSIWMI_REQUEST_CONTEXT RequestContext,
  [in]      ULONG                    InstanceIndex,
  [in]      ULONG                    InstanceNameLength,
  [out]     PULONG                   BufferAvail,
  [in, out] PULONG                   SizeNeeded
);

Parâmetros

[in] RequestContext

Ponteiro para uma estrutura do tipo SCSIWMI_REQUEST_CONTEXT que contém o contexto de solicitação para um SRB WMI.

[in] InstanceIndex

Contém um índice que indica a instância para a qual a posição e o comprimento do nome da instância devem ser especificados.

[in] InstanceNameLength

Especifica o tamanho em bytes do nome da instância.

[out] BufferAvail

Deve conter, na entrada, o número de bytes de espaço em buffer na estrutura WNODE_ALL_DATA que pode ser usada para descrever nomes e dados de instância. No retorno, esse membro contém o número de bytes de espaço em buffer que permanecem.

Há três rotinas WMI de Porta SCSI que retornam um valor para o tamanho do buffer disponível em seu parâmetro BufferAvail :

ScsiPortWmiSetInstanceCount

ScsiPortWmiSetData

ScsiPortWmiSetInstanceName

O driver de miniporto deve chamar ScsiPortWmiSetInstanceCount primeiro, mas depois que ScsiPortWmiSetInstanceCount tiver sido chamado, não importa em que ordem o minidriver chama ScsiPortWmiSetData e ScsiPortWmiSetInstanceName. Ao chamar ScsiPortWmiSetData ou ScsiPortWmiSetInstanceName, o valor passado para a rotina em seu parâmetro BufferAvail deve ser o mesmo que o valor retornado no parâmetro BufferAvail pela rotina WMI de porta SCSI mais recentemente chamada. Por exemplo, suponha que o minidriver chame ScsiPortWmiSetInstanceCount primeiro e essa rotina retorne um valor de 1.000 em seu parâmetro BufferAvail . Em seguida, o minidriver chama ScsiPortWmiSetData , que retorna um valor de 500 em seu parâmetro BufferAvail . Por fim, o minidriver chama ScsiPortWmiSetInstanceName , que retorna um valor de 200 em seu parâmetro BufferAvail . O valor inicial de 1.000 deve ser passado para ScsiPortWmiSetData em BufferAvail e o valor de 500 deve ser passado para ScsiPortWmiSetInstanceName.

Se não houver memória suficiente disponível para adicionar um nome de instância de comprimento InstanceNameLength, um zero será retornado no membro BufferAvail .

[in, out] SizeNeeded

Indica, na entrada, o número de bytes necessários para descrever o WNODE antes de adicionar os dados descritivos para a instância especificada por InstanceIndex. No retorno, esse membro conterá o tamanho de todo o WNODE, incluindo os dados da nova instância.

Retornar valor

A rotina ScsiPortWmiSetInstanceCount retorna um ponteiro para o buffer em que o chamador pode armazenar o nome da instância especificada em InstanceIndex. Se ScsiPortWmiSetInstanceCount não puder alocar memória suficiente para o nome da instância ou se o WNODE contido no contexto de solicitação não for do tipo WNODE_ALL_DATA, ScsiPortWmiSetData retornará NULL.

Comentários

O minidriver deve chamar ScsiPortWmiSetInstanceCount antes de chamar ScsiPortWmiSetInstanceName.

O parâmetro RequestContext aponta para uma estrutura de contexto de solicitação, SCSIWMI_REQUEST_CONTEXT, que contém informações associadas a um bloco de solicitação SCSI ( Instrumentação de Gerenciamento do Windows ) (SRB). A estrutura de contexto de solicitação, por sua vez, contém uma das Estruturas de WNODE_XXX WMI usadas pelo sistema WMI para passar dados entre consumidores de dados no modo usuário e provedores de dados no modo kernel, como drivers.

A rotina ScsiPortWmiSetInstanceName requer que a estrutura WNODE definida no contexto de solicitação seja do tipo WNODE_ALL_DATA. Isso ocorre porque ScsiPortWmiSetInstanceName pode reservar uma área de nome de instância para qualquer uma das instâncias associadas a um bloco de dados WMI. Ao contrário da estrutura WNODE_SINGLE_INSTANCE que contém informações sobre uma única instância, a estrutura WNODE_ALL_DATA contém uma matriz de ponteiros para áreas de buffer para instâncias diferentes e ScsiPortWmiSetInstanceCount inicializa essa matriz, para que cada buffer de dados de instância possa ser acessado individualmente.

A memória alocada para o contexto de solicitação deve permanecer válida até que o driver de miniporto chame ScsiPortWmiPostProcess e ScsiPortWmiPostProcess retorne o status SRB final e o tamanho do buffer. Se o SRB puder ser pendente, a memória do contexto de solicitação deverá ser alocada da extensão SRB. Se o SRB não puder ser pendente, a memória poderá ser alocada de um quadro de pilha que não sai do escopo.

Requisitos

Requisito Valor
Plataforma de Destino Área de Trabalho
Cabeçalho scsiwmi.h (inclua Miniport.h, Scsi.h)

Confira também

SCSIWMI_REQUEST_CONTEXT

WNODE_ALL_DATA

WNODE_SINGLE_INSTANCE