CreateSemaphoreExA-Funktion (winbase.h)
Erstellt oder öffnet ein benanntes oder unbenannte Semaphorobjekt und gibt ein Handle an das Objekt zurück.
Syntax
HANDLE CreateSemaphoreExA(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCSTR lpName,
DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parameter
[in, optional] lpSemaphoreAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur. Wenn dieser Parameter NULL-ist, kann der Semaphorhandle 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
Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Namen des Semaphorobjekts angibt. 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, werden die parameter lInitialCount und lMaximumCount parameter ignoriert, da sie bereits durch den Erstellungsprozess festgelegt wurden. Wenn der lpSemaphoreAttributes Parameter nicht NULL-ist, bestimmt er, ob das Handle geerbt werden kann.
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.
dwFlags
Dieser Parameter ist reserviert und muss 0 sein.
[in] dwDesiredAccess
Die Zugriffsmaske für das Semaphorobjekt. Eine Liste der Zugriffsrechte finden Sie unter Sync Object Security and Access Rights.
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 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 CreateSemaphoreEx 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 von [OpenSemaphor](.) angeben. /synchapi/nf-synchapi-signalobjectandwait.md) oder CreateSemaphoreEx-Funktion.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows Vista [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | winbase.h (enthalten Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |