Fungsi OpenMutexW (synchapi.h)

Artikel
03/08/2023

Membuka objek mutex bernama yang sudah ada.

Sintaks

HANDLE OpenMutexW(
  [in] DWORD   dwDesiredAccess,
  [in] BOOL    bInheritHandle,
  [in] LPCWSTR lpName
);

Parameter

[in] dwDesiredAccess

Akses ke objek mutex. Hanya hak akses SYNCHRONIZE yang diperlukan untuk menggunakan mutex; untuk mengubah keamanan mutex, tentukan MUTEX_ALL_ACCESS. Fungsi gagal jika pendeskripsi keamanan objek yang ditentukan tidak mengizinkan akses yang diminta untuk proses panggilan. Untuk daftar hak akses, lihat Keamanan Objek Sinkronisasi dan Hak Akses.

[in] bInheritHandle

Jika nilai ini TRUE, proses yang dibuat oleh proses ini akan mewarisi handel. Jika tidak, proses tidak mewarisi handel ini.

[in] lpName

Nama mutex yang akan dibuka. Perbandingan nama peka huruf besar/kecil.

Fungsi ini dapat membuka objek di namespace layanan privat. Untuk informasi selengkapnya, lihat Namespace Objek.

Layanan Terminal: Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuka objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Untuk informasi selengkapnya, lihat Namespace Objek Kernel.

Catatan Peralihan pengguna cepat diimplementasikan menggunakan sesi Layanan Terminal. Pengguna pertama yang masuk menggunakan sesi 0, pengguna berikutnya untuk masuk menggunakan sesi 1, dan sebagainya. Nama objek kernel harus mengikuti panduan yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek mutex.

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

Jika mutex bernama tidak ada, fungsi gagal dan GetLastError mengembalikan ERROR_FILE_NOT_FOUND.

Keterangan

Fungsi OpenMutex memungkinkan beberapa proses untuk membuka handel objek mutex yang sama. Fungsi ini hanya berhasil jika beberapa proses telah membuat mutex dengan menggunakan fungsi CreateMutex . Proses panggilan dapat menggunakan handel yang dikembalikan dalam fungsi apa pun yang memerlukan handel ke objek mutex, seperti fungsi tunggu, tunduk pada batasan akses yang ditentukan dalam parameter dwDesiredAccess .

Handel dapat diduplikasi dengan menggunakan fungsi DuplicateHandle . Gunakan fungsi CloseHandle untuk menutup handel. Sistem menutup handel secara otomatis ketika proses berakhir. Objek mutex dihancurkan ketika handel terakhirnya telah ditutup.

Jika aplikasi multithreadEd Anda harus berulang kali membuat, membuka, dan menutup objek mutex bernama, kondisi balapan dapat terjadi. Dalam situasi ini, lebih baik menggunakan CreateMutex alih-alih OpenMutex, karena CreateMutex membuka mutex jika ada dan membuatnya jika tidak.

Contoh

Untuk contoh yang menggunakan OpenMutex, lihat Menggunakan Objek Bernama.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	synchapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll