PcNewRegistryKey 関数 (portcls.h)
PcNewRegistryKey 関数は、新しいレジストリ キーを開くか作成し、キーを表す IRegistryKey オブジェクトを作成します。 呼び出し元は、このオブジェクトを介してキーにアクセスします。
構文
PORTCLASSAPI NTSTATUS PcNewRegistryKey(
[out] PREGISTRYKEY *OutRegistryKey,
[in, optional] PUNKNOWN OuterUnknown,
[in] ULONG RegistryKeyType,
[in] ACCESS_MASK DesiredAccess,
[in, optional] PVOID DeviceObject,
[in, optional] PVOID SubDevice,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] ULONG CreateOptions,
[out, optional] PULONG Disposition
);
パラメーター
[out] OutRegistryKey
この関数によって作成されたレジストリ キー オブジェクトへの出力ポインター。 このパラメーターは、関数が IRegistryKey オブジェクトへのポインターを出力する呼び出し元によって割り当てられたポインター変数を指します。 オブジェクトは、開かれているレジストリ キーまたは作成されるレジストリ キーを表します。 このパラメーターに有効な NULL 以外のポインター値を指定します。
[in, optional] OuterUnknown
OutRegistryKey オブジェクトを集計する必要があるオブジェクトの IUnknown インターフェイスへのポインター。 集計が必要な場合を除き、このパラメーターを NULL に設定 します。
[in] RegistryKeyType
呼び出し元が作成または開くレジストリ キーの種類を指定します。 詳細については、「解説」を参照してください。
[in] DesiredAccess
アクセス制御マスクを指定します。 このパラメーターは、 ACCESS_MASK型の構造体です。 これは、呼び出し元が開くか作成されるレジストリ キーに対して要求しているアクセスの種類を示します。 詳細については、「解説」を参照してください。
[in, optional] DeviceObject
アダプター ドライバーのデバイス オブジェクトへのポインター。 このポインターは PVOID 型にキャストされます。 RegistryKeyType が GeneralRegistryKey 以外の値である場合、このパラメーターは、DEVICE_OBJECT型の有効な初期化されたシステム構造を指す必要があります。 RegistryKeyType の値が GeneralRegistryKey の場合、PcNewRegistryKey 関数はこのパラメーターを使用しません。 詳細については、「解説」を参照してください。
[in, optional] SubDevice
クライアントに提供されるデバイスの側面を指定します。 アダプター ドライバーでは、このパラメーターに 値 NULL を 割り当てる必要があります。
[in, optional] ObjectAttributes
作成または開いているキーのオブジェクト属性へのポインター。 RegistryKeyType の値が GeneralRegistryKey の場合、このパラメーターは、キーの有効な ObjectName 文字列を持つOBJECT_ATTRIBUTES型の有効で初期化されたシステム構造を指す必要があります。それ以外の場合、関数はこのパラメーターを使用しません。 詳細については、「解説」を参照してください。
[in, optional] CreateOptions
作成オプションを指定します。 何も必要ない場合は、0 を指定できます。 RegistryKeyType が GeneralRegistryKey でない場合、PcNewRegistryKey 関数はこのパラメーターを無視します。 詳細については、「解説」を参照してください。
[out, optional] Disposition
キーが作成されたか、既存のキーが開かれたかを示す値を受け取る変数へのポインター。 このパラメーターは省略可能であり、 NULL として指定できます。 RegistryKeyType が GeneralRegistryKey 以外の値である場合、PcNewRegistryKey 関数はこのパラメーターを無視します。 詳細については、「解説」を参照してください。
戻り値
呼び出しが成功した場合、PcNewRegistryKey はSTATUS_SUCCESSを返します。 それ以外の場合は、適切なエラー コードを返します。
注釈
RegistryKeyType パラメーターの値が GeneralRegistryKey の場合、PcNewRegistryKey 関数は既存のキーを開くか、Disposition パラメーターを使用して関数が出力する値によって示されるように、レジストリに新しいキーを作成します。 キーが GeneralRegistryKey 以外の型の場合、この関数は、デバイスの列挙時に以前に作成された既存のキープラグ アンド プレイ開きます。
DesiredAccess、ObjectAttributes、CreateOptions、および Disposition パラメーターは、ZwCreateKey 呼び出しで同じ名前のパラメーターに対して定義されている値を受け取ります。
RegistryKeyType パラメーターは、次の表に示す列挙値のいずれかに設定する必要があります。
| RegistryKeyType 値 | 意味 |
|---|---|
| GeneralRegistryKey | 任意のキー型への汎用アクセスを提供します。 指定したキーが既に存在する場合は開き、存在しない場合はキーを作成します。 |
| DeviceRegistryKey | デバイス固有の情報を含む既存のキーを開きます。 このキーは、 DeviceObject で指定されたデバイス インスタンスのキーの下にあります。 |
| DriverRegistryKey | ドライバー固有の情報を含む既存のキーを開きます。 |
| HwProfileRegistryKey | デバイスまたはドライバーの情報を含む現在のハードウェア プロファイルに関連する既存のキーを開きます。 これにより、ドライバーはハードウェア プロファイル固有の構成情報にアクセスできます。 |
| DeviceInterfaceRegistryKey | PcNewRegistryKey では使用されません。 詳細については、「 IPort::NewRegistryKey 」を参照してください。 |
RegistryKeyType 値が GeneralRegistryKey の場合、呼び出し元は有効な ObjectAttributes パラメーター値を指定する必要があり、CreateOptions パラメーターと Disposition パラメーターは省略可能です。 その他の RegistryKeyType 値の場合、呼び出し元は有効な DeviceObject パラメーター値を指定する必要があり、 CreateOptions パラメーターと Disposition パラメーターは使用されません。
ObjectAttributes パラメーターは、キー名やセキュリティ記述子などのオブジェクト属性を含むOBJECT_ATTRIBUTES型の不透明な構造体を指します。 InitializeObjectAttributes マクロを使用して構造体を初期化します。 このマクロの Attributes パラメーターで、セキュリティで保護されていないユーザー モード アプリケーションがレジストリ キーへの読み取り/書き込みアクセスを許可しない限り、OBJ_KERNEL_HANDLE フラグを設定します。
DesiredAccess パラメーターは、アクセス制御マスクです。 OutRegistryKey オブジェクトを使用してアクセスするときに、呼び出し元が新しいレジストリ キーに対して必要とするアクセス制御の種類を指定します。 このマスクは、レジストリ キーへのユーザーによるアクセスを制御するアクセス制御リスト (ACL) と混同しないでください。 PcNewRegistryKey を呼び出して GeneralRegistryKey 型のレジストリ キーを作成する場合、ObjectAttributes パラメーターは、ACL を含むセキュリティ記述子を含むキーの属性を指定します。 ただし、新しいキーが GeneralRegistryKey 型で 、ObjectAttributes 構造体のセキュリティ記述子ポインターが NULL であるか、セキュリティ記述子の ACL ポインターが NULL の場合、新しいキーは既定で親キーの ACL を継承します。
キーが GeneralRegistryKey 以外の型の場合、キーは、デバイスの列挙時にキーが作成されたときにキーに割り当てられた ACL を保持プラグ アンド プレイ。
PcNewRegistryKey 関数は IPort::NewRegistryKey メソッドに似ていますが、デバイス オブジェクトとポート オブジェクトは PcNewRegistryKey 呼び出しで明示的に指定する必要がありますが、単に NewRegistryKey 呼び出しでは暗黙的に指定される必要があります。 PcNewRegistryKey は、主にアダプター ドライバーによって使用されます。 ミニポート ドライバーは通常、代わりに NewRegistryKey を 呼び出します。
OutRegistryKey パラメーターと OuterUnknown パラメーターは、COM オブジェクトの参照カウント規則に従います。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | PortCls システム ドライバーは、Microsoft Windows 98/Me および Windows 2000 以降のオペレーティング システムで PcNewRegistryKey 関数を実装します。 |
| 対象プラットフォーム | ユニバーサル |
| Header | portcls.h (Portcls.h を含む) |
| Library | Portcls.lib |
| IRQL | PASSIVE_LEVEL |