Función PcNewRegistryKey (portcls.h)

Artículo
02/26/2024

La función PcNewRegistryKey abre o crea una nueva clave del Registro y crea un objeto IRegistryKey para representar la clave. El autor de la llamada accede a la clave a través de este objeto .

Sintaxis

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
);

Parámetros

[out] OutRegistryKey

Puntero de salida al objeto de clave del Registro creado por esta función. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que la función genera el puntero al objeto IRegistryKey . El objeto representa la clave del Registro que se abre o crea. Especifique un valor de puntero válido que no sea NULL para este parámetro.

[in, optional] OuterUnknown

Puntero a la interfaz IUnknown de un objeto que necesita agregar el objeto OutRegistryKey . A menos que se requiera la agregación, establezca este parámetro en NULL.

[in] RegistryKeyType

Especifica el tipo de clave del Registro que el autor de la llamada quiere crear o abrir. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in] DesiredAccess

Especifica una máscara de control de acceso. Este parámetro es una estructura de tipo ACCESS_MASK. Indica el tipo de acceso que el autor de la llamada solicita a la clave del Registro que se va a abrir o crear. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] DeviceObject

Puntero al objeto de dispositivo del controlador del adaptador. Este puntero se convierte en el tipo PVOID. Si RegistryKeyType es cualquier valor distinto de GeneralRegistryKey, este parámetro debe apuntar a una estructura del sistema inicializada válida de tipo DEVICE_OBJECT. Si el valor de RegistryKeyType es GeneralRegistryKey, la función PcNewRegistryKey no usa este parámetro. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] SubDevice

Especifica el aspecto del dispositivo que se va a ofrecer a los clientes. Los controladores de adaptador deben asignar el valor NULL a este parámetro.

[in, optional] ObjectAttributes

Puntero a los atributos de objeto de la clave que se va a crear o abrir. Si RegistryKeyType tiene el valor GeneralRegistryKey, este parámetro debe apuntar a una estructura del sistema válida inicializada de tipo OBJECT_ATTRIBUTES con una cadena ObjectName válida para la clave; de lo contrario, la función no usa este parámetro. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] CreateOptions

Especifica las opciones de creación. Puede ser cero si no se desea ninguno. Si RegistryKeyType no es GeneralRegistryKey, la función PcNewRegistryKey omite este parámetro. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[out, optional] Disposition

Puntero a una variable que recibe un valor que indica si se creó una clave o se abrió una clave existente. Este parámetro es opcional y se puede especificar como NULL. Si RegistryKeyType es cualquier valor distinto de GeneralRegistryKey, la función PcNewRegistryKey omite este parámetro. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

PcNewRegistryKey devuelve STATUS_SUCCESS si la llamada se realizó correctamente. De lo contrario, devuelve un código de error adecuado.

Comentarios

Si el valor del parámetro RegistryKeyType es GeneralRegistryKey, la función PcNewRegistryKey abre una clave existente o crea una nueva clave en el Registro, como se indica en el valor que la función genera a través del parámetro Disposition . Si la clave es de cualquier tipo que no sea GeneralRegistryKey, la función abre una clave ya existente que se creó anteriormente durante Plug and Play enumeración de dispositivos.

Los parámetros DesiredAccess, ObjectAttributes, CreateOptions y Disposition toman los valores definidos para los parámetros con los mismos nombres en la llamada ZwCreateKey .

El parámetro RegistryKeyType debe establecerse en uno de los valores de enumeración que se muestran en la tabla siguiente.

Valor de RegistryKeyType	Significado
GeneralRegistryKey	Proporcione acceso genérico a cualquier tipo de clave. Abra la clave especificada si ya existe o cree la clave si no lo hace.
DeviceRegistryKey	Abra una clave existente que contenga información específica del dispositivo. La clave se encuentra bajo la clave de la instancia de dispositivo especificada por DeviceObject.
DriverRegistryKey	Abra una clave existente que contenga información específica del controlador.
HwProfileRegistryKey	Abra una clave existente en relación con el perfil de hardware actual que contiene información del dispositivo o del controlador. Esto permite al controlador acceder a la información de configuración específica del perfil de hardware.
DeviceInterfaceRegistryKey	No se usa con PcNewRegistryKey. Consulte IPort::NewRegistryKey para obtener más información.

Para un valor RegistryKeyType de GeneralRegistryKey, el autor de la llamada debe proporcionar un valor de parámetro ObjectAttributes válido y los parámetros CreateOptions y Disposition son opcionales. Para cualquier otro valor RegistryKeyType , el autor de la llamada debe proporcionar un valor de parámetro DeviceObject válido y no se usan los parámetros CreateOptions y Disposition .

El parámetro ObjectAttributes apunta a una estructura opaca de tipo OBJECT_ATTRIBUTES que contiene atributos de objeto como el nombre de clave y el descriptor de seguridad. Use la macro InitializeObjectAttributes para inicializar la estructura. En el parámetro Attributes de esta macro, establezca la marca OBJ_KERNEL_HANDLE a menos que quiera permitir que las aplicaciones en modo de usuario no seguras tengan acceso de lectura y escritura a la clave del Registro.

El parámetro DesiredAccess es una máscara de control de acceso. Especifica el tipo de control de acceso que el autor de la llamada debe tener en la nueva clave del Registro al acceder a él a través del objeto OutRegistryKey . Esta máscara no debe confundirse con la lista de control de acceso (ACL) que controla el acceso de los usuarios a la clave del Registro. Al llamar a PcNewRegistryKey para crear una clave del Registro de tipo GeneralRegistryKey, el parámetro ObjectAttributes especifica los atributos de la clave, incluido un descriptor de seguridad que contiene la ACL. Sin embargo, si la nueva clave es de tipo GeneralRegistryKey y el puntero del descriptor de seguridad de la estructura ObjectAttributes es NULL o el puntero ACL del descriptor de seguridad es NULL, la nueva clave heredará la ACL de la clave primaria de forma predeterminada.

Si la clave es de cualquier tipo que no sea GeneralRegistryKey, la clave conserva la ACL que Plug and Play asignada a la clave cuando se creó durante la enumeración del dispositivo.

La función PcNewRegistryKey es similar al método IPort::NewRegistryKey , salvo que el objeto de dispositivo y el objeto de puerto deben especificarse explícitamente en una llamada a PcNewRegistryKey , pero simplemente están implícitas en una llamada a NewRegistryKey . PcNewRegistryKey se usa principalmente por controladores de adaptador. Los controladores de miniport suelen llamar a NewRegistryKey en su lugar.

Los parámetros OutRegistryKey y OuterUnknown siguen las convenciones de recuento de referencias para objetos COM.

Requisitos

Requisito	Value
Cliente mínimo compatible	El controlador del sistema PortCls implementa la función PcNewRegistryKey en Microsoft Windows 98/Me y en los sistemas operativos Windows 2000 y versiones posteriores.
Plataforma de destino	Universal
Encabezado	portcls.h (incluya Portcls.h)
Library	Portcls.lib
IRQL	PASSIVE_LEVEL