Función PcNewRegistryKey (portcls.h)
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 |