QueueUserAPC

ユーザモードの非同期プロシージャ呼び出し(APC)オブジェクトを、指定したスレッドの APC キューに追加する。(QueueUserAPC)

QueueUserAPC pfnAPC, hThread, dwData

pfnAPC : [int] 指定されたスレッドがアラート可能な待機操作を実行したときに呼び出される、アプリケーション側で用意した APC 関数へのポインタ。詳細は [PAPCFUNC callback function](../winnt/nc-winnt-papcfunc.md) を参照。
hThread : [intptr] スレッドへのハンドル。ハンドルは **THREAD_SET_CONTEXT** アクセス権を持つ必要がある。詳細は [Synchronization Object Security and Access Rights](/windows/desktop/Sync/synchronization-object-security-and-access-rights) を参照。
dwData : [int] *pfnAPC* パラメータが指す APC 関数に渡される単一の値。

(プラグイン / モジュール : kernel32.dll)

解説

ユーザモードの非同期プロシージャ呼び出し(APC)オブジェクトを、指定したスレッドの APC
キューに追加する。(QueueUserAPC)

[戻り値]
関数が成功した場合、戻り値は 0 以外である。関数が失敗した場合、戻り値は 0 である。拡張エラー情報を取得するには
[GetLastError](/windows/desktop/api/errhandlingapi/nf-errhandlingapi-getlasterror)
を呼び出す。**Windows Server 2003 および Windows XP:** この関数には GetLastError
で取得可能なエラー値は定義されていない。

[備考]
特殊なユーザモード APC については [QueueUserAPC2
function](nf-processthreadsapi-queueuserapc2.md)
を参照。オペレーティングシステムが提供する APC サポートにより、アプリケーションは APC
オブジェクトをスレッドにキューイングできる。APC が使用する関数を確実に実行するため、APC
は呼び出し側プロセス内のスレッドにのみキューイングすべきである。>[!NOTE] > 呼び出し側プロセス外のスレッドに APC
をキューイングすることは、いくつかの理由で推奨されない。DLL のリベースにより、APC
が使用する関数のアドレスが呼び出し側プロセス外での実行時に正しくない可能性がある。同様に、64 ビットプロセスが 32 ビットプロセスへ
APC
をキューイングする(またはその逆)場合、アドレスは正しくなくアプリケーションはクラッシュする。アドレスが判明していても、他の要因が関数の正常実行を妨げる場合がある。各スレッドは独自の
APC キューを持つ。APC のキューイングは、スレッドに APC
関数を呼び出すよう要求することである。オペレーティングシステムはソフトウェア割り込みを発行し、スレッドに APC
関数の呼び出しを指示する。ユーザモード APC がキューイングされた場合、スレッドはアラート可能な状態にならない限り APC
関数を呼び出すよう指示されない。スレッドがアラート可能な状態になると、キュー内の保留中 APC
を先入れ先出し(FIFO)順に全て処理し、待機操作は **WAIT_IO_COMPLETION** を返す。スレッドは [SleepEx
function](../synchapi/nf-synchapi-sleepex.md)、[SignalObjectAndWait
function](../synchapi/nf-synchapi-signalobjectandwait.md)、[WaitForSingleObjectEx
function](../synchapi/nf-synchapi-waitforsingleobjectex.md)、[WaitForMultipleObjectsEx
function](../synchapi/nf-synchapi-waitformultipleobjectsex.md)、または
[MsgWaitForMultipleObjectsEx
function](../winuser/nf-winuser-msgwaitformultipleobjectsex.md)
を使用することでアラート可能な状態になる。スレッドが実行開始する前にアプリケーションが APC をキューイングした場合、スレッドはまず
APC 関数の呼び出しから開始する。スレッドが APC 関数を呼び出した後、APC キュー内の全 APC に対する APC
関数を呼び出す。APC 内部からオブジェクトをスリープまたは待機することが可能である。APC 内でアラート可能な待機を実行すると、APC
を再帰的にディスパッチすることになり、スタックオーバーフローを引き起こしうる。スレッドが [ExitThread
function](nf-processthreadsapi-exitthread.md) または [TerminateThread
function](nf-processthreadsapi-terminatethread.md) で終了されるとき、APC キュー内の
APC は失われ、APC 関数は呼び出されない。スレッドが終了処理中であるとき、QueueUserAPC を呼び出してスレッドの APC
キューに追加しようとすると **(31) ERROR_GEN_FAILURE** で失敗する。[ReadFileEx
function](../fileapi/nf-fileapi-readfileex.md)、[SetWaitableTimer
function](../synchapi/nf-synchapi-setwaitabletimer.md)、および
[WriteFileEx function](../fileapi/nf-fileapi-writefileex.md) は APC
を完了通知コールバック機構として使用して実装されている点に注意すること。この関数を使用するアプリケーションをコンパイルするには、**_WIN32_WINNT**
を 0x0400 以上に定義する。詳細は [Using the Windows
Headers](/windows/desktop/WinProg/using-the-windows-headers) を参照。

情報