CreateJobObjectA, fonction (winbase.h)

Article
08/27/2023

Crée ou ouvre un objet de travail.

Syntaxe

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

Paramètres

[in, optional] lpJobAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES qui spécifie le descripteur de sécurité pour l’objet de travail et détermine si les processus enfants peuvent hériter du handle retourné. Si lpJobAttributes a la valeur NULL, l’objet de travail obtient un descripteur de sécurité par défaut et le handle ne peut pas être hérité. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut pour un objet de travail proviennent du jeton principal ou d’emprunt d’identité du créateur.

[in, optional] lpName

Nom du travail. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.

Si lpName a la valeur NULL, le travail est créé sans nom.

Si lpName correspond au nom d’un événement, d’un sémaphore, d’un mutex, d’un minuteur d’attente ou d’un objet de mappage de fichiers existant, la fonction échoue et la fonction GetLastError retourne ERROR_INVALID_HANDLE. Cela se produit parce que ces objets partagent le même espace de noms.

L’objet peut être créé dans un espace de noms privé. Pour plus d’informations, consultez Espaces de noms d’objets.

Terminal Services : Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception de la barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets du noyau.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour l’objet de travail. Le handle a le droit d’accès JOB_OBJECT_ALL_ACCESS . Si l’objet existait avant l’appel de la fonction, la fonction retourne un handle à l’objet de travail existant et GetLastError retourne ERROR_ALREADY_EXISTS.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Lorsqu’un travail est créé, ses informations comptables sont initialisées à zéro, toutes les limites sont inactives et aucun processus n’est associé. Pour affecter un processus à un objet de travail, utilisez la fonction AssignProcessToJobObject . Pour définir des limites pour un travail, utilisez la fonction SetInformationJobObject . Pour interroger les informations de comptabilité, utilisez la fonction QueryInformationJobObject .

Tous les processus associés à un travail doivent s’exécuter dans la même session. Un travail est associé à la session du premier processus à affecter au travail.

Windows Server 2003 et Windows XP : Un travail est associé à la session du processus qui l’a créé.

Pour fermer un handle d’objet de travail, utilisez la fonction CloseHandle . Le travail est détruit lorsque son dernier handle a été fermé et que tous les processus associés ont été arrêtés. Toutefois, si l’indicateur JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE est spécifié pour le travail, la fermeture du dernier handle d’objet de travail met fin à tous les processus associés, puis détruit l’objet de travail lui-même.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0500 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h, Jobapi2.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll