Función TreeSetNamedSecurityInfoA (aclapi.h)

  • Artículo

Esta versión de esta función no se admite. Se admite la versión de caracteres anchos de esta función, TreeSetNamedSecurityInfoW.

Sintaxis

DWORD TreeSetNamedSecurityInfoA(
  [in]           LPSTR                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]           DWORD                dwAction,
  [in]           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, consulte 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 establecer. 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 del propietario, este parámetro puede ser NULL.

[in, optional] pGroup

Puntero a una estructura de 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] dwAction

Especifica el comportamiento de esta función. Debe establecerse en uno de los valores siguientes, definidos en AccCtrl.h.

Valor Significado
TREE_SEC_INFO_SET
0x00000001
 La información de seguridad se establece en el objeto especificado por el parámetro pObjectName y el árbol de objetos secundarios de ese objeto. Si las ACL se especifican en los parámetros pDacl o pSacl , los descriptores de seguridad se asocian al objeto . Los descriptores de seguridad se propagan al árbol de objetos secundarios en función de sus propiedades de herencia.
TREE_SEC_INFO_RESET
0x00000002
 La información de seguridad se restablece en el objeto especificado por el parámetro pObjectName y el árbol de objetos secundarios de ese objeto. Cualquier información de seguridad existente se quita de todos los objetos del árbol.

Si algún objeto del árbol no concede los permisos adecuados al autor de la llamada para modificar el descriptor de seguridad en el objeto, se omite la propagación de información de seguridad en ese nodo concreto del árbol y sus objetos. La operación continúa en el resto del árbol bajo el objeto especificado por el parámetro pObjectName .
TREE_SEC_INFO_RESET_KEEP_EXPLICIT
0x00000003
 La información de seguridad se restablece en el objeto especificado por el parámetro pObjectName y el árbol de objetos secundarios de ese objeto. Cualquier información de seguridad heredada existente se quita de todos los objetos del árbol. La información de seguridad que se estableció explícitamente en los objetos del árbol no cambia.

Si algún objeto del árbol no concede los permisos adecuados al autor de la llamada para modificar el descriptor de seguridad en el objeto, se omite la propagación de información de seguridad en ese nodo concreto del árbol y sus objetos. La operación continúa en el resto del árbol bajo el objeto especificado por el parámetro pObjectName .

[in] fnProgress

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

#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

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 sobre el progreso y el error cuando se procesan los nodos. El autor de la llamada especifica la función de progreso en fnProgress y, durante la operación de árbol, TreeSetNamedSecurityInfo 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 la configuración 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 ejecuta 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 la configuración 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 de propietario, grupo, DACL y SACL solicitados, no se realiza ninguna de las actualizaciones.

Esta función proporciona la misma funcionalidad que la función SetNamedSecurityInfo cuando el valor del parámetro dwAction se establece en TREE_SEC_INFO_SET, el valor del parámetro ProgressInvokeSetting se establece en ProgressInvokePrePostError y la función a la que apunta el parámetro fnProgress establece el valor de su parámetro pInvokeSetting en ProgressInvokePrePostError.

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

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

Nota

El encabezado aclapi.h define TreeSetNamedSecurityInfo 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en 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 Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado aclapi.h
Library Advapi32.lib
Archivo DLL Advapi32.dll