Funzione QueueUserAPC (processthreadsapi.h)

  • Articolo

Aggiunge un oggetto APC (User-Mode Procedure Call ) alla coda APC del thread specificato.

Sintassi

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

Parametri

[in] pfnAPC

Puntatore alla funzione APC fornita dall'applicazione da chiamare quando il thread specificato esegue un'operazione di attesa avvisabile. Per altre informazioni, vedere Funzione di callback PAPCFUNC.

[in] hThread

Handle per il thread. L'handle deve avere il diritto di accesso THREAD_SET_CONTEXT . Per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.

[in] dwData

Valore singolo passato alla funzione APC a cui fa riferimento il parametro pfnAPC .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError. Windows Server 2003 e Windows XP: Non sono presenti valori di errore definiti per questa funzione che possono essere recuperati chiamando GetLastError.

Commenti

Per informazioni sulle API in modalità utente speciale, vedere La funzione QueueUserAPC2 .

Il supporto APC fornito nel sistema operativo consente a un'applicazione di accodare un oggetto APC a un thread. Per garantire l'esecuzione corretta delle funzioni usate dal servizio APC, le API devono essere accodate solo ai thread nel processo del chiamante.

Nota

L'accodamento delle API ai thread all'esterno del processo del chiamante non è consigliato per diversi motivi. La ribasing della DLL può causare l'errore degli indirizzi delle funzioni usati dal servizio Azure Kubernete quando le funzioni vengono eseguite all'esterno del processo del chiamante. Analogamente, se un processo a 64 bit accoda un APC a un processo a 32 bit o viceversa, gli indirizzi non saranno corretti e l'applicazione si arresterà in modo anomalo. Altri fattori possono impedire l'esecuzione di funzioni riuscite, anche se l'indirizzo è noto.

Ogni thread ha una coda APC personalizzata. L'accodamento di un APC è una richiesta per il thread di chiamare la funzione APC. Il sistema operativo genera un interruzione software per indirizzare il thread per chiamare la funzione APC.

Quando un APC in modalità utente viene accodato, il thread non viene indirizzato per chiamare la funzione APC a meno che non si tratti di uno stato avvisabile. Dopo che il thread si trova in uno stato avvisabile, il thread gestisce tutte le API in sospeso in primo luogo nell'ordine FIFO (First Out) e l'operazione di attesa restituisce WAIT_IO_COMPLETION. Un thread entra in uno stato avvisabile usando la funzione SleepEx, SignalObjectAndWait, la funzione WaitForSingleObjectEx, la funzione WaitForMultipleObjectsEx o La funzione MsgWaitForMultipleObjectsEx.

Se un'applicazione accoda un APC prima dell'avvio del thread, il thread inizia chiamando la funzione APC. Dopo che il thread chiama una funzione APC, chiama le funzioni APC per tutte le API nella coda APC.

È possibile dormire o attendere un oggetto all'interno dell'APC. Se si esegue un'attesa avvisabile all'interno di un APC, verrà inviato in modo ricorsivo le API. Ciò può causare un overflow dello stack.

Quando il thread viene terminato usando la funzione ExitThread o la funzione di funzione TerminateThread , le API nella coda APC vengono perse. Le funzioni APC non vengono chiamate.

Quando il thread si trova nel processo di chiusura, la chiamata a QueueUserAPC per aggiungere alla coda APC del thread avrà esito negativo con (31) ERROR_GEN_FAILURE.

Si noti che la funzione ReadFileEx, la funzione SetWaitableTimer e le funzioni di funzione WriteFileEx vengono implementate usando un oggetto APC come meccanismo di callback di notifica di completamento.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0400 o versioni successive. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione processthreadsapi.h (includere Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche