Função AssignProcessToJobObject (jobapi2.h)

Artigo
08/24/2023

Atribui um processo a um objeto de trabalho existente.

Sintaxe

BOOL AssignProcessToJobObject(
  [in] HANDLE hJob,
  [in] HANDLE hProcess
);

Parâmetros

[in] hJob

Um identificador para o objeto de trabalho ao qual o processo será associado. A função CreateJobObject ou OpenJobObject retorna esse identificador. O identificador deve ter o acesso de JOB_OBJECT_ASSIGN_PROCESS correto. Para obter mais informações, consulte Segurança do objeto de trabalho e direitos de acesso.

[in] hProcess

Um identificador para o processo a ser associado ao objeto de trabalho. O identificador deve ter os direitos de acesso PROCESS_SET_QUOTA e PROCESS_TERMINATE. Para obter mais informações, consulte Direitos de Acesso e Segurança do Processo.

Se o processo já estiver associado a um trabalho, o trabalho especificado por hJob deverá estar vazio ou deve estar na hierarquia de trabalhos aninhados aos quais o processo já pertence e não poderá ter limites de interface do usuário definidos (SetInformationJobObject com JobObjectBasicUIRestrictions). Para obter mais informações, consulte Comentários.

Windows 7, Windows Server 2008 R2, Windows XP com SP3, Windows Server 2008, Windows Vista e Windows Server 2003: O processo ainda não deve ser atribuído a um trabalho; se for, a função falhará com ERROR_ACCESS_DENIED. Esse comportamento mudou a partir do Windows 8 e do Windows Server 2012.

Serviços de Terminal: Todos os processos em um trabalho devem ser executados na mesma sessão que o trabalho.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

Depois de associar um processo a um objeto de trabalho usando AssignProcessToJobObject, o processo está sujeito aos limites definidos para o trabalho. Para definir limites para um trabalho, use a função SetInformationJobObject .

Se o trabalho tiver um limite de tempo no modo de usuário e o limite de tempo tiver sido esgotado, AssignProcessToJobObject falhará e o processo especificado será encerrado. Se o limite de tempo for excedido associando o processo, AssignProcessToJobObject ainda terá êxito. No entanto, a violação do limite de tempo será relatada. Se o trabalho tiver um limite de processo ativo e o limite for excedido associando esse processo, AssignProcessToJobObject falhará e o processo especificado será encerrado.

As operações de memória executadas por um processo associado a um trabalho que tem um limite de memória estão sujeitas ao limite de memória. As operações de memória executadas pelo processo antes de serem associadas ao trabalho não são examinadas por AssignProcessToJobObject.

Se o processo já estiver em execução e o trabalho tiver limitações de segurança, AssignProcessToJobObject poderá falhar. Por exemplo, se o token primário do processo contiver o grupo de administradores locais, mas o objeto de trabalho tiver a limitação de segurança JOB_OBJECT_SECURITY_NO_ADMIN, a função falhará. Se o trabalho tiver a limitação de segurança JOB_OBJECT_SECURITY_ONLY_TOKEN, o processo deverá ser criado suspenso. Para criar um processo suspenso, chame a função CreateProcess com o sinalizador CREATE_SUSPENDED.

Um processo pode ser associado a mais de um trabalho em uma hierarquia de trabalhos aninhados. Para classe de prioridade, afinidade, cobrança de confirmação, limite de tempo de execução por processo, limite de classe de agendamento e conjunto de trabalho mínimo e máximo, o processo herda um limite efetivo que é o limite mais restritivo de todos os trabalhos em sua cadeia de trabalho pai. Para outros limites de recursos, o processo herda limites de seu trabalho imediato na hierarquia. As informações contábeis são adicionadas ao trabalho imediato e agregadas em cada trabalho pai na cadeia de trabalho. Por padrão, todos os processos filho são associados ao trabalho imediato e a cada trabalho na cadeia de trabalho pai. Para criar um processo filho que não faça parte da mesma cadeia de trabalho, chame a função CreateProcess com o sinalizador CREATE_BREAKAWAY_FROM_JOB. O processo filho se separa de todos os trabalhos na cadeia de trabalho, a menos que um trabalho na cadeia não permita a separação. Nesse caso, o processo filho não se separa desse trabalho ou de nenhum trabalho acima dele na cadeia de trabalho. Para obter mais informações, consulte Trabalhos Aninhados.

Windows 7, Windows Server 2008 R2, Windows XP com SP3, Windows Server 2008, Windows Vista e Windows Server 2003: Um processo só pode ser associado a um único trabalho. Um processo herda limites do trabalho ao qual está associado e adiciona suas informações contábeis ao trabalho. Se um processo estiver associado a um trabalho, todos os processos filho que ele cria serão associados a esse trabalho por padrão. Para criar um processo filho que não faça parte do mesmo trabalho, chame a função CreateProcess com o sinalizador CREATE_BREAKAWAY_FROM_JOB. Um processo pode ser associado a mais de um trabalho começando no Windows 8 e no Windows Server 2012.

Windows 7, Windows Server 2008 R2, Windows Server 2008 e Windows Vista: Se o processo estiver sendo monitorado pelo PCA (Assistente de Compatibilidade de Programas), ele será colocado em um trabalho de compatibilidade. Portanto, o processo deve ser criado usando CREATE_BREAKAWAY_FROM_JOB antes que ele possa ser colocado em outro trabalho. Como alternativa, você pode inserir um manifesto do aplicativo que especifica um nível de Controle de Conta de Usuário (UAC) em seu aplicativo e o PCA não adicionará o processo ao trabalho de compatibilidade. Para obter mais informações, consulte Requisitos de desenvolvimento de aplicativos para compatibilidade de controle de conta de usuário.

Se o trabalho ou qualquer um de seus trabalhos pai na cadeia de trabalho estiver terminando quando AssignProcessToJob for chamado, a função falhará.

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	jobapi2.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll