Método IPort::NewRegistryKey (portcls.h)
El método NewRegistryKey abre una clave del Registro existente o crea una nueva clave en el Registro. El método crea un objeto de clave del Registro para representar la clave y genera una referencia a este objeto al autor de la llamada. A continuación, el autor de la llamada accede a la clave a través de la interfaz IRegistryKey del objeto.
Sintaxis
NTSTATUS NewRegistryKey(
PREGISTRYKEY *OutRegistryKey,
PUNKNOWN OuterUnknown,
ULONG RegistryKeyType,
ACCESS_MASK DesiredAccess,
POBJECT_ATTRIBUTES ObjectAttributes,
ULONG CreateOptions,
PULONG Disposition
);
Parámetros
OutRegistryKey
Puntero a una variable de puntero asignada por el autor de la llamada en la que el método escribe la referencia al objeto IRegistryKey. Este objeto representa la clave del Registro que se está abriendo o creando. El llamador debe especificar un valor de puntero válido que no sea NULL para este parámetro.
OuterUnknown
Puntero a la interfaz IUnknown de un objeto que necesita agregar el objeto de clave del Registro. Este parámetro es opcional. Si no se requiere la agregación, especifique este parámetro como NULL.
RegistryKeyType
Especifica el tipo de clave del Registro a la que el autor de la llamada solicita acceso. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
DesiredAccess
Máscara de control de acceso que especifica el tipo de acceso que el autor de la llamada requiere para la clave. Este parámetro es de tipo ACCESS_MASK. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
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, el método no usa este parámetro. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
CreateOptions
Marcas que indican las opciones de creación. Puede ser cero si no se desea ninguno. Este parámetro es necesario si RegistryKeyType tiene el valor GeneralRegistryKey; de lo contrario, el método no usa este parámetro. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
Disposition
Puntero a una variable ULONG asignada por el autor de la llamada en la que el método escribe un valor de estado que indica si se creó una nueva clave o se abrió una clave existente. Este parámetro es opcional y se puede especificar como NULL si el autor de la llamada no necesita el valor de estado. El método usa este parámetro solo si RegistryKeyType tiene el valor GeneralRegistryKey. El método no usa el parámetro para ninguno de los otros tipos de clave. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
Valor devuelto
Este método devuelve NTSTATUS que contiene STATUS_SUCCESS si la llamada se realizó correctamente. De lo contrario, el método devuelve un código de error adecuado.
Comentarios
Los parámetros DesiredAccess, ObjectAttributes y Disposition toman los valores definidos para los parámetros con los mismos nombres en la llamada ZwCreateKey.
Si el parámetro RegistryKeyType tiene el valor GeneralRegistryKey, el método NewRegistryKey abre una clave del Registro existente o crea una clave nueva en el Registro, como se indica en el valor que el método genera a través del parámetro Disposition. Si el tipo de clave es cualquier valor distinto de GeneralRegistryKey, el método abre una clave ya existente que se creó anteriormente durante Plug and Play enumeración del dispositivo.
El llamador debe establecer el parámetro RegistryKeyType en uno de los valores de enumeración que se muestran en la tabla siguiente.
| Valor registryKeyType | Significado |
|---|---|
| GeneralRegistryKey | Proporcione acceso genérico a cualquier tipo de clave. Abre la clave si existe o crea la clave si no lo hace. |
| DeviceRegistryKey | Abra una clave existente que contenga información específica del dispositivo. |
| DriverRegistryKey | Abra una clave existente que contenga información específica del controlador. |
| HwProfileRegistryKey | Abra una clave existente relativa al perfil de hardware actual para la 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 | Abra una clave del Registro existente que contenga información sobre una instancia de interfaz de dispositivo determinada. |
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 tenga previsto 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 ACL (lista de control de acceso) que controla el acceso de los usuarios a la clave del Registro. Al llamar a NewRegistryKey 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 el tipo de clave es 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 creada por la llamada heredará la ACL de la clave primaria de forma predeterminada.
Si la clave no es de tipo GeneralRegistryKey, la clave conserva la ACL que Plug and Play asignó a la clave cuando se creó durante la enumeración del dispositivo.
El método NewRegistryKey es similar a la función PcNewRegistryKey, salvo que el objeto de dispositivo y el objeto de puerto deben especificarse explícitamente en una llamada PcNewRegistryKey, pero simplemente están implícitos en una llamada a NewRegistryKey. Los controladores del adaptador suelen llamar a PcNewRegistryKey. Los controladores de minipuerto suelen llamar a NewRegistryKey en su lugar.
Una vez creada o abierta una clave del Registro mediante una llamada a NewRegistryKey o PcNewRegistryKey, el método IRegistryKey::NewSubKey se puede usar para crear subclaves en esa clave.
Los parámetros OutRegistryKey y OuterUnknown siguen las convenciones de recuento de referencias para objetos COM.
Requisitos
| Requisito | Valor |
|---|---|
| Header | portcls.h |
| IRQL | PASSIVE_LEVEL |