CM_Register_Notification関数 (cfgmgr32.h)

[アーティクル]
08/22/2023

CM_Register_Notification関数は、指定した型の PnP イベントが発生したときに呼び出されるアプリケーションコールバックルーチンを登録します。

コードが Windows 7 以前のバージョンの Windows を対象とする場合は、CM_Register_Notificationの代わりに RegisterDeviceNotification を使用します。カーネルモードの呼び出し元は、代わりに IoRegisterPlugPlayNotification を使用する必要があります。

構文

CMAPI CONFIGRET CM_Register_Notification(
  [in]           PCM_NOTIFY_FILTER   pFilter,
  [in, optional] PVOID               pContext,
  [in]           PCM_NOTIFY_CALLBACK pCallback,
  [out]          PHCMNOTIFICATION    pNotifyContext
);

パラメーター

[in] pFilter

CM_NOTIFY_FILTER構造体へのポインター。

[in, optional] pContext

pCallback のコールバックルーチンに渡されるコンテキストを含む呼び出し元によって割り当てられたバッファーへのポインター。

[in] pCallback

指定した PnP イベントが発生したときに呼び出されるルーチンへのポインター。コールバック関数のプロトタイプについては、「解説」セクションを参照してください。

コールバックルーチンの Action パラメーターは、 CM_NOTIFY_ACTION 列挙の値になります。

通知を受信すると、コールバックが通知を調べる方法は、コールバックルーチンの EventData パラメーターの FilterType メンバーによって異なります。

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

コールバックは EventData-u.DeviceInterface> を調べる必要があります。

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

コールバックは EventData-u.DeviceHandle> を調べる必要があります。

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

コールバックは EventData-u.DeviceInstance> を調べる必要があります。

[out] pNotifyContext

登録呼び出しに対応する HCMNOTIFICATION ハンドルを受け取るポインター。

戻り値

操作が成功した場合、関数はCR_SUCCESSを返します。それ以外の場合は、 Cfgmgr32.h で定義されているCR_プレフィックス付きのエラーコードのいずれかを返します。

注釈

プラグアンドプレイデバイスイベントは、できるだけ早く処理してください。イベントハンドラーが実行をブロックする可能性がある操作 (I/O など) を実行する場合は、別のスレッドを起動して操作を非同期的に実行することをお勧めします。

CM_Register_Notification関数は、既存のデバイスインターフェイスの通知を提供しません。既存のインターフェイスを取得するには、最初 に CM_Register_Notification を呼び出し、次に CM_Get_Device_Interface_List を呼び出します。ドライバーが CM_Register_Notificationを呼び出した後で、ドライバーが CM_Get_Device_Interface_Listを呼び出す前にインターフェイスが有効になっている場合、ドライバーはインターフェイス到着の通知を受け取り、インターフェイスは CM_Get_Device_Interface_List によって返されるデバイスインターフェイスインスタンスの一覧にも表示されます。

CM_Register_Notificationによって返される HCMNOTIFICATION ハンドルは、不要になったCM_Unregister_Notification関数を呼び出して閉じる必要があります。

コールバックルーチンは、次の関数プロトタイプを使用します。

typedef __callback DWORD (CALLBACK *PCM_NOTIFY_CALLBACK)(
    _In_ HCMNOTIFICATION       hNotify,
    _In_opt_ PVOID             Context,
    _In_ CM_NOTIFY_ACTION      Action,
    _In_reads_bytes_(EventDataSize) PCM_NOTIFY_EVENT_DATA EventData,
    _In_ DWORD                 EventDataSize
    );

CM_NOTIFY_ACTION_DEVICEQUERYREMOVE通知に応答する場合、PCM_NOTIFY_CALLBACKコールバックは必要に応じて、ERROR_SUCCESSまたはERROR_CANCELLEDを返す必要があります。それ以外の場合、コールバックはERROR_SUCCESSを返す必要があります。コールバックは、他の値を返さないでください。その他のアクションの説明については、 CM_NOTIFY_ACTION ドキュメントを参照してください。 EventData パラメーターでこのコールバックが受け取る構造体については、「CM_NOTIFY_EVENT_DATA」も参照してください。

例

例については、「デバイスインターフェイスの到着とデバイスの削除の通知の登録」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Microsoft Windows 8 以降のバージョンの Windows で使用できます。
対象プラットフォーム	ユニバーサル
Header	cfgmgr32.h (Cfgmgr32.h を含む)
Library	Cfgmgr32.lib;Windows 10の OneCoreUAP.lib
[DLL]	CfgMgr32.dll