Función QueueUserAPC (processthreadsapi.h)

  • Artículo

Agrega un objeto de llamada de procedimiento asincrónico en modo de usuario (APC) a la cola de APC del subproceso especificado.

Sintaxis

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

Parámetros

[in] pfnAPC

Puntero a la función de APC proporcionada por la aplicación que se llamará cuando el subproceso especificado realiza una operación de espera que se pueda alertar. Para obtener más información, consulte función de devolución de llamada PAPCFUNC.

[in] hThread

Identificador del subproceso. El identificador debe tener el derecho de acceso THREAD_SET_CONTEXT . Para obtener más información, vea Synchronization Object Security and Access Rights.

[in] dwData

Valor único que se pasa a la función de APC a la que apunta el parámetro pfnAPC .

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError. Windows Server 2003 y Windows XP: No hay valores de error definidos para esta función que se pueden recuperar llamando a GetLastError.

Comentarios

Consulte Función QueueUserAPC2 para obtener información sobre las API especiales del modo de usuario.

La compatibilidad de APC proporcionada en el sistema operativo permite a una aplicación poner en cola un objeto de APC en un subproceso. Para garantizar la ejecución correcta de las funciones usadas por APC, las API solo se deben poner en cola en los subprocesos del proceso del autor de la llamada.

Nota

No se recomienda poner en cola las API en subprocesos fuera del proceso del autor de la llamada por varios motivos. La reebasión de DLL puede hacer que las direcciones de las funciones usadas por el APC sean incorrectas cuando las funciones se ejecutan fuera del proceso del autor de la llamada. Del mismo modo, si un proceso de 64 bits pone en cola un APC a un proceso de 32 bits o viceversa, las direcciones serán incorrectas y la aplicación se bloqueará. Otros factores pueden impedir la ejecución correcta de la función, incluso si se conoce la dirección.

Cada subproceso tiene su propia cola de APC. La cola de un APC es una solicitud para que el subproceso llame a la función de APC. El sistema operativo emite una interrupción de software para dirigir el subproceso para llamar a la función de APC.

Cuando se pone en cola un APC en modo de usuario, el subproceso no se dirige a llamar a la función de APC a menos que esté en estado de alerta. Una vez que el subproceso se encuentra en un estado de alerta, el subproceso controla todas las API pendientes en primer lugar, primero en salir (FIFO) y la operación de espera devuelve WAIT_IO_COMPLETION. Un subproceso entra en un estado de alerta mediante la función SleepEx, la función SignalObjectAndWait, la función WaitForSingleObjectEx, la función WaitForMultipleObjectsEx o la función MsgWaitForMultipleObjectsEx.

Si una aplicación pone en cola un APC antes de que el subproceso comience a ejecutarse, el subproceso comienza llamando a la función APC. Una vez que el subproceso llama a una función de APC, llama a las funciones de APC para todas las API de su cola de APC.

Es posible suspender o esperar un objeto dentro del APC. Si realiza una espera alertable dentro de un APC, enviará de forma recursiva las API. Esto puede provocar un desbordamiento de pila.

Cuando el subproceso finaliza mediante la función ExitThread o la función TerminateThread , se pierden las API de su cola de APC. No se llama a las funciones de APC.

Cuando el subproceso está en proceso de finalización, al llamar a QueueUserAPC para agregarlo a la cola de APC del subproceso se producirá un error (31) ERROR_GEN_FAILURE.

Tenga en cuenta que la función ReadFileEx, la función SetWaitableTimer y las funciones de función WriteFileEx se implementan mediante un APC como mecanismo de devolución de llamada de notificación de finalización.

Para compilar una aplicación que usa esta función, defina _WIN32_WINNT como 0x0400 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado processthreadsapi.h (incluye Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también