Función TreeSetNamedSecurityInfoA (aclapi.h)

Artículo
11/20/2024

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 un cadena terminada en nullque 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 establecer. Este parámetro puede ser una combinación de las marcas de bits SECURITY_INFORMATION.

[in, optional] pOwner

Puntero a una estructura SID que identifica al propietario del objeto. El SID debe ser uno que se pueda asignar como 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 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 lista de control de acceso estructura (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 de 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 la SACL, este parámetro puede ser NULL.

[in] dwAction

Especifica el comportamiento de esta función. Debe establecerse en uno de los siguientes valores, 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 se especifican ACL 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 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 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 usada para realizar un seguimiento del progreso de la función TreeSetNamedSecurityInfo. El prototipo de la función progress 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 de progreso y 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 progress.

[in, optional] Args

Puntero a un VOID para los argumentos de función de progreso especificados por el llamador.

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.

Observaciones

Esta función no admite establecer un NULL propietario, grupo, DACL o SACL.

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 ProgressInvokePrePostErrory la función a la que apunta el parámetro fnProgress establece el valor de su parámetro pInvokeSetting para 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 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2008 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	aclapi.h
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll

Compartir a través de