Função DeviceIoControl (ioapiset.h)

Envia um código de controle diretamente para um driver de dispositivo especificado, fazendo com que o dispositivo correspondente execute a operação correspondente.

Consulte o exemplo de letra atribuir unidade.

Sintaxe

BOOL DeviceIoControl(
  [in]                HANDLE       hDevice,
  [in]                DWORD        dwIoControlCode,
  [in, optional]      LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out, optional]     LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out, optional]     LPDWORD      lpBytesReturned,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parâmetros

[in] hDevice

Um identificador para o dispositivo no qual a operação deve ser executada. O dispositivo normalmente é um volume, diretório, arquivo ou fluxo. Para recuperar um identificador de dispositivo, use a função CreateFile . Para obter mais informações, consulte Comentários.

[in] dwIoControlCode

O código de controle da operação. Esse valor identifica a operação específica a ser executada e o tipo de dispositivo no qual executá-la.

Para obter uma lista dos códigos de controle, consulte Comentários. A documentação de cada código de controle fornece detalhes de uso para os parâmetros lpInBuffer, nInBufferSize, lpOutBuffer e nOutBufferSize .

[in, optional] lpInBuffer

Um ponteiro para o buffer de entrada que contém os dados necessários para executar a operação. O formato desses dados depende do valor do parâmetro dwIoControlCode .

Esse parâmetro poderá ser NULL se dwIoControlCode especificar uma operação que não exija dados de entrada.

[in] nInBufferSize

O tamanho do buffer de entrada, em bytes.

[out, optional] lpOutBuffer

Um ponteiro para o buffer de saída que deve receber os dados retornados pela operação. O formato desses dados depende do valor do parâmetro dwIoControlCode .

Esse parâmetro poderá ser NULL se dwIoControlCode especificar uma operação que não retorna dados.

[in] nOutBufferSize

O tamanho do buffer de saída em bytes.

[out, optional] lpBytesReturned

Um ponteiro para uma variável que recebe o tamanho dos dados armazenados no buffer de saída, em bytes.

Se o buffer de saída for muito pequeno para receber dados, a chamada falhará, GetLastErrorretornará ERROR_INSUFFICIENT_BUFFER e lpBytesReturned será zero.

Se o buffer de saída for muito pequeno para armazenar todos os dados, mas puder conter algumas entradas, alguns drivers retornarão o máximo de dados que se ajustar. Nesse caso, a chamada falha, GetLastError retorna ERROR_MORE_DATA e lpBytesReturned indica a quantidade de dados recebidos. Seu aplicativo deve chamar DeviceIoControl novamente com a mesma operação, especificando um novo ponto de partida.

Se lpOverlapped for NULL, lpBytesReturned não poderá ser NULL. Mesmo quando uma operação não retorna dados de saída e lpOutBuffer é NULL, DeviceIoControl usa lpBytesReturned. Após essa operação, o valor de lpBytesReturned não tem sentido.

Se lpOverlapped não for NULL, lpBytesReturned poderá ser NULL. Se esse parâmetro não for NULL e a operação retornar dados, lpBytesReturned não terá sentido até que a operação sobreposta seja concluída. Para recuperar o número de bytes retornados, chame GetOverlappedResult. Se hDevice estiver associado a uma porta de conclusão de E/S, você poderá recuperar o número de bytes retornados chamando GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Um ponteiro para uma estrutura OVERLAPPED .

Se hDevice foi aberto sem especificar FILE_FLAG_OVERLAPPED, lpOverlapped será ignorado.

Se hDevice foi aberto com o sinalizador FILE_FLAG_OVERLAPPED , a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, lpOverlapped deve apontar para uma estrutura OVERLAPPED válida que contém um identificador para um objeto de evento. Caso contrário, a função falhará de maneiras imprevisíveis.

Para operações sobrepostas, DeviceIoControl retorna imediatamente e o objeto de evento é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.

Retornar valor

Se a operação for concluída com êxito, o valor retornado será não zero (TRUE).

Se a operação falhar ou estiver pendente, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Para recuperar um identificador para o dispositivo, você deve chamar a função CreateFile com o nome de um dispositivo ou o nome do driver associado a um dispositivo. Para especificar um nome de dispositivo, use o seguinte formato:

\\.\DeviceName

DeviceIoControl pode aceitar um identificador para um dispositivo específico. Por exemplo, para abrir um identificador para a unidade lógica A: com CreateFile, especifique \\.\a:. Como alternativa, você pode usar os nomes \\.\PhysicalDrive0, \\.\PhysicalDrive1 e assim por diante, para abrir identificadores para as unidades físicas em um sistema.

Você deve especificar os sinalizadores de acesso FILE_SHARE_READ e FILE_SHARE_WRITE ao chamar CreateFile para abrir um identificador para um driver de dispositivo. No entanto, quando você abre um recurso de comunicação, como uma porta serial, deve especificar o acesso exclusivo. Use os outros parâmetros CreateFile da seguinte maneira ao abrir um identificador de dispositivo:

  • O parâmetro fdwCreate deve especificar OPEN_EXISTING.
  • O parâmetro hTemplateFile deve ser NULL.
  • O parâmetro fdwAttrsAndFlags pode especificar FILE_FLAG_OVERLAPPED para indicar que o identificador retornado pode ser usado em operações de E/S sobrepostas (assíncronas).
Para obter listas de códigos de controle com suporte, consulte os seguintes tópicos:

Exemplos

Para obter um exemplo que usa DeviceIoControl, consulte Chamando DeviceIoControl.

Requisitos

   
Cliente mínimo com suporte Windows XP
Servidor mínimo com suporte Windows Server 2003
Plataforma de Destino Windows
Cabeçalho ioapiset.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

CreateEvent

CreateFile

Controle de entrada e saída do dispositivo (IOCTL)

GetOverlappedResult

GetQueuedCompletionStatus

SOBREPOSTA

Atribuir exemplo de letra da unidade