CreateJobObjectA-Funktion (winbase.h)

Artikel
08/27/2023

Erstellt oder öffnet ein Auftragsobjekt.

Syntax

HANDLE CreateJobObjectA(
  [in, optional] LPSECURITY_ATTRIBUTES lpJobAttributes,
  [in, optional] LPCSTR                lpName
);

Parameter

[in, optional] lpJobAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die den Sicherheitsdeskriptor für das Auftragsobjekt angibt und bestimmt, ob untergeordnete Prozesse das zurückgegebene Handle erben können. Wenn lpJobAttributesNULL ist, ruft das Auftragsobjekt einen Standardsicherheitsdeskriptor ab, und das Handle kann nicht geerbt werden. Die ACLs im Standardsicherheitsdeskriptor für ein Auftragsobjekt stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers.

[in, optional] lpName

Der Name des Auftrags. Der Name ist auf MAX_PATH Zeichen beschränkt. Beim Namenvergleich wird die Groß-/Kleinschreibung beachtet.

Wenn lpNameNULL ist, wird der Auftrag ohne Namen erstellt.

Wenn lpName mit dem Namen eines vorhandenen Ereignisses, Semaphors, Mutex, wartebaren Timers 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.

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

Terminaldienste: 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.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Auftragsobjekt. Das Handle verfügt über das Zugriffsrecht JOB_OBJECT_ALL_ACCESS . Wenn das Objekt vor dem Funktionsaufruf vorhanden war, gibt die Funktion ein Handle an das vorhandene Auftragsobjekt 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

Wenn ein Auftrag erstellt wird, werden seine Buchhaltungsinformationen auf Null initialisiert, alle Grenzwerte sind inaktiv, und es gibt keine zugeordneten Prozesse. Um einem Auftragsobjekt einen Prozess zuzuweisen, verwenden Sie die AssignProcessToJobObject-Funktion . Verwenden Sie die SetInformationJobObject-Funktion , um Grenzwerte für einen Auftrag festzulegen. Verwenden Sie zum Abfragen von Buchhaltungsinformationen die QueryInformationJobObject-Funktion .

Alle Einem Auftrag zugeordneten Prozesse müssen in derselben Sitzung ausgeführt werden. Ein Auftrag ist der Sitzung des ersten Prozesses zugeordnet, der dem Auftrag zugewiesen werden soll.

Windows Server 2003 und Windows XP: Ein Auftrag ist der Sitzung des Prozesses zugeordnet, der ihn erstellt hat.

Verwenden Sie zum Schließen eines Auftragsobjekthandles die CloseHandle-Funktion . Der Auftrag wird zerstört, wenn sein letztes Handle geschlossen wurde und alle zugehörigen Prozesse beendet wurden. Wenn für den Auftrag jedoch das flag JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE angegeben ist, beendet das Schließen des letzten Auftragsobjekthandles alle zugeordneten Prozesse und zerstört dann das Auftragsobjekt selbst.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0500 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h, Jobapi2.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll