Función AddAce (securitybaseapi.h)

Artículo
03/01/2024

La función AddAce agrega una o varias entradas de control de acceso (ACE) a una lista de control de acceso (ACL) especificada.

Sintaxis

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Parámetros

[in, out] pAcl

Puntero a una ACL. Esta función agrega una ACE a esta ACL.

[in] dwAceRevision

Especifica el nivel de revisión de la ACL que se va a modificar.

Este valor puede ser ACL_REVISION o ACL_REVISION_DS. Use ACL_REVISION_DS si la ACL contiene ACE específicas del objeto. Este valor debe ser compatible con el campo AceType de todas las ACE en pAceList. De lo contrario, se producirá un error en la función y se establecerá el último error en ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Especifica la posición de la lista de ACE de la ACL en la que se van a agregar nuevos ACE. Un valor de cero inserta los ACE al principio de la lista. Un valor de MAXDWORD anexa las ACE al final de la lista.

[in] pAceList

Puntero a una lista de uno o varios ACL que se van a agregar a la ACL especificada. Las ACE de la lista deben almacenarse de forma contigua.

[in] nAceListLength

Especifica el tamaño, en bytes, del búfer de entrada al que apunta el parámetro pAceList .

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError. A continuación se muestran los posibles valores de error.

Código devuelto	Descripción
ERROR_INSUFFICIENT_BUFFER	La nueva ACE no encaja en la ACL. Se requiere un búfer de ACL mayor.
ERROR_INVALID_PARAMETER	La ACL especificada no tiene el formato correcto.
ERROR_SUCCESS	La ACE se agregó correctamente.

Comentarios

Las aplicaciones usan con frecuencia las funciones FindFirstFreeAce y GetAce cuando se usa la función AddAce para manipular una ACL. Además, la estructura de ACL_SIZE_INFORMATION recuperada por la función GetAclInformation contiene el tamaño de la ACL y el número de ACE que contiene.

Ejemplos

Para obtener un ejemplo que usa esta función, vea Iniciar un proceso de cliente interactivo.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll