Função DeviceIoControl (ioapiset.h)

Artigo
08/24/2023

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 Atribuir letra da 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, em bytes, do buffer de entrada.

[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á, GetLastError retornará ERROR_INSUFFICIENT_BUFFER e lpBytesReturned será zero.

Se o buffer de saída for muito pequeno para conter todos os dados, mas puder conter algumas entradas, alguns drivers retornarão o máximo de dados que se ajustarem. 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 for NULL, DeviceIoControl usará lpBytesReturned. Após essa operação, o valor de lpBytesReturned não terá 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 tiver sido aberto sem especificar FILE_FLAG_OVERLAPPED, lpOverlapped será ignorado.

Se hDevice tiver sido 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 contenha um identificador para um objeto de evento. Caso contrário, a função falhará de maneiras imprevisíveis.

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

Valor retornado

Se a operação for concluída com êxito, o valor retornado será diferente de 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 alças 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, ao abrir um recurso de comunicação, como uma porta serial, você deve especificar 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

Requisito	Valor
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