ホーム › System.Performance › PERFLIBREQUEST

PERFLIBREQUEST

コールバック

シグネチャ

DWORD PERFLIBREQUEST(
    DWORD RequestCode,
    void* Buffer,
    DWORD BufferSize
);

パラメーター

フィールド

型

説明

RequestCode

DWORD

要求コードには、次の値のいずれかを指定できます。

値	意味
PERF_ADD_COUNTER	コンシューマーがクエリにカウンターを追加しています。PERFLIB は、クエリに追加される各カウンターについて、この要求コードでコールバックを呼び出します。Buffer パラメーターには、追加されるカウンターを識別する PERF_COUNTER_IDENTITY 構造体が格納されます。プロバイダーは、この通知をカウントの開始に利用できます。
PERF_REMOVE_COUNTER	コンシューマーがクエリからカウンターを削除しています。PERFLIB は、クエリから削除される各カウンターについて、この要求コードでコールバックを呼び出します。Buffer パラメーターには、削除されるカウンターを識別する PERF_COUNTER_IDENTITY 構造体が格納されます。プロバイダーは、この通知をカウントの停止に利用できます。
PERF_ENUM_INSTANCES	コンシューマーがカウンターセットのインスタンスを列挙しています。Buffer パラメーターには、コンシューマーがインスタンスを列挙している対象のコンピューター名 (または IP アドレス) を示す、null で終わる Unicode 文字列が格納されます。
PERF_COLLECT_START	コンシューマーがカウンターデータの収集を開始しようとしています。Buffer パラメーターには、コンシューマーがデータを収集している対象のコンピューター名 (または IP アドレス) を示す、null で終わる Unicode 文字列が格納されます。プロバイダーは、生データの状態が重要な場合 (たとえば、部分的な更新が許可されないトランザクション関連のカウンターなど) に、この通知を利用できます。この通知によってプロバイダーは、収集が開始される前に保留中の更新をすべてフラッシュし、以降の更新をロックする機会を得られます。
PERF_COLLECT_END	カウンターデータの収集が完了しました。Buffer パラメーターには、コンシューマーがデータを収集した対象のコンピューター名 (または IP アドレス) を示す、null で終わる Unicode 文字列が格納されます。プロバイダーは、この通知を利用して、収集開始の通知によって課された更新ロックを解放し、カウンターデータの更新を再開できるようにできます。

Buffer

void*

バッファーの内容は要求によって異なります。格納される可能性のある内容については、RequestCode パラメーターを参照してください。

BufferSize

DWORD

Buffer パラメーターのサイズ (バイト単位)。

公式ドキュメント

プロバイダーは、コンシューマーがクエリへのカウンターの追加や削除などの特定の操作を行ったときに通知を受け取るために、この関数を実装できます。 PERFLIB は、コンシューマーの要求が完了する前にこのコールバックを呼び出します。

PERFLIBREQUEST 型は、このコールバック関数へのポインターを定義します。ControlCallback 関数は、アプリケーション定義の関数名のプレースホルダーです。

戻り値

コールバックが成功した場合は ERROR_SUCCESS を返します。

コールバックが失敗した場合、要求が PERF_ADD_COUNTER、PERF_ENUM_INSTANCES、または PERF_COLLECT_START であれば、PERFLIB はそのエラーコードをコンシューマーに返します。それ以外の場合、エラーコードは無視されます。

解説(Remarks)

provider 要素の callback 属性が "custom" である場合、または CTRPP の呼び出し時に -NotificationCallback 引数を使用した場合は、この関数を実装する必要があります。コールバック関数の名前は CounterInitialize に渡します。

Windows Vista: CounterInitialize 関数は PerfAutoInitialize という名前です。また、CTRPP ツールは、すべての要求コードを含むこのコールバックのスケルトンを生成します。サポートする要求コードにコードを追加し、それ以外は削除してください。

コールバックは 1 秒以内に完了する必要があります。コールバックが時間内に完了しない場合、PERFLIB はコンシューマーの要求を続行し、コールバックの完了時にその戻り値を無視します。

例

次の例は、 ControlCallback 関数の簡単な実装を示しています。

ULONG MyControlCallback(ULONG RequestCode, PVOID pBuffer, ULONG* pBufferSize)
{
    ULONG Status = ERROR_SUCCESS;
    PWNODE_HEADER Wnode = (PWNODE_HEADER)pBuffer;
    LPWSTR pComputerName = NULL;
    LPWSTR pInstance = NULL;
    PPERF_COUNTER_IDENTITY pCounter;
    UNREFERENCED_PARAMETER(pBufferSize);

    switch (RequestCode) 
    {
        case PERF_ADD_COUNTER:
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0) 
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_REMOVE_COUNTER: 
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0)
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_ENUM_INSTANCES:
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_START: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_END: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        default:
            wprintf(L"Unknown request code, %lu\n", RequestCode);
    }

    return Status;
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)