Struktur TUMPANG TINDIH (minwinbase.h)

Artikel
03/05/2024

Berisi informasi yang digunakan dalam input dan output (I/O) asinkron (atau tumpang tindih).

Sintaks

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

Anggota

Internal

Kode status untuk permintaan I/O. Ketika permintaan dikeluarkan, sistem mengatur anggota ini ke STATUS_PENDING untuk menunjukkan bahwa operasi belum dimulai. Ketika permintaan selesai, sistem mengatur anggota ini ke kode status untuk permintaan yang telah selesai.

Anggota Internal awalnya dicadangkan untuk penggunaan sistem dan perilakunya dapat berubah.

InternalHigh

Jumlah byte yang ditransfer untuk permintaan I/O. Sistem menetapkan anggota ini jika permintaan selesai tanpa kesalahan.

Anggota InternalHigh awalnya dicadangkan untuk penggunaan sistem dan perilakunya dapat berubah.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

Bagian urutan rendah dari posisi file untuk memulai permintaan I/O, seperti yang ditentukan oleh pengguna.

Anggota ini bukan nol hanya ketika melakukan permintaan I/O pada perangkat pencarian yang mendukung konsep offset (juga disebut sebagai mekanisme penunjuk file), seperti file. Jika tidak, anggota ini harus nol.

Untuk informasi tambahan, lihat Keterangan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

Bagian urutan tinggi dari posisi file untuk memulai permintaan I/O, seperti yang ditentukan oleh pengguna.

Untuk informasi tambahan, lihat Keterangan.

DUMMYUNIONNAME.Pointer

Dicadangkan untuk penggunaan sistem; jangan gunakan setelah inisialisasi ke nol.

hEvent

Handel ke peristiwa yang akan diatur ke status sinyal oleh sistem ketika operasi telah selesai. Pengguna harus menginisialisasi anggota ini baik ke nol atau penanganan aktivitas yang valid menggunakan fungsi CreateEvent sebelum meneruskan struktur ini ke fungsi yang tumpang tindih. Kejadian ini kemudian dapat digunakan untuk menyinkronkan permintaan I/O simultan untuk perangkat. Untuk informasi tambahan, lihat Keterangan.

Fungsi seperti ReadFile dan WriteFile mengatur handel ini ke status tidak ditandatangani sebelum memulai operasi I/O. Ketika operasi telah selesai, handel diatur ke status sinyal.

Fungsi seperti GetOverlappedResult dan fungsi tunggu sinkronisasi mengatur ulang peristiwa reset otomatis ke status tidak ditandatangani. Oleh karena itu, Anda harus menggunakan peristiwa reset manual; jika Anda menggunakan peristiwa reset otomatis, aplikasi Anda dapat berhenti merespons jika Anda menunggu operasi selesai lalu memanggil GetOverlappedResult dengan parameter bWait diatur ke TRUE.

Keterangan

Setiap anggota struktur ini yang tidak digunakan harus selalu diinisialisasi ke nol sebelum struktur digunakan dalam panggilan fungsi. Jika tidak, fungsi mungkin gagal dan mengembalikan ERROR_INVALID_PARAMETER.

Anggota Offset dan OffsetHigh bersama-sama mewakili posisi file 64-bit. Ini adalah offset byte dari awal file atau perangkat seperti file, dan ditentukan oleh pengguna; sistem tidak akan mengubah nilai-nilai ini. Proses panggilan harus mengatur anggota ini sebelum meneruskan struktur TUMPANG TINDIH ke fungsi yang menggunakan offset, seperti fungsi ReadFile atau WriteFile (dan terkait).

Anda dapat menggunakan makro HasOverlappedIoCompleted untuk memeriksa apakah operasi I/O asinkron telah selesai jika GetOverlappedResult terlalu rumit untuk aplikasi Anda.

Anda dapat menggunakan fungsi CancelIo untuk membatalkan operasi I/O asinkron.

Kesalahan umum adalah menggunakan kembali struktur yang TUMPANG TINDIH sebelum operasi asinkron sebelumnya selesai. Anda harus menggunakan struktur terpisah untuk setiap permintaan. Anda juga harus membuat objek peristiwa untuk setiap utas yang memproses data. Jika Anda menyimpan handel peristiwa dalam array, Anda dapat dengan mudah menunggu semua peristiwa diberi sinyal menggunakan fungsi WaitForMultipleObjects .

Untuk informasi tambahan dan potensi jebakan penggunaan I/O asinkron, lihat CreateFile, ReadFile, WriteFile, dan fungsi terkait.

Untuk gambaran umum sinkronisasi umum dan informasi penggunaan TUMPANG TINDIH konseptual, lihat Sinkronisasi dan Input dan Output yang Tumpang Tindih dan topik terkait.

Untuk gambaran umum berorientasi I/O file dari I/O sinkron dan asinkron, lihat I/O Sinkron dan Asinkron.

Contoh

Misalnya, lihat Server Pipa Bernama Menggunakan I/O yang Tumpang Tindih.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Header	minwinbase.h (termasuk Windows.h pada Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)