Função QueueUserAPC (processthreadsapi.h)

  • Artigo

Adiciona um objeto APC ( chamada de procedimento assíncrono ) no modo de usuário à fila APC do thread especificado.

Sintaxe

DWORD QueueUserAPC(
  [in] PAPCFUNC  pfnAPC,
  [in] HANDLE    hThread,
  [in] ULONG_PTR dwData
);

Parâmetros

[in] pfnAPC

Um ponteiro para a função APC fornecida pelo aplicativo a ser chamada quando o thread especificado executar uma operação de espera alertável. Para obter mais informações, consulte Função de retorno de chamada PAPCFUNC.

[in] hThread

Um identificador para o thread. O identificador deve ter o direito de acesso THREAD_SET_CONTEXT . Para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso.

[in] dwData

Um único valor que é passado para a função APC apontada pelo parâmetro pfnAPC .

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. Windows Server 2003 e Windows XP: Não há valores de erro definidos para essa função que possam ser recuperados chamando GetLastError.

Comentários

Consulte Função QueueUserAPC2 para obter informações sobre APCs especiais no modo de usuário.

O suporte a APC fornecido no sistema operacional permite que um aplicativo enfileirar um objeto APC em um thread. Para garantir a execução bem-sucedida de funções usadas pelo APC, as APCs devem ser enfileiradas apenas para threads no processo do chamador.

Observação

O enfileiramento de APCs para threads fora do processo do chamador não é recomendado por vários motivos. A rebasagem de DLL pode fazer com que os endereços das funções usadas pelo APC fiquem incorretos quando as funções são executadas fora do processo do chamador. Da mesma forma, se um processo de 64 bits colocar um APC em um processo de 32 bits ou vice-versa, os endereços estarão incorretos e o aplicativo falhará. Outros fatores podem impedir a execução bem-sucedida da função, mesmo que o endereço seja conhecido.

Cada thread tem sua própria fila de APC. O enfileiramento de um APC é uma solicitação para o thread chamar a função APC. O sistema operacional emite uma interrupção de software para direcionar o thread para chamar a função APC.

Quando um APC no modo de usuário é enfileirado, o thread não é direcionado para chamar a função APC, a menos que esteja em um estado alertável. Depois que o thread estiver em um estado alertável, o thread manipulará todas as APCs pendentes na ordem FIFO (primeiro a entrar, primeiro a sair) e a operação de espera retornará WAIT_IO_COMPLETION. Um thread entra em um estado alertável usando a função SleepEx, a função SignalObjectAndWait, a função WaitForSingleObjectEx, a função WaitForMultipleObjectsEx ou a função MsgWaitForMultipleObjectsEx.

Se um aplicativo enfileirar um APC antes que o thread comece a ser executado, o thread começará chamando a função APC. Depois que o thread chama uma função APC, ele chama as funções APC para todas as APCs em sua fila de APC.

É possível suspender ou aguardar um objeto dentro do APC. Se você executar uma espera alertável dentro de um APC, ela enviará recursivamente as APCs. Isso pode causar um estouro de pilha.

Quando o thread é encerrado usando a função ExitThread ou a função TerminateThread , as APCs em sua fila APC são perdidas. As funções APC não são chamadas.

Quando o thread estiver em processo de encerramento, chamar QueueUserAPC para adicionar à fila de APC do thread falhará com (31) ERROR_GEN_FAILURE.

Observe que as funções ReadFileEx, SetWaitableTimer e WriteFileEx são implementadas usando um APC como o mecanismo de retorno de chamada de notificação de conclusão.

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

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho processthreadsapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também