PERFLIBREQUEST コールバック関数 (perflib.h)

  • [アーティクル]

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

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

構文

PERFLIBREQUEST Perflibrequest;

ULONG Perflibrequest(
  [in] ULONG RequestCode,
  [in] PVOID Buffer,
  [in] ULONG BufferSize
)
{...}

パラメーター

[in] RequestCode

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

値 意味
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 文字列が含まれています。

プロバイダーは、この通知を使用して、カウンター データの更新を再開できるように、コレクション開始通知によって課される更新ロックを解放できます。

[in] Buffer

バッファーの内容は、要求によって異なります。 可能なコンテンツについては、 RequestCode パラメーターを参照してください。

[in] BufferSize

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

戻り値

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

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

注釈

プロバイダー要素の 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;
}

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー perflib.h