Estrutura OVERLAPPED (minwinbase.h)

Contém informações usadas em E/S (entrada e saída) assíncronas (ou sobrepostas).

Sintaxe

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYSTRUCTNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;

Membros

Internal

O código status para a solicitação de E/S. Quando a solicitação é emitida, o sistema define esse membro como STATUS_PENDING para indicar que a operação ainda não foi iniciada. Quando a solicitação é concluída, o sistema define esse membro como o código status para a solicitação concluída.

O membro Interno foi originalmente reservado para uso do sistema e seu comportamento pode mudar.

InternalHigh

O número de bytes transferidos para a solicitação de E/S. O sistema define esse membro se a solicitação for concluída sem erros.

O membro InternalHigh foi originalmente reservado para uso do sistema e seu comportamento pode mudar.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

A parte de baixa ordem da posição do arquivo na qual iniciar a solicitação de E/S, conforme especificado pelo usuário.

Esse membro é diferente de zero somente ao executar solicitações de E/S em um dispositivo em busca que dá suporte ao conceito de um deslocamento (também conhecido como um mecanismo de ponteiro de arquivo), como um arquivo. Caso contrário, esse membro deve ser zero.

Para obter informações adicionais, consulte Comentários.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

A parte de alta ordem da posição do arquivo na qual iniciar a solicitação de E/S, conforme especificado pelo usuário.

Esse membro é diferente de zero somente ao executar solicitações de E/S em um dispositivo em busca que dá suporte ao conceito de um deslocamento (também conhecido como um mecanismo de ponteiro de arquivo), como um arquivo. Caso contrário, esse membro deve ser zero.

Para obter informações adicionais, consulte Comentários.

DUMMYUNIONNAME.Pointer

Reservado para uso do sistema; não use após a inicialização como zero.

hEvent

Um identificador para o evento que será definido como um estado sinalizado pelo sistema quando a operação for concluída. O usuário deve inicializar esse membro como zero ou um identificador de evento válido usando a função CreateEvent antes de passar essa estrutura para quaisquer funções sobrepostas. Esse evento pode ser usado para sincronizar solicitações simultâneas de E/S para um dispositivo. Para obter informações adicionais, consulte Comentários.

Funções como ReadFile e WriteFile definem esse identificador como o estado não atribuído antes de iniciar uma operação de E/S. Quando a operação for concluída, o identificador será definido como o estado sinalizado.

Funções como GetOverlappedResult e as funções de espera de sincronização redefinem eventos de redefinição automática para o estado não atribuído. Portanto, você deve usar um evento de redefinição manual; se você usar um evento de redefinição automática, seu aplicativo poderá parar de responder se você aguardar a conclusão da operação e, em seguida, chamar GetOverlappedResult com o parâmetro bWait definido como TRUE.

Comentários

Todos os membros não utilizados dessa estrutura sempre devem ser inicializados como zero antes que a estrutura seja usada em uma chamada de função. Caso contrário, a função poderá falhar e retornar ERROR_INVALID_PARAMETER.

Os membros Offset e OffsetHigh juntos representam uma posição de arquivo de 64 bits. É um deslocamento de bytes do início do arquivo ou dispositivo semelhante ao arquivo e é especificado pelo usuário; o sistema não modificará esses valores. O processo de chamada deve definir esse membro antes de passar a estrutura OVERLAPPED para funções que usam um deslocamento, como as funções ReadFile ou WriteFile (e relacionadas).

Você pode usar a macro HasOverlappedIoCompleted para marcar se uma operação de E/S assíncrona foi concluída se GetOverlappedResult for muito complicado para seu aplicativo.

Você pode usar a função CancelIo para cancelar uma operação de E/S assíncrona.

Um erro comum é reutilizar uma estrutura OVERLAPPED antes que a operação assíncrona anterior tenha sido concluída. Você deve usar uma estrutura separada para cada solicitação. Você também deve criar um objeto de evento para cada thread que processa dados. Se você armazenar os identificadores de evento em uma matriz, poderá esperar facilmente que todos os eventos sejam sinalizados usando a função WaitForMultipleObjects .

Para obter informações adicionais e possíveis armadilhas de uso assíncrono de E/S, consulte CreateFile, ReadFile, WriteFile e funções relacionadas.

Para obter uma visão geral de sincronização geral e informações conceituais de uso de OVERLAPPED , consulte Sincronização e entrada e saída sobrepostas e tópicos relacionados.

Para obter uma visão geral orientada a E/S de arquivo de E/S síncrona e assíncrona, consulte E/S síncrona e assíncrona.

Exemplos

Para obter um exemplo, consulte Servidor de pipe nomeado usando E/S sobreposta.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Cabeçalho minwinbase.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)

Confira também

CancelIo

CreateFile

GetOverlappedResult

HasOverlappedIoCompleted

ReadFile

Sincronização e entrada e saída sobrepostas

E/S síncrona e assíncrona

WriteFile