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 das Semaphorhandle nicht von untergeordneten Prozessen geerbt werden.

Das lpSecurityDescriptor-Element der -Struktur gibt einen Sicherheitsdeskriptor für das neue Semaphor an. Wenn dieser Parameter NULL ist, erhält der Semaphor eine Standardsicherheitsbeschreibung. 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 des Semaphorobjekts. Dieser Wert muss größer oder gleich Null und kleiner als oder gleich lMaximumCount sein. Der Zustand eines Semaphors wird signalisiert, wenn seine Anzahl größer als 0 ist, und nicht signalisiert, wenn er 0 ist. Die Anzahl wird um eins verringert, wenn eine Wartefunktion einen Thread freigibt, der auf den Semaphor gewartet hat. 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-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 geerbt werden kann.

Wenn lpNameNULL ist, wird das Semaphorobjekt ohne Namen erstellt.

Wenn lpName mit dem Namen eines vorhandenen Ereignisses, Mutex, wartebaren Timers, Auftrags oder Dateizuordnungsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies tritt auf, weil 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 für Terminaldienste beschriebenen Richtlinien 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 Synchronisierungsobjektsicherheit und Zugriffsrechte.

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 Parameter lInitialCount gibt die anfängliche Anzahl an. Die Anzahl darf nie kleiner als 0 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 abgeschlossen hat, wird die Anzahl des Semaphorobjekts um eins verringert. Wenn der Thread abgeschlossen ist, wird die ReleaseSemaphore-Funktion aufgerufen, die die Anzahl des Semaphorobjekts erhöht.

Mehrere Prozesse können über Handles desselben Semaphorobjekts verfügen, sodass das Objekt für die Interprozesssynchronisierung verwendet werden kann. Die folgenden Mechanismen für die Objektfreigabe sind verfügbar:

• Ein von der CreateProcess-Funktion erstellter untergeordneter Prozess kann ein Handle an ein Semaphorobjekt erben, wenn der lpSemaphoreAttributes-Parameter der CreateSemaphoreEx-fähigen Vererbung aktiviert ist.
• Ein Prozess kann das Semaphor-Objekthandle-Handle 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 von [OpenSemaphore](.) angeben. /synchapi/nf-synchapi-signalobjectandwait.md) oder CreateSemaphoreEx-Funktion .

Verwenden Sie die CloseHandle-Funktion , um das Handle zu schließen. Das System schließt den 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	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

CloseHandle

Semaphorobjekte

Synchronisierungsfunktionen