CreateSemaphoreExW-Funktion (synchapi.h)

  • Artikel

Erstellt oder öffnet ein benanntes oder unbenannte Semaphorobjekt und gibt ein Handle an das Objekt zurück.

Syntax

HANDLE CreateSemaphoreExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCWSTR               lpName,
                 DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Parameter

[in, optional] lpSemaphoreAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur . Wenn dieser Parameter NULL ist, kann das Semaphorhandle nicht von untergeordneten Prozessen geerbt werden.

Der lpSecurityDescriptor-Member der -Struktur gibt einen Sicherheitsdeskriptor für das neue Semaphor an. Wenn dieser Parameter NULL ist, erhält der Semaphor einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für ein Semaphor stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers.

[in] lInitialCount

Die anfängliche Anzahl für das Semaphorobjekt. Dieser Wert muss größer oder gleich Null und kleiner oder gleich lMaximumCount sein. Der Zustand eines Semaphors wird signalisiert, wenn seine Anzahl größer als 0 ist, und nicht signalisiert, wenn er null ist. Die Anzahl wird um eins verringert, wenn eine Wartefunktion einen Thread freigibt, der auf den Semaphor wartete. Die Anzahl wird durch Aufrufen der ReleaseSemaphore-Funktion um einen angegebenen Betrag erhöht.

[in] lMaximumCount

Die maximale Anzahl für das Semaphorobjekt. Dieser Wert muss größer als 0 sein.

[in, optional] lpName

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des Semaphorobjekts angibt. Der Name ist auf MAX_PATH Zeichen beschränkt. Beim Namenvergleich wird die Groß-/Kleinschreibung beachtet.

Wenn lpName mit dem Namen eines vorhandenen benannten Semaphorobjekts übereinstimmt, werden die Parameter lInitialCount und lMaximumCount ignoriert, da sie bereits vom Erstellungsprozess festgelegt wurden. Wenn der lpSemaphoreAttributes-Parameter nicht NULL ist, bestimmt er, ob das Handle vererbt werden kann.

Wenn lpNameNULL ist, wird das Semaphorobjekt ohne Namen erstellt.

Wenn lpName mit dem Namen eines vorhandenen Ereignis-, Mutex-, Wartezeitgeber-, Auftrags- oder Dateizuordnungsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies liegt daran, dass diese Objekte denselben Namespace verwenden.

Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen Oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Weitere Informationen finden Sie unter Kernelobjektnamespaces. Der schnelle Benutzerwechsel wird mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den Richtlinien für Terminaldienste entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

Das Objekt kann in einem privaten Namespace erstellt werden. Weitere Informationen finden Sie unter Objektnamespaces.

dwFlags

Dieser Parameter ist reserviert und muss 0 sein.

[in] dwDesiredAccess

Die Zugriffsmaske für das Semaphorobjekt. Eine Liste der Zugriffsrechte finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Semaphorobjekt. Wenn das benannte Semaphorobjekt vor dem Funktionsaufruf vorhanden war, gibt die Funktion ein Handle an das vorhandene Objekt zurück, und GetLastError gibt ERROR_ALREADY_EXISTS zurück.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Der Zustand eines Semaphorobjekts wird signalisiert, wenn seine Anzahl größer als 0 ist, und nicht signalisiert, wenn seine Anzahl gleich 0 ist. Der lInitialCount-Parameter gibt die anfängliche Anzahl an. Die Anzahl darf nie kleiner als 0 (null) oder größer als der im lMaximumCount-Parameter angegebene Wert sein.

Jeder Thread des aufrufenden Prozesses kann das Handle semaphor-object in einem Aufruf einer der Wartefunktionen angeben. Die Wartefunktionen für einzelne Objekte geben zurück, wenn der Zustand des angegebenen Objekts signalisiert wird. Die Wartefunktionen für mehrere Objekte können angewiesen werden, entweder zurückzugeben, wenn eine oder alle angegebenen Objekte signalisiert werden. Wenn eine Wartefunktion zurückgegeben wird, wird der wartende Thread freigegeben, um seine Ausführung fortzusetzen. Jedes Mal, wenn ein Thread eine Wartezeit auf ein Semaphorobjekt abschließt, wird die Anzahl des Semaphorobjekts um eins verringert. Wenn der Thread fertig ist, ruft er die ReleaseSemaphore-Funktion auf, die die Anzahl des Semaphorobjekts erhöht.

Mehrere Prozesse können über Handles desselben Semaphorobjekts verfügen, wodurch die Verwendung des -Objekts für die Prozessübergreifende Synchronisierung ermöglicht wird. Die folgenden Mechanismen für die Objektfreigabe sind verfügbar:

  • Ein untergeordneter Prozess, der von der CreateProcess-Funktion erstellt wurde, kann ein Handle an ein Semaphorobjekt erben, wenn der lpSemaphoreAttributes-Parameter von CreateSemaphoreEx eine Vererbung aktiviert hat.
  • Ein Prozess kann das Handle semaphor-object in einem Aufruf der DuplicateHandle-Funktion angeben, um ein doppeltes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann.
  • Ein Prozess kann den Namen eines Semaphorobjekts in einem Aufruf der OpenSemaphore - oder CreateSemaphoreEx-Funktion angeben.
Verwenden Sie die CloseHandle-Funktion , um das Handle zu schließen. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Semaphorobjekt wird zerstört, wenn sein letztes Handle geschlossen wurde.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile synchapi.h (windows.h einschließen)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

CloseHandle

Semaphorobjekte

Synchronisierungsfunktionen