Fungsi DuplicateHandle (handleapi.h)

Menduplikasi handel objek.

Sintaks

BOOL DuplicateHandle(
  [in]  HANDLE   hSourceProcessHandle,
  [in]  HANDLE   hSourceHandle,
  [in]  HANDLE   hTargetProcessHandle,
  [out] LPHANDLE lpTargetHandle,
  [in]  DWORD    dwDesiredAccess,
  [in]  BOOL     bInheritHandle,
  [in]  DWORD    dwOptions
);

Parameter

[in] hSourceProcessHandle

Handel ke proses dengan handel yang akan diduplikasi.

Handel harus memiliki hak akses PROCESS_DUP_HANDLE. Untuk informasi selengkapnya, lihat Keamanan Proses dan Hak Akses.

[in] hSourceHandle

Handel yang akan diduplikasi. Ini adalah handel objek terbuka yang valid dalam konteks proses sumber. Untuk daftar objek yang handelnya dapat diduplikasi, lihat bagian Keterangan berikut.

[in] hTargetProcessHandle

Handel untuk proses yang menerima handel duplikat. Handel harus memiliki hak akses PROCESS_DUP_HANDLE.

Parameter ini bersifat opsional dan dapat ditentukan sebagai NULL jika bendera DUPLICATE_CLOSE_SOURCE diatur dalam Opsi.

[out] lpTargetHandle

Penunjuk ke variabel yang menerima handel duplikat. Nilai handel ini valid dalam konteks proses target.

Jika hSourceHandle adalah handel pseudo yang dikembalikan oleh GetCurrentProcess atau GetCurrentThread, DuplicateHandle masing-masing mengonversinya menjadi handel nyata ke proses atau utas.

Jika lpTargetHandleADALAH NULL, fungsi akan menduplikasi handel, tetapi tidak mengembalikan nilai handel duplikat ke pemanggil. Perilaku ini hanya ada untuk kompatibilitas mundur dengan versi sebelumnya dari fungsi ini. Anda tidak boleh menggunakan fitur ini, karena Anda akan kehilangan sumber daya sistem sampai proses target berakhir.

Parameter ini diabaikan jika hTargetProcessHandle adalah NULL.

[in] dwDesiredAccess

Akses yang diminta untuk handel baru. Untuk bendera yang dapat ditentukan untuk setiap jenis objek, lihat bagian Keterangan berikut.

Parameter ini diabaikan jika parameter dwOptions menentukan bendera DUPLICATE_SAME_ACCESS. Jika tidak, bendera yang dapat ditentukan bergantung pada jenis objek yang handelnya akan diduplikasi.

Parameter ini diabaikan jika hTargetProcessHandle adalah NULL.

[in] bInheritHandle

Variabel yang menunjukkan apakah handel dapat diwariskan. Jika TRUE, handel duplikat dapat diwarisi oleh proses baru yang dibuat oleh proses target. Jika FALSE, handel baru tidak dapat diwariskan.

Parameter ini diabaikan jika hTargetProcessHandle adalah NULL.

[in] dwOptions

Tindakan opsional. Parameter ini bisa nol, atau kombinasi apa pun dari nilai berikut.

Nilai	Makna
DUPLICATE_CLOSE_SOURCE 0x00000001	Menutup handel sumber. Ini terjadi terlepas dari status kesalahan yang dikembalikan.
DUPLICATE_SAME_ACCESS 0x00000002	Mengabaikan parameter dwDesiredAccess . Handel duplikat memiliki akses yang sama dengan handel sumber.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Handel duplikat mengacu pada objek yang sama dengan handel asli. Oleh karena itu, setiap perubahan pada objek tercermin melalui kedua handel. Misalnya, jika Anda menduplikasi handel file, posisi file saat ini selalu sama untuk kedua handel. Agar handel file memiliki posisi file yang berbeda, gunakan fungsi CreateFile untuk membuat handel file yang berbagi akses ke file yang sama.

DuplicateHandle dapat dipanggil oleh proses sumber atau proses target (atau proses yang merupakan proses sumber dan target). Misalnya, proses dapat menggunakan DuplicateHandle untuk membuat duplikat yang tidak dapat diwariskan dari handel yang dapat diwariskan, atau handel dengan akses yang berbeda dari handel asli.

Proses sumber menggunakan fungsi GetCurrentProcess untuk mendapatkan handel dengan sendirinya. Handel ini adalah handel pseudo, tetapi DuplicateHandle mengonversinya menjadi handel proses nyata. Untuk mendapatkan handel proses target, mungkin perlu menggunakan beberapa bentuk komunikasi antarproses (misalnya, pipa bernama atau memori bersama) untuk mengomunikasikan pengidentifikasi proses ke proses sumber. Proses sumber dapat menggunakan pengidentifikasi ini dalam fungsi OpenProcess untuk mendapatkan handel ke proses target.

Jika proses yang memanggil DuplicateHandle bukan juga proses target, proses sumber harus menggunakan komunikasi antarproses untuk meneruskan nilai handel duplikat ke proses target.

DuplicateHandle dapat digunakan untuk menduplikasi handel antara proses 32-bit dan proses 64-bit. Handel yang dihasilkan berukuran tepat untuk bekerja dalam proses target. Untuk informasi selengkapnya, lihat Interoperabilitas Proses.

DuplicateHandle dapat menduplikasi handel ke jenis objek berikut.

Objek	Deskripsi
Token akses	Handel dikembalikan oleh fungsi CreateRestrictedToken, DuplicateToken, DuplicateTokenEx, OpenProcessToken, atau OpenThreadToken .
Mengubah pemberitahuan	Handel dikembalikan oleh fungsi FindFirstChangeNotification .
Perangkat komunikasi	Handel dikembalikan oleh fungsi CreateFile .
Input konsol	Handel dikembalikan oleh fungsi CreateFile ketika CONIN$ ditentukan, atau oleh fungsi GetStdHandle saat STD_INPUT_HANDLE ditentukan. Handel konsol dapat diduplikasi untuk digunakan hanya dalam proses yang sama.
Buffer layar konsol	Handel dikembalikan oleh fungsi CreateFile ketika CONOUT$ ditentukan, atau oleh fungsi GetStdHandle saat STD_OUTPUT_HANDLE ditentukan. Handel konsol dapat diduplikasi untuk digunakan hanya dalam proses yang sama.
Desktop	Handel dikembalikan oleh fungsi GetThreadDesktop .
Kejadian	Handel dikembalikan oleh fungsi CreateEvent atau OpenEvent .
File	Handel dikembalikan oleh fungsi CreateFile .
Pemetaan file	Handel dikembalikan oleh fungsi CreateFileMapping .
Tugas	Handel dikembalikan oleh fungsi CreateJobObject .
Mailslot	Handel dikembalikan oleh fungsi CreateMailslot .
Mutex	Handel dikembalikan oleh CreateMutex atau [OpenMutex](.. Fungsi /synchapi/nf-synchapi-openmutexw.md).
Pipa	Handel pipa bernama dikembalikan oleh fungsi CreateNamedPipe atau CreateFile . Handel pipa anonim dikembalikan oleh fungsi CreatePipe .
Proses	Handel dikembalikan oleh fungsi CreateProcess, GetCurrentProcess, atau OpenProcess .
Kunci Registri	Handel dikembalikan oleh fungsi RegCreateKey, RegCreateKeyEx, RegOpenKey, atau RegOpenKeyEx . Perhatikan bahwa handel kunci registri yang dikembalikan oleh fungsi RegConnectRegistry tidak dapat digunakan dalam panggilan ke DuplicateHandle.
Semaphore	Handel dikembalikan oleh fungsi CreateSemaphore atau OpenSemaphore .
Rangkaian	Handel dikembalikan oleh fungsi CreateProcess, CreateThread, CreateRemoteThread, atau GetCurrentThread
Pengatur Waktu	Handel dikembalikan oleh fungsi CreateWaitableTimerW atau OpenWaitableTimerW .
Transaksi	Handel dikembalikan oleh fungsi CreateTransaction .
Stasiun jendela	Handel dikembalikan oleh fungsi GetProcessWindowStation .

 

Anda tidak boleh menggunakan DuplicateHandle untuk menduplikasi handel ke objek berikut:

• Port penyelesaian I/O. Tidak ada kesalahan yang dikembalikan, tetapi handel duplikat tidak dapat digunakan.
• Soket. Tidak ada kesalahan yang dikembalikan, tetapi handel duplikat mungkin tidak dikenali oleh Winsock pada proses target. Selain itu, menggunakan DuplicateHandle mengganggu referensi internal yang dihitung pada objek yang mendasar. Untuk menduplikasi handel soket, gunakan fungsi WSADuplicateSocket .
• Pseudo-handles selain yang dikembalikan oleh fungsi GetCurrentProcess atau GetCurrentThread .

Parameter dwDesiredAccess menentukan hak akses handel baru. Semua objek mendukung hak akses standar. Objek juga dapat mendukung hak akses tambahan tergantung pada jenis objek. Untuk informasi selengkapnya, lihat topik berikut:

• Keamanan Desktop dan Hak Akses
• Keamanan File dan Hak Akses
• Keamanan Pemetaan File dan Hak Akses
• Keamanan Objek Pekerjaan dan Hak Akses
• Keamanan Proses dan Hak Akses
• Keamanan Kunci Registri dan Hak Akses
• Keamanan Objek Sinkronisasi dan Hak Akses
• Keamanan Utas dan Hak Akses
• Keamanan dan Hak Akses Window-Station

Dalam beberapa kasus, handel baru dapat memiliki lebih banyak hak akses daripada handel asli. Namun, dalam kasus lain, DuplicateHandle tidak dapat membuat handel dengan lebih banyak hak akses daripada aslinya. Misalnya, handel file yang dibuat dengan hak akses GENERIC_READ tidak dapat diduplikasi sehingga memiliki hak akses GENERIC_READ dan GENERIC_WRITE.

Biasanya proses target menutup handel duplikat ketika proses tersebut selesai menggunakan handel. Untuk menutup handel duplikat dari proses sumber, panggil DuplicateHandle dengan parameter berikut:

• Atur hSourceProcessHandle ke proses target dari panggilan DuplicateHandle yang membuat handel.
• Atur hSourceHandle ke handel duplikat untuk menutup.
• Atur hTargetProcessHandle ke NULL.
• Atur dwOptions ke DUPLICATE_CLOSE_SOURCE.

Contoh

Contoh berikut membuat mutex, menduplikasi handel ke mutex, dan meneruskannya ke utas lain. Menduplikasi handel memastikan bahwa jumlah referensi ditingkatkan sehingga objek mutex tidak akan dihancurkan sampai kedua utas menutup handel.

#include <windows.h>

DWORD CALLBACK ThreadProc(PVOID pvParam);

int main()
{
    HANDLE hMutex = CreateMutex(NULL, FALSE, NULL);
    HANDLE hMutexDup, hThread;
    DWORD dwThreadId;

    DuplicateHandle(GetCurrentProcess(), 
                    hMutex, 
                    GetCurrentProcess(),
                    &hMutexDup, 
                    0,
                    FALSE,
                    DUPLICATE_SAME_ACCESS);

    hThread = CreateThread(NULL, 0, ThreadProc, 
        (LPVOID) hMutexDup, 0, &dwThreadId);

    // Perform work here, closing the handle when finished with the
    // mutex. If the reference count is zero, the object is destroyed.
    CloseHandle(hMutex);

    // Wait for the worker thread to terminate and clean up.
    WaitForSingleObject(hThread, INFINITE);
    CloseHandle(hThread);
    return 0;
}

DWORD CALLBACK ThreadProc(PVOID pvParam)
{
    HANDLE hMutex = (HANDLE)pvParam;

    // Perform work here, closing the handle when finished with the
    // mutex. If the reference count is zero, the object is destroyed.
    CloseHandle(hMutex);
    return 0;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop | Aplikasi UWP]
Target Platform	Windows
Header	handleapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

CloseHandle

Menangani Pewarisan

Menangani dan Fungsi Objek