Función CreateJobObjectA (winbase.h)

Artículo
11/20/2024

Crea o abre un objeto de trabajo.

Sintaxis

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

Parámetros

[in, optional] lpJobAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES que especifica el descriptor de seguridad para el objeto de trabajo y determina si los procesos secundarios pueden heredar el identificador devuelto. Si lpJobAttributes es NULL, el objeto de trabajo obtiene un descriptor de seguridad predeterminado y el identificador no se puede heredar. Las ACL del descriptor de seguridad predeterminado para un objeto de trabajo proceden del token principal o de suplantación del creador.

[in, optional] lpName

Nombre del trabajo. El nombre está limitado a MAX_PATH caracteres. La comparación de nombres distingue mayúsculas de minúsculas.

Si lpName es null, el trabajo se crea sin un nombre.

Si lpName coincide con el nombre de un evento existente, semáforo, exclusión mutua, temporizador de espera o objeto de asignación de archivos, se produce un error en la función y la función GetLastError devuelve ERROR_INVALID_HANDLE. Esto ocurre porque estos objetos comparten el mismo espacio de nombres.

El objeto se puede crear en un espacio de nombres privado. Para obtener más información, vea Espacios de nombres de objeto.

Terminal Services: El nombre puede tener un prefijo "Global" o "Local" para crear explícitamente el objeto en el espacio de nombres global o de sesión. El resto del nombre puede contener cualquier carácter excepto el carácter de barra diagonal inversa (\). Para obtener más información, vea espacios de nombres de objeto kernel.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador para el objeto de trabajo. El identificador tiene el derecho de acceso JOB_OBJECT_ALL_ACCESS. Si el objeto existía antes de la llamada de función, la función devuelve un identificador al objeto de trabajo existente y GetLastError devuelve ERROR_ALREADY_EXISTS.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Observaciones

Cuando se crea un trabajo, su información contable se inicializa en cero, todos los límites están inactivos y no hay procesos asociados. Para asignar un proceso a un objeto de trabajo, use la función AssignProcessToJobObject. Para establecer límites para un trabajo, use la función SetInformationJobObject. Para consultar información de contabilidad, use la función QueryInformationJobObject.

Todos los procesos asociados a un trabajo deben ejecutarse en la misma sesión. Un trabajo está asociado a la sesión del primer proceso que se asignará al trabajo.

Windows Server 2003 y Windows XP: Un trabajo está asociado a la sesión del proceso que lo creó.

Para cerrar un identificador de objeto de trabajo, use la función CloseHandle. El trabajo se destruye cuando se ha cerrado su último identificador y se han cerrado todos los procesos asociados. Sin embargo, si el trabajo tiene la marca JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE especificada, cerrar el último identificador de objeto de trabajo finaliza todos los procesos asociados y, a continuación, destruye el propio objeto de trabajo.

Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0500 o posterior. Para obtener más información, vea Using the Windows Headers.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winbase.h (incluya Windows.h, Jobapi2.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll