Função ScsiPortWmiSetInstanceName (scsiwmi.h)
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.
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 :
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) |