IOCTL_ATA_PASS_THROUGH IOCTL (ntddscsi.h)
Permite que um aplicativo envie quase qualquer comando do ATA para um dispositivo de destino, com as seguintes restrições:
- Se houver um driver de classe para o tipo de destino do dispositivo, o aplicativo deverá enviar a solicitação para o driver de classe. Assim, um aplicativo pode enviar essa solicitação diretamente ao driver de porta do sistema para uma LU (unidade lógica de destino) somente se não houver nenhum driver de classe para o tipo de dispositivo conectado a esse LU. O driver de porta do sistema não verifica se um dispositivo foi reivindicado por um driver de classe antes de processar uma solicitação de passagem. Portanto, se um aplicativo ignorar um driver de classe que reivindicou um dispositivo e enviar uma solicitação de passagem para esse dispositivo diretamente para o driver de porta, um conflito de controle do dispositivo pode ocorrer entre o driver de classe e o aplicativo.
- Essa solicitação não poderá ser usada se o comando exigir que o driver subjacente acesse a memória diretamente. Se o comando do chamador puder exigir acesso direto à memória, use IOCTL_ATA_PASS_THROUGH_DIRECT em vez disso.
- Os aplicativos não devem tentar enviar uma solicitação de passagem de forma assíncrona. Todas as solicitações de passagem devem ser síncronas.
- Os aplicativos não exigem privilégios administrativos para enviar uma solicitação de passagem para um dispositivo, mas devem ter acesso de leitura/gravação ao dispositivo.
Código principal
Buffer de entrada
O buffer em >AssociatedIrp.SystemBuffer deve conter uma estrutura ATA_PASS_THROUGH_EX, que inclui um conjunto de registros de entrada de arquivo de tarefa que indicam o tipo de comando a ser executado e seus parâmetros. O chamador deve inicializar todos os membros dessa estrutura, exceto PathId, TargetId e Lun, que o driver de porta preenche. Para um comando de saída de dados, o DataBufferOffset membro da estrutura deve apontar para um buffer alinhado a cache que contém os dados a serem gravados.
Comprimento do buffer de entrada
Parameters.DeviceIoControl.InputBufferLength indica o tamanho em bytes do buffer em AssociatedIrp.SystemBuffer>. Se o comando ATA inserido for uma operação de gravação, o tamanho do buffer de entrada deverá ser a soma de tamanhos de(ATA_PASS_THROUGH_EX) e o valor no membro datatransferLength de ATA_PASS_THROUGH_EX. O exemplo de pseudocódigo a seguir mostra como calcular o tamanho do buffer:ULONG buffsize; // size of the buffer
ATA_PASS_THROUGH_EX hdr;
hdr.DataTransferLength = size in bytes of the data transfer
buffsize = sizeof (ATA_PASS_THROUGH_EX) + hdr.DataTransferLength
Se o comando ATA inserido for uma operação de leitura ou uma operação de controle de dispositivo que não envolva transferência de dados, InputBufferLength deverá ser igual a tamanhos de (ATA_PASS_THROUGH_EX).
Em ambos os casos, se InputBufferLength for menor que tamanho de (ATA_PASS_THROUGH_EX), o driver de porta falhará na solicitação de E/S e retornará um erro.
Buffer de saída
O driver de porta formata os dados de retorno usando uma estrutura de ATA_PASS_THROUGH_EX e armazena os dados no buffer em >AssociatedIrp.SystemBuffer.
O driver de porta preenche o currentTaskFile membro com os valores presentes nos registros de saída do dispositivo na conclusão do comando do ATA inserido. Se o comando for uma transferência de dados, o driver de porta armazenará os dados transferidos em um buffer alinhado a cache localizado em um deslocamento de DataBufferOffset bytes desde o início da estrutura. O aplicativo é responsável por interpretar o conteúdo dos registros de saída para determinar quais erros, se houver, foram retornados pelo dispositivo.
Comprimento do buffer de saída
O driver de porta atualiza o DataTransferLength membro do ATA_PASS_THROUGH_EX para indicar a quantidade de dados realmente transferidos do dispositivo. Se o comando ATA inserido for uma operação de gravação ou uma operação de controle de dispositivo que não transfere dados, OutputBufferLength será igual a tamanhos de(ATA_PASS_THROUGH_EX). Se o comando ATA inserido for uma operação de leitura, OutputBufferLength será igual a sizeof(ATA_PASS_THROUGH_EX) + DataTransferLength.
Bloco de status
O membro de Informações é definido como o número de bytes retornados no buffer de saída em >AssociatedIrp.SystemBuffer. O membro status de está definido como STATUS_SUCCESS ou possivelmente STATUS_BUFFER_TOO_SMALL ou STATUS_INVALID_PARAMETER se o valor de status de de entrada no ATA_PASS_THROUGH_EX for definido incorretamente.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows Server 2003. |
| cabeçalho | ntddscsi.h (include Ntddscsi.h) |