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에서 지정한 디바이스 instance 키 아래에 있습니다. |
| DriverRegistryKey | 드라이버 관련 정보가 포함된 기존 키를 엽니다. |
| HwProfileRegistryKey | 디바이스 또는 드라이버 정보를 포함하는 현재 하드웨어 프로필을 기준으로 기존 키를 엽니다. 이렇게 하면 드라이버가 하드웨어 프로필 관련 구성 정보에 액세스할 수 있습니다. |
| DeviceInterfaceRegistryKey | PcNewRegistryKey와 함께 사용되지 않습니다. 자세한 내용은 IPort::NewRegistryKey 를 참조하세요. |
GeneralRegistryKey의 RegistryKeyType 값의 경우 호출자는 유효한 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 함수는 디바이스 개체와 포트 개체가 PcNewRegistryKey 호출에서 명시적으로 지정되어야 하지만 NewRegistryKey 호출에만 암시된다는 점을 제외하고 IPort::NewRegistryKey 메서드와 비슷합니다. PcNewRegistryKey 는 주로 어댑터 드라이버에서 사용됩니다. 미니포트 드라이버는 일반적으로 NewRegistryKey 를 대신 호출합니다.
OutRegistryKey 및 OuterUnknown 매개 변수는 COM 개체에 대한 참조 계산 규칙을 따릅니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | PortCls 시스템 드라이버는 Microsoft Windows 98/Me 및 Windows 2000 이상 운영 체제에서 PcNewRegistryKey 함수를 구현합니다. |
| 대상 플랫폼 | 유니버설 |
| 헤더 | portcls.h(Portcls.h 포함) |
| 라이브러리 | Portcls.lib |
| IRQL | PASSIVE_LEVEL |