ICLRProfiling::AttachProfiler メソッド

[アーティクル]
08/09/2011

指定されたプロファイラーを、指定されたプロセスにアタッチします。

HRESULT AttachProfiler(
  [in] DWORD dwProfileeProcessID,
  [in] DWORD dwMillisecondsMax,                     // optional
  [in] const CLSID * pClsidProfiler,
  [in] LPCWSTR wszProfilerPath,                     // optional
  [in] size_is(cbClientData)] void * pvClientData,  // optional
  [in] UINT cbClientData);                          // optional

パラメーター

dwProfileeProcessID
[入力] プロファイラーをアタッチする必要があるプロセスのプロセス ID。 64 ビットコンピューターでは、プロファイル対象のプロセスのビットは AttachProfiler を呼び出しているトリガープロセスのビットに一致する必要があります。 AttachProfiler が呼び出されるユーザーアカウントに管理者特権がある場合は、システム上のどのプロセスもターゲットプロセスにすることもできます。それ以外の場合は、同じユーザーアカウントがターゲットプロセスを所有している必要があります。
dwMillisecondsMax
[入力] AttachProfiler が完了するまでの時間 (ミリ秒単位)。トリガープロセスは、特定のプロファイラーが初期化を完了するために十分であることがわかっているタイムアウトを渡す必要があります。
pClsidProfiler
[入力] 読み込まれるプロファイラーの CLSID へのポインター。トリガープロセスでは、AttachProfiler が戻った後にこのメモリを再利用できます。
wszProfilerPath
[入力] 読み込まれるプロファイラーの DLL ファイルへの完全パス。この文字列に含める文字数は、null 終端文字も含めて 260 文字以内にする必要があります。 wszProfilerPath が null または空の文字列である場合、共通言語ランタイム (CLR: Common Language Runtime) は、pClsidProfiler が示す CLSID のレジストリ内を探してプロファイラーの DLL ファイルの場所を見つけます。
pvClientData
[入力] ICorProfilerCallback3::InitializeForAttach メソッドでプロファイラーに渡されるデータへのポインター。トリガープロセスでは、AttachProfiler が戻った後にこのメモリを再利用できます。 pvClientData が null の場合、cbClientData を 0 (ゼロ) にする必要があります。
cbClientData
[入力] pvClientData によって指定されるデータのサイズのバイト数。

戻り値

このメソッドは、次の特定の HRESULT を返します。

HRESULT	説明
S_OK	指定されたプロファイラーは、正常にターゲットプロセスにアタッチされました。
CORPROF_E_PROFILER_ALREADY_ACTIVE	アクティブなプロファイラーまたはターゲットプロセスにアタッチされているプロファイラーが既に存在します。
CORPROF_E_PROFILER_NOT_ATTACHABLE	指定されたプロファイラーはアタッチをサポートしていません。トリガープロセスは、別のプロファイラーをアタッチする可能性があります。
CORPROF_E_PROFILEE_INCOMPATIBLE_WITH_TRIGGER	ターゲットプロセスのバージョンが、AttachProfiler を呼び出している現在のプロセスと互換性がないため、プロファイラーのアタッチを要求できません。
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	トリガープロセスのユーザーは、ターゲットプロセスにアクセスできません。
HRESULT_FROM_WIN32(ERROR_PRIVILEGE_NOT_HELD)	トリガープロセスのユーザーは、特定のターゲットプロセスにプロファイラーをアタッチするために必要な特権を持っていません。アプリケーションイベントログには、詳細情報が含まれている可能性があります。
CORPROF_E_IPC_FAILED	ターゲットプロセスとやり取りする際にエラーが発生しました。これは、通常、ターゲットプロセスがシャットダウンしていた場合に発生します。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	ターゲットプロセスは存在していないか、アタッチをサポートする CLR を実行していません。これは、ランタイムの列挙型メソッドの呼び出し以降に CLR がアンロードされたことを示している可能性があります。
HRESULT_FROM_WIN32(ERROR_TIMEOUT)	プロファイラーの読み込みを開始せずにタイムアウトの時間切れになりました。アタッチ操作は再試行できます。ターゲットプロセスのファイナライザーがタイムアウト値よりも長く実行されると、タイムアウトが発生します。
E_INVALIDARG	1 つ以上のパラメーターの値が無効です。
E_FAIL	他のいくつかの未指定のエラーが発生しました。
その他のエラーコード	プロファイラーの ICorProfilerCallback3::InitializeForAttach メソッドが、エラーを示す HRESULT を返す場合、AttachProfiler は、それと同じ HRESULT を返します。この場合、E_NOTIMPL は CORPROF_E_PROFILER_NOT_ATTACHABLE に変換されます。

解説

プロファイラーのアタッチとデタッチの詳細については、「プロファイラーのアタッチとデタッチ」を参照してください。

メモリ管理

COM 規則に従うと、pvClientData パラメーターが示すデータのメモリの割り当てと割り当て解除の責任は AttachProfiler の呼び出し元 (たとえば、プロファイラーの開発者が作成したトリガーコード) にあります。 CLR は AttachProfiler の呼び出しを実行するときに、pvClientData が示すメモリをコピーし、それを対象プロセスに送信します。対象プロセス内の CLR が pvClientData ブロックのコピーを受信すると、InitializeForAttach メソッドを通じてプロファイラーにそのブロックを渡してから、対象プロセスから pvClientData ブロックのコピーを解放します。