função de retorno de chamada TAPE_PROCESS_COMMAND_ROUTINE (minitape.h)

  • Artigo

TAPE_PROCESS_COMMAND_ROUTINE lida com os aspectos específicos do dispositivo de uma solicitação IOCTL.

Sintaxe

TAPE_PROCESS_COMMAND_ROUTINE TapeProcessCommandRoutine;

TAPE_STATUS TapeProcessCommandRoutine(
  [in, out]      PVOID MinitapeExtension,
  [in, out]      PVOID CommandExtension,
  [in, out]      PVOID CommandParameters,
  [in, out]      PSCSI_REQUEST_BLOCK Srb,
  [in]           ULONG CallNumber,
  [in, optional] TAPE_STATUS StatusOfLastCommand,
  [in, out]      PULONG RetryFlags
)
{...}

Parâmetros

[in, out] MinitapeExtension

Ponteiro para a extensão de minitape específica do driver. Isso será NULL se o driver de miniclasse não solicitar uma extensão de minitape quando ele for inicializado.

[in, out] CommandExtension

Ponteiro para a extensão de comando. Isso será NULL se o driver de miniclasse não solicitar uma extensão de comando quando ele for inicializado.

[in, out] CommandParameters

Ponteiro para um buffer alocado pelo chamador que contém uma estrutura TAPE_CREATE_PARTITION .

[in, out] Srb

Ponteiro para um SRB alocado e parcialmente preenchido pelo driver de classe de fita. TAPE_PROCESS_COMMAND_ROUTINE deve preencher o CDB no SRB.

  • Cdb – ponteiro para a CDB SCSI para o comando . Limpe o CDB com TapeClassZeroMemory antes de preenchê-lo.
  • CdbLength – especifica o número de bytes no CDB.
TAPE_PROCESS_COMMAND_ROUTINE também pode preencher os seguintes membros no SRB:
  • DataBuffer – ponteiro para o buffer de dados a ser transferido. Use TapeClassAllocateSrbBuffer para alocar um DataBuffer de comprimento maior ou igual a DataTransferLength.
  • DataTransferLength – especifica o número de bytes a serem transferidos no SRB. Esse membro é definido por TapeClassAllocateSrbBuffer.
  • TimeOutValue – especifica um valor de tempo limite para esse comando, substituindo o valor de tempo limite padrão da extensão de dispositivo do driver de classe de fita.
  • SrbFlags – especifica um sinalizador para este comando. O driver de miniclasse de fita deve definir SRB_FLAGS_DATA_OUT se o SRB estiver enviando dados para a unidade de fita. Esse membro poderá ser zero se o SRB estiver solicitando dados da unidade de fita ou se nenhum dado estiver sendo transferido pelo comando.

[in] CallNumber

Especifica o número de vezes que TAPE_PROCESS_COMMAND_ROUTINE foi chamado para processar um determinado comando de fita. CallNumber é zero na primeira vez que essa rotina é chamada e é incrementada para cada chamada subsequente até que o driver de miniclasse retorne um valor TAPE_STATUS que indica que o comando está concluído.

[in, optional] StatusOfLastCommand

Especifica o status do último comando. Na primeira chamada para TAPE_PROCESS_COMMAND_ROUTINE para processar uma determinada solicitação, StatusOfLastCommand é TAPE_STATUS_SUCCESS. Nas chamadas subsequentes, StatusOfLastCommand será TAPE_STATUS_SUCCESS ou um erro status se ocorreu um erro e o driver de miniclasse de fita RETURN_ERRORS em RetryFlags na chamada anterior.

[in, out] RetryFlags

Ponteiro para uma variável que especifica qual ação o driver de classe de fita deve tomar quando um dispositivo de fita relata um erro.

A palavra de baixa ordem especifica o número de tentativas a serem executadas no caso de uma falha de comando SCSI. O padrão é zero (sem repetições).

A palavra de alta ordem contém sinalizadores que especificam como o driver de classe de fita deve retornar o controle se ocorrer um erro:

  • Se RETURN_ERRORS e IGNORE_ERRORS estiverem claros (o padrão), o driver de classe de fita retornará uma falha status ao solicitante original.
  • Se o driver de miniclasse definir RETURN_ERRORS, o driver de classe de fita chamará TAPE_PROCESS_COMMAND_ROUTINE com StatusOfLastCommand definido como um status de falha.
  • Se o driver de miniclasse definir IGNORE_ERRORS, o driver de classe de fita converterá uma falha status em êxito e chamará TAPE_PROCESS_COMMAND_ROUTINE com StatusOfLastCommand definido como êxito.

Retornar valor

Código de retorno Descrição
TAPE_STATUS_SEND_SRB_AND_CALLBACK
 Indica ao driver de classe de fita que o SRB foi preenchido e está pronto para ser enviado para o dispositivo de destino. Por padrão, as chamadas do driver de classe de fita TAPE_PROCESS_COMMAND_ROUTINE novamente somente se o SRB for bem-sucedido. Um driver de miniclasse pode modificar o comportamento padrão definindo RetryFlags antes de retornar de TAPE_PROCESS_COMMAND_ROUTINE.
TAPE_STATUS_CALLBACK
 Direciona o driver de classe de fita para incrementar CallNumber e chamar TAPE_PROCESS_COMMAND_ROUTINE novamente sem enviar um SRB para o dispositivo de fita.
TAPE_STATUS_CHECK_TEST_UNIT_READY
 Direciona o driver de classe de fita para preencher um SRB para o comando TEST UNIT READY e enviar o SRB para o dispositivo.
TAPE_STATUS_XXX
 Qualquer outro código de retorno indica ao driver de classe de fita que o comando foi concluído e indica êxito, falha ou aviso. Os possíveis valores de retorno de conclusão para essa rotina incluem, mas não se limitam a:
TAPE_STATUS_SUCCESS
TAPE_STATUS_INSUFFICIENT_RESOURCES
TAPE_STATUS_INVALID_DEVICE_REQUEST
TAPE_STATUS_INVALID_PARAMETER
TAPE_STATUS_IO_DEVICE_ERROR
TAPE_STATUS_MEDIA_WRITE_PROTECTED
TAPE_STATUS_NOT_IMPLEMENTED

Comentários

As seguintes funções podem ser atribuídas a esse espaço reservado de retorno de chamada:

Createpartition

CreatePartition manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_CREATE_PARTITION . Essa rotina é necessária. CreatePartition cria uma partição em uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. A criação de uma partição normalmente requer uma série de SRBs para concluir a operação. Depois que CreatePartition preenche um determinado SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo de destino e, dependendo do resultado do SRB e do valor de RetryFlags, chama TapeMiniCreatePartition novamente.

CreatePartition deve preencher os seguintes membros no SRB antes de retornar ao driver de classe de fita:

Se o driver de miniclasse de fita armazenar informações de partição na extensão de minitape, CreatePartition atualizará a extensão antes de retornar ao driver de classe de fita com TAPE_STATUS_SUCCESS.

Apagar

Apagar manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_ERASE . Essa rotina é necessária. Apagar apaga uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. Apagar uma fita normalmente requer um SRB para concluir a operação. Depois que Erase preenche o SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chama Erase novamente. Em seguida, apagar retorna TAPE_STATUS_SUCCESS.

GetDriveParameters

GetDriveParameters manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_GET_DRIVE_PARAMS . Essa rotina é necessária. GetDriveParameters obtém parâmetros de unidade de fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. Obter parâmetros de unidade normalmente requer uma série de SRBs para concluir a operação. Depois que GetDriveParameters preenche um determinado SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo de destino e, dependendo do resultado do SRB e do valor de RetryFlags, chama GetDriveParameters novamente.

GetMediaParameters

GetMediaParameters manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_GET_MEDIA_PARAMS . Essa rotina é necessária. GetMediaParameters obtém parâmetros de mídia de fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. Obter parâmetros de mídia normalmente requer mais de um SRB para concluir a operação, começando com uma unidade de teste pronta para a qual o driver de miniclasse solicita retornando TAPE_STATUS_CHECK_TEST_UNIT_READY a primeira vez que o driver de classe de fita chama a rotina.

Depois que GetMediaParameters preenche um determinado SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chama GetMediaParameters novamente.

GetMediaTypes

GetMediaTypes manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_STORAGE_GET_MEDIA_TYPES_EX . Essa rotina é necessária. GetMediaTypes obtém informações sobre os tipos de mídia compatíveis com um dispositivo de fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. Obter tipos de mídia normalmente requer mais de um SRB para concluir a operação, começando com uma unidade de teste pronta para a qual o driver de miniclasse solicita retornando TAPE_STATUS_CHECK_TEST_UNIT_READY a primeira vez que o driver de classe de fita chama a rotina.

Getposition

GetPosition manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_GET_POSITION . Essa rotina é necessária. GetPosition lê a posição de uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. A leitura da posição da fita normalmente requer mais de um SRB para concluir a operação, geralmente começando com uma unidade de teste pronta para a qual o driver de miniclasse solicita retornando TAPE_STATUS_CHECK_TEST_UNIT_READY a primeira vez que o driver de classe de fita chama a rotina.

Getstatus

GetStatus manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_GET_STATUS . Essa rotina é necessária. GetStatus lê o status de um dispositivo de fita, normalmente direcionando o driver de classe de fita para emitir um comando pronto para a unidade de teste.

Se um dispositivo indicar se uma unidade precisa de limpeza de dados no sentido (em vez de relatar a necessidade de limpeza como um erro, que um driver de miniclasse manipularia em sua rotina TapeMiniTapeError ), GetStatus preencherá o CDB no SRB passado pelo driver de classe de fita para obter os dados de sentido e, se necessário, retornará TAPE_STATUS_REQUIRES_CLEANING.

Preparar

Prepare manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_PREPARE . Essa rotina é necessária. Preparar prepara uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. Se o dispositivo der suporte à operação solicitada, preparar uma fita normalmente exigirá um SRB. Depois que Prepare preencher o SRB e retornar, o driver de classe de fita enviará o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chamará Preparar novamente.

SetDriveParameters

SetDriveParameters manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_SET_DRIVE_PARAMS . Essa rotina é necessária. SetDriveParameters define parâmetros para um dispositivo de fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. A configuração de parâmetros normalmente envolve uma série de SRBs para concluir a operação. Depois que SetDriveParameters preenche um determinado SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chama SetDriveParameters novamente.

SetMediaParameters

SetMediaParameters manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_SET_MEDIA_PARAMS . Essa rotina é necessária. SetMediaParameters define o tamanho do bloco de uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. Definir o tamanho do bloco normalmente requer mais de um SRB para concluir a operação, começando com uma unidade de teste pronta para a qual o driver de miniclasse solicita retornando TAPE_STATUS_CHECK_TEST_UNIT_READY a primeira vez que o driver de classe de fita chama a rotina.

Depois que SetMediaParameters preenche um determinado SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chama SetMediaParameters novamente.

Setposition

SetPosition manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_SET_POSITION . Essa rotina é necessária. SetPosition define a posição de uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. A configuração da posição normalmente requer um SRB. Depois que SetPosition preencher o SRB e retornar, o driver de classe de fita enviará o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chamará SetPosition novamente. SetPosition retorna TAPE_STATUS_SUCCESS.

WriteMarks

WriteMarks manipula os aspectos específicos do dispositivo de uma solicitação de IOCTL_TAPE_WRITE_MARKS . Essa rotina é necessária. WriteMarks grava marcas em uma fita preenchendo o CDB em um SRB passado pelo driver de classe de fita. As marcas de gravação normalmente exigem um SRB para concluir a operação. Depois que WriteMarks preenche o SRB e retorna, o driver de classe de fita envia o SRB para o dispositivo e, dependendo do resultado do SRB e do valor de RetryFlags, chama WriteMarks novamente. WriteMarks retorna TAPE_STATUS_SUCCESS.

PreProcessReadWrite

PreProcessReadWrite é uma rotina opcional de uso especial que executa todas as operações específicas do dispositivo necessárias antes das operações de leitura e gravação. A maioria dos drivers de miniclasse de fita não precisa dessa rotina. As atividades da rotina PreProcessReadWrite são específicas do dispositivo. A rotina pode usar as informações passadas a ela pelo driver de classe para implementar o pré-processamento especial para leituras e gravações. Se uma unidade tiver recursos limitados, o driver poderá precisar dessa rotina para manter o estado coerente, por exemplo.

Se um driver de miniclasse de fita definir um ponto de entrada não NULL para essa rotina no TAPE_INIT_DATA_EX estrutura que ele passa para TapeClassInitialize de sua rotina DriverEntry , o driver de classe de fita o chamará antes de cada operação de leitura e gravação no dispositivo de fita. O driver de classe não espera nenhuma informação dessa rotina.

WMIOperations

WMIOperations é o ponto de entrada comum para todas as chamadas WMI do driver de classe de fita. Um minidriver que dá suporte ao WMI deve definir o membro do ponteiro de função, WMIOperations, na estrutura TAPE_INIT_DATA_EX para apontar para a rotina de TAPE_PROCESS_COMMAND_ROUTINE do minidriver. O minidriver deve fazer isso em sua rotina DriverEntry antes de chamar TapeClassInitialize. Se um minidriver não der suporte a operações WMI, ele deverá definir o campo TapeWMIOperations como NULL.

O driver de classe de fita atribui valores aos membros da estrutura TAPE_WMI_OPERATIONS e passa essa estrutura para a rotina WMIOperations do minidriver no parâmetro CommandParameters . Assim como acontece com outras rotinas de minidriver, o WMIOperations preenche, cria e inicializa os blocos de solicitação SCSI (SRB) e os blocos de descritor de comando (CDB) necessários para implementar o método WMI indicado e retorna o controle para o driver de classe de fita. Em seguida, o driver de classe de fita chama o driver de porta para executar a solicitação.

O minidriver retorna os dados WMI no buffer apontado pelo membro DataBuffer da estrutura TAPE_WMI_OPERATIONS.

Requisitos

Requisito Valor
Plataforma de Destino Área de Trabalho
Cabeçalho minitape.h (inclua Minitape.h)

Confira também

SCSI_REQUEST_BLOCK

TAPE_STATUS

TapeClassAllocateSrbBuffer

TapeClassZeroMemory