PcNewRegistryKey 関数 (portcls.h)

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

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