PcNewRegistryKey 関数 (portcls.h)

[アーティクル]
02/07/2025

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 関数を実装します。
ターゲットプラットフォームの	万国
ヘッダー	portcls.h (Portcls.h を含む)
ライブラリ	Portcls.lib
IRQL	PASSIVE_LEVEL

次の方法で共有

PcNewRegistryKey 関数 (portcls.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース