Método IRegistryKey::NewSubKey (portcls.h)

Artículo
08/07/2023

El NewSubKey método crea una nueva subclave del Registro o abre una subclave existente bajo la clave representada por el objeto IRegistryKey .

Sintaxis

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

Parámetros

[out] RegistrySubKey

Puntero de salida para la nueva subclave. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que el método escribe el puntero en el nuevo objeto IRegistryKey . Este objeto representa la subclave que se abre o crea. Especifique un valor de puntero válido que no sea NULL para este parámetro.

[in] 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.

[in] DesiredAccess

Especifica el tipo de acceso que requiere el autor de la llamada a la subclave que se abre o crea. 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.

[in] SubKeyName

Puntero al nombre que se va a asignar a la subclave. Este parámetro debe ser un puntero válido que no sea NULL a una estructura inicializada de tipo UNICODE_STRING.

[in] CreateOptions

Marcas que indican las opciones de creación. Puede ser cero si no se desea ninguno. Este parámetro es necesario si el valor de RegistryKeyType es 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.

[out, optional] Disposition

Puntero de salida para el valor de disposición. Este parámetro apunta 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 lo necesita. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

NewSubKey devuelve STATUS_SUCCESS si la llamada se realizó correctamente al generar un puntero IRegistryKey válido a través del parámetro RegistrySubKey . De lo contrario, el método devuelve un código de error adecuado.

Comentarios

El NewSubKey método abre la clave del Registro especificada si ya existe o crea una nueva clave en el Registro si no existe. El método genera un puntero a la interfaz IRegistryKey de la nueva clave mediante el parámetro RegistrySubKey . El método también genera un valor de estado a través del parámetro Disposition opcional para indicar si la clave se abrió o creó.

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

El parámetro DesiredAccess es una máscara de control de acceso que especifica el tipo de control de acceso que el autor de la llamada debe tener en la subclave al acceder a ella a través del objeto RegistrySubKey . Esta máscara no debe confundirse con la ACL (lista de control de acceso) que controla el acceso de los usuarios a la subclave del Registro. Cuando la función PcNewRegistryKey o el método IPort::NewRegistryKey crea 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, cuando el NewSubKey método crea una nueva subclave del Registro, esa subclave simplemente hereda la ACL de su clave primaria. El NewSubKey método no proporciona ningún medio para especificar una ACL que difiere de la de la clave primaria.

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