Función TreeResetNamedSecurityInfoW (aclapi.h)

  • Artículo

La función TreeResetNamedSecurityInfo restablece la información de seguridad especificada en el descriptor de seguridad de un árbol de objetos especificado. Esta función permite que una lista de control de acceso discrecional (DACL) especificada o cualquier elemento de la lista de control de acceso del sistema (SACL) se propague a lo largo de todo un árbol. Esta función admite una función de devolución de llamada para realizar un seguimiento del progreso de la operación de árbol.

Sintaxis

DWORD TreeResetNamedSecurityInfoW(
  [in]           LPWSTR               pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 pOwner,
  [in, optional] PSID                 pGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl,
  [in]           BOOL                 KeepExplicit,
  [in, optional] FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

Parámetros

[in] pObjectName

Puntero a una cadena terminada en null que especifica el nombre del objeto de nodo raíz para los objetos que van a recibir información de seguridad actualizada. Los objetos admitidos son claves del Registro y objetos de archivo. Para obtener descripciones de los formatos de cadena de los distintos tipos de objeto, vea SE_OBJECT_TYPE.

[in] ObjectType

Valor de la enumeración SE_OBJECT_TYPE que indica el tipo de objeto denominado por el parámetro pObjectName . Los valores admitidos son SE_REGISTRY_KEY y SE_FILE_OBJECT, para las claves del Registro y los objetos de archivo, respectivamente.

[in] SecurityInfo

Conjunto de marcas de bits que indican el tipo de información de seguridad que se va a restablecer. Este parámetro puede ser una combinación de las marcas de bits de SECURITY_INFORMATION .

[in, optional] pOwner

Puntero a una estructura de SID que identifica al propietario del objeto. El SID debe ser uno que se pueda asignar como el SID propietario de un descriptor de seguridad. El parámetro SecurityInfo debe incluir la marca OWNER_SECURITY_INFORMATION. Para establecer el propietario, el autor de la llamada debe tener WRITE_OWNER acceso a cada objeto, incluido el objeto raíz. Si no establece el SID de propietario, este parámetro puede ser NULL.

[in, optional] pGroup

Puntero a una estructura SID que identifica el grupo principal del objeto. El parámetro SecurityInfo debe incluir la marca GROUP_SECURITY_INFORMATION. Para establecer el grupo, el autor de la llamada debe tener WRITE_OWNER acceso a cada objeto, incluido el objeto raíz. Si no establece el SID del grupo principal, este parámetro puede ser NULL.

[in, optional] pDacl

Puntero a una estructura de lista de control de acceso (ACL) que representa la nueva DACL para los objetos que se restablecen. El parámetro SecurityInfo debe incluir la marca DACL_SECURITY_INFORMATION. El autor de la llamada debe tener READ_CONTROL y WRITE_DAC acceso a cada objeto, incluido el objeto raíz. Si no establece la DACL, este parámetro puede ser NULL.

[in, optional] pSacl

Puntero a una estructura de ACL que representa la nueva SACL para los objetos que se restablecen. El parámetro SecurityInfo debe incluir cualquiera de las marcas siguientes: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION o BACKUP_SECURITY_INFORMATION. Si establece SACL_SECURITY_INFORMATION o SCOPE_SECURITY_INFORMATION, el autor de la llamada debe tener habilitado el privilegio SE_SECURITY_NAME. Si no establece sacl, este parámetro puede ser NULL.

[in] KeepExplicit

Valor booleano que define si las ACE definidas explícitamente se mantienen o eliminan para el subárbol. Si KeepExplicit es TRUE, las ACE definidas explícitamente se conservan para cada DACL de subárbol y SACL, y las ACE heredadas se reemplazan por las ACE heredadas de pDacl y pSacl. Si KeepExplicit es FALSE, las ACE definidas explícitamente para cada DACL de subárbol y SACL se eliminan antes de que las ACE heredadas se reemplacen por las ACE heredadas de pDacl y pSacl.

[in, optional] fnProgress

Puntero a la función utilizada para realizar un seguimiento del progreso de la función TreeResetNamedSecurityInfo . El prototipo de la función de progreso es:

#include <windows.h>
#include <Aclapi.h>

typedef VOID (*FN_PROGRESS) (
  IN LPWSTR pObjectName,              // Name of object just processed
  IN DWORD Status,                    // Status of operation on object
  IN OUT PPROG_INVOKE_SETTING pInvokeSetting, // When to set
  IN PVOID Args,                      // Caller specific data
  IN BOOL SecuritySet                 // Whether security was set
);

La función progress proporciona al autor de la llamada información de progreso y error cuando se procesan los nodos. El llamador especifica la función progress en fnProgress y, durante la operación de árbol, TreeResetNamedSecurityInfo pasa el nombre del último objeto procesado, el estado de error de esa operación y el valor de PROG_INVOKE_SETTING actual. El autor de la llamada puede cambiar el valor de PROG_INVOKE_SETTING mediante pInvokeSetting.

Si no se va a usar ninguna función de progreso, establezca este parámetro en NULL.

[in] ProgressInvokeSetting

Valor de la enumeración PROG_INVOKE_SETTING que especifica el valor inicial de la función de progreso.

[in, optional] Args

Puntero a void para los argumentos de función de progreso especificados por el autor de la llamada.

Valor devuelto

Si la función se realiza correctamente, la función devuelve ERROR_SUCCESS.

Si se produce un error en la función, devuelve un código de error definido en WinError.h.

Comentarios

Esta función no admite el establecimiento de un propietario, grupo, DACL o SACL NULL .

Si el autor de la llamada no contiene los privilegios y permisos adecuados para admitir las actualizaciones solicitadas de propietario, grupo, DACL y SACL, no se realiza ninguna de las actualizaciones.

Esta función es similar a la función TreeSetNamedSecurityInfo :

  • Si el parámetro KeepExplicit de TreeResetNamedSecurityInfo se establece en TRUE, la función es equivalente a TreeSetNamedSecurityInfo con el parámetro dwAction establecido en TREE_SEC_INFO_RESET_KEEP_EXPLICIT.
  • Si el parámetro KeepExplicit de TreeResetNamedSecurityInfo se establece en FALSE, la función es equivalente a TreeSetNamedSecurityInfo con el parámetro dwAction establecido en TREE_SEC_INFO_RESET.

Nota

El encabezado aclapi.h define TreeResetNamedSecurityInfo como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado aclapi.h
Library Advapi32.lib
Archivo DLL Advapi32.dll