CreateSemaphoreW-Funktion (synchapi.h)
Erstellt oder öffnet ein benanntes oder unbenannte Semaphorobjekt.
Um ein Zugriffsformat für das Objekt anzugeben, verwenden Sie die CreateSemaphoreEx--Funktion.
Syntax
HANDLE CreateSemaphoreW(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCWSTR lpName
);
Parameter
[in, optional] lpSemaphoreAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur. Wenn dieser Parameter NULL-ist, kann das Handle nicht von untergeordneten Prozessen geerbt werden.
Der lpSecurityDescriptor Element 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 oder Identitätswechseltoken des Erstellers.
[in] lInitialCount
Die anfängliche Anzahl des Semaphorobjekts. Dieser Wert muss größer oder gleich Null und kleiner als oder gleich lMaximumCountsein. Der Zustand eines Semaphors wird signalisiert, wenn seine Anzahl größer als Null und nicht signalisiert ist, wenn es null ist. Die Anzahl wird um eine verringert, wenn eine Wartefunktion einen Thread freigibt, der auf das Semaphor wartete. Die Anzahl wird um einen angegebenen Betrag erhöht, indem die ReleaseSemaphore--Funktion aufgerufen wird.
[in] lMaximumCount
Die maximale Anzahl für das Semaphorobjekt. Dieser Wert muss größer als Null sein.
[in, optional] lpName
Der Name des Semaphorobjekts. Der Name ist auf MAX_PATH Zeichen beschränkt. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.
Wenn lpName mit dem Namen eines vorhandenen benannten Semaphorobjekts übereinstimmt, fordert diese Funktion das SEMAPHORE_ALL_ACCESS Zugriffsrecht an. In diesem Fall werden die parameter lInitialCount und lMaximumCount ignoriert, da sie bereits durch den Erstellungsprozess festgelegt wurden. Wenn der lpSemaphoreAttributes Parameter nicht NULL-ist, bestimmt er, ob das Handle geerbt werden kann, aber sein Sicherheitsdeskriptorelement wird ignoriert.
Wenn lpName-NULL-ist, wird das Semaphorobjekt ohne Namen erstellt.
Wenn lpName- mit dem Namen eines vorhandenen Ereignisses, mutex- oder wartezeitfähigen Timer-, Auftrags- oder Dateizuordnungsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError--Funktion gibt ERROR_INVALID_HANDLEzurück. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.
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 Kernel Object Namespaces. Schnelle Benutzerumschaltung 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 Object Namespaces.
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 ist, gibt die Funktion ein Handle an das vorhandene Objekt zurück und GetLastError gibt ERROR_ALREADY_EXISTSzurück.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Der von CreateSemaphore zurückgegebene Handle hat das SEMAPHORE_ALL_ACCESS Zugriffsrecht; es kann in jeder Funktion verwendet werden, die ein Handle für ein Semaphorobjekt erfordert, vorausgesetzt, der Aufrufer wurde Zugriff gewährt. Wenn ein Semaphor aus einem Dienst oder einem Thread erstellt wird, der die Identität eines anderen Benutzers angibt, können Sie entweder einen Sicherheitsdeskriptor auf das Semaphor anwenden, wenn Sie es erstellen, oder den Standardsicherheitsdeskriptor für den Erstellungsprozess ändern, indem Sie die standardmäßige DACL ändern. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.
Der Zustand eines Semaphorobjekts wird signalisiert, wenn seine Anzahl größer als Null ist und nicht signalisiert wird, wenn die Anzahl gleich Null ist. Der parameter lInitialCount gibt die anfangsanzahl an. Die Anzahl darf niemals kleiner als Null oder größer als der im lMaximumCount Parameter angegebene Wert sein.
Jeder Thread des aufrufenden Prozesses kann das Semaphor-Objekthandle in einem Aufruf einer der Wait-Funktionenangeben. Die Einzelobjekt-Wait-Funktionen werden zurückgegeben, wenn der Status des angegebenen Objekts signalisiert wird. Die Wait-Funktionen mit mehreren Objekten können angewiesen werden, entweder zurückzugeben, wenn eines oder alle angegebenen Objekte signalisiert werden. Wenn eine Wartefunktion zurückgegeben wird, wird der Wartethread losgelassen, um die Ausführung fortzusetzen. Jedes Mal, wenn ein Thread eine Wartezeit für ein Semaphorobjekt abschließt, wird die Anzahl des Semaphorobjekts um ein Objekt erhöht. Wenn der Thread abgeschlossen ist, ruft er die ReleaseSemaphor--Funktion auf, wodurch die Anzahl des Semaphorobjekts erhöht wird.
Mehrere Prozesse können Überhandles desselben Semaphorobjekts verfügen, wodurch die Verwendung des Objekts für die Interprocesssynchronisierung ermöglicht wird. Die folgenden Objektfreigabemechanismen sind verfügbar:
- Ein untergeordneter Prozess, der von der CreateProcess--Funktion erstellt wird, kann ein Handle an ein Semaphorobjekt erben, wenn die lpSemaphoreAttributes Parameter von CreateSemaphore aktivierte Vererbung.
- Ein Prozess kann das Semaphor-Objekthandle in einem Aufruf der DuplicateHandle--Funktion angeben, um ein dupliziertes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann.
- Ein Prozess kann den Namen eines Semaphorobjekts in einem Aufruf des OpenSemaphors oder CreateSemaphore--Funktion angeben.
Beispiele
Ein Beispiel, das CreateSemaphoreverwendet, finden Sie unter Verwenden von Semaphor-Objekten.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | synchapi.h (enthalten Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |