QueueUserAPC 関数 (processthreadsapi.h)
指定したスレッドの APC キューにユーザー モード 非同期プロシージャ 呼び出し (APC) オブジェクトを追加します。
構文
DWORD QueueUserAPC(
[in] PAPCFUNC pfnAPC,
[in] HANDLE hThread,
[in] ULONG_PTR dwData
);
パラメーター
[in] pfnAPC
指定したスレッドがアラート可能な待機操作を実行するときに呼び出されるアプリケーション提供の APC 関数へのポインター。 詳細については、「 PAPCFUNC コールバック関数」を参照してください。
[in] hThread
スレッドへのハンドル。 ハンドルには 、THREAD_SET_CONTEXT アクセス権が必要です。 詳細については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。
[in] dwData
pfnAPC パラメーターによって指される APC 関数に渡される単一の値。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。 Windows Server 2003 および Windows XP: この関数には、 GetLastError を呼び出して取得できるエラー値は定義されていません。
注釈
特殊なユーザー モード APC の詳細については、「 QueueUserAPC2 関数 」を参照してください。
オペレーティング システムで提供される APC サポートを使用すると、アプリケーションは APC オブジェクトをスレッドにキューに入れられます。 APC で使用される関数が正常に実行されるようにするには、APC を呼び出し元のプロセス内のスレッドにのみキューに入れておく必要があります。
注意
呼び出し元のプロセス外のスレッドに APC をキューに入れるのは、さまざまな理由で推奨されません。 DLL の再評価により、呼び出し元のプロセスの外部で関数が実行されると、APC で使用される関数のアドレスが正しくない可能性があります。 同様に、64 ビット プロセスが APC を 32 ビット プロセスにキューに登録した場合、またはその逆の場合、アドレスが正しくなっていなくても、アプリケーションがクラッシュします。 その他の要因により、アドレスがわかっている場合でも、関数の正常な実行を妨げる可能性があります。
各スレッドには、独自の APC キューがあります。 APC のキューは、スレッドが APC 関数を呼び出す要求です。 オペレーティング システムは、APC 関数を呼び出すようにスレッドに指示するソフトウェア割り込みを発行します。
ユーザー モード APC がキューに入れられたときに、このスレッドがアラート可能な状態である場合を除き、スレッドは APC 関数を呼び出すよう指示されません。 スレッドがアラート可能な状態の後、スレッドは保留中のすべての APC を最初の入力、先出し (FIFO) 順に処理し、待機操作は WAIT_IO_COMPLETIONを返します。 スレッドは、SleepEx 関数、SignalObjectAndWait 関数、WaitForSingleObjectEx 関数、WaitForMultipleObjectsEx 関数、または MsgWaitForMultipleObjectsEx 関数を使用して、アラート可能な状態になります。
スレッドの実行を開始する前にアプリケーションが APC をキューに入れる場合、スレッドは APC 関数を呼び出すことによって開始されます。 スレッドは APC 関数を呼び出した後、APC キュー内のすべての APC に対して APC 関数を呼び出します。
APC 内のオブジェクトをスリープまたは待機することができます。 APC 内でアラート可能な待機を実行すると、APC は再帰的にディスパッチされます。 これにより、スタック オーバーフローが発生する可能性があります。
ExitThread 関数または TerminateThread 関数関数を使用してスレッドが終了すると、その APC キュー内の APC は失われます。 APC 関数は呼び出されません。
スレッドが終了処理中の場合、QueueUserAPC を呼び出してスレッドの APC キューに追加すると、 (31) ERROR_GEN_FAILUREで失敗します。
ReadFileEx 関数、SetWaitableTimer 関数、および WriteFileEx 関数は、完了通知コールバック メカニズムとして APC を使用して実装されることに注意してください。
この関数を使用するアプリケーションをコンパイルするには、 0x0400 以降として_WIN32_WINNTを定義します。 詳細については、「 Windows ヘッダーの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | processthreadsapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |