Função CreateJobObjectA (winbase.h)

Artigo
08/27/2023

Cria ou abre um objeto de trabalho.

Sintaxe

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

Parâmetros

[in, optional] lpJobAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica o descritor de segurança para o objeto de trabalho e determina se os processos filho podem herdar o identificador retornado. Se lpJobAttributes for NULL, o objeto de trabalho obterá um descritor de segurança padrão e o identificador não poderá ser herdado. As ACLs no descritor de segurança padrão para um objeto de trabalho vêm do token primário ou de representação do criador.

[in, optional] lpName

O nome do trabalho. O nome é limitado a MAX_PATH caracteres. A comparação de nomes diferencia maiúsculas de minúsculas.

Se lpName for NULL, o trabalho será criado sem um nome.

Se lpName corresponder ao nome de um evento existente, semáforo, mutex, temporizador de espera ou objeto de mapeamento de arquivo, a função falhará e a função GetLastError retornará ERROR_INVALID_HANDLE. Isso ocorre porque esses objetos compartilham o mesmo namespace.

O objeto pode ser criado em um namespace privado. Para obter mais informações, consulte Namespaces de objeto.

Serviços de Terminal: O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). Para obter mais informações, consulte Namespaces de objeto kernel.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de trabalho. O identificador tem o acesso de JOB_OBJECT_ALL_ACCESS correto. Se o objeto existir antes da chamada de função, a função retornará um identificador para o objeto de trabalho existente e GetLastError retornará ERROR_ALREADY_EXISTS.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Quando um trabalho é criado, suas informações contábeis são inicializadas como zero, todos os limites são inativos e não há processos associados. Para atribuir um processo a um objeto de trabalho, use a função AssignProcessToJobObject . Para definir limites para um trabalho, use a função SetInformationJobObject . Para consultar informações contábeis, use a função QueryInformationJobObject .

Todos os processos associados a um trabalho devem ser executados na mesma sessão. Um trabalho é associado à sessão do primeiro processo a ser atribuído ao trabalho.

Windows Server 2003 e Windows XP: Um trabalho é associado à sessão do processo que o criou.

Para fechar um identificador de objeto de trabalho, use a função CloseHandle . O trabalho é destruído quando seu último identificador foi fechado e todos os processos associados foram encerrados. No entanto, se o trabalho tiver o sinalizador JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE especificado, fechar o último identificador de objeto de trabalho encerrará todos os processos associados e destruirá o próprio objeto de trabalho.

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h, Jobapi2.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll