Función GetNamedSecurityInfoA (aclapi.h)

Artículo
02/26/2024

La función GetNamedSecurityInfo recupera una copia del descriptor de seguridad de un objeto especificado por nombre.

Sintaxis

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parámetros

[in] pObjectName

Puntero a una cadena terminada en null que especifica el nombre del objeto desde el que se va a recuperar la información de seguridad. Para obtener descripciones de los formatos de cadena de los distintos tipos de objeto, consulte SE_OBJECT_TYPE.

[in] ObjectType

Especifica un valor de la enumeración SE_OBJECT_TYPE que indica el tipo de objeto denominado por el parámetro pObjectName .

[in] SecurityInfo

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

[out, optional] ppsidOwner

Puntero a una variable que recibe un puntero al SID propietario en el descriptor de seguridad devuelto en ppSecurityDescriptor o NULL si el descriptor de seguridad no tiene ningún SID de propietario. El puntero devuelto solo es válido si establece la marca de OWNER_SECURITY_INFORMATION. Además, este parámetro puede ser NULL si no necesita el SID propietario.

[out, optional] ppsidGroup

Puntero a una variable que recibe un puntero al SID del grupo principal en el descriptor de seguridad devuelto o NULL si el descriptor de seguridad no tiene ningún SID de grupo. El puntero devuelto solo es válido si establece la marca GROUP_SECURITY_INFORMATION. Además, este parámetro puede ser NULL si no necesita el SID de grupo.

[out, optional] ppDacl

Puntero a una variable que recibe un puntero a la DACL en el descriptor de seguridad devuelto o NULL si el descriptor de seguridad no tiene NINGUNA DACL. El puntero devuelto solo es válido si establece la marca DACL_SECURITY_INFORMATION. Además, este parámetro puede ser NULL si no necesita la DACL.

[out, optional] ppSacl

Puntero a una variable que recibe un puntero al SACL en el descriptor de seguridad devuelto o NULL si el descriptor de seguridad no tiene SACL. El puntero devuelto solo es válido si establece la marca de SACL_SECURITY_INFORMATION. Además, este parámetro puede ser NULL si no necesita sacl.

[out, optional] ppSecurityDescriptor

Puntero a una variable que recibe un puntero al descriptor de seguridad del objeto. Cuando haya terminado de usar el puntero, libere el búfer devuelto llamando a la función LocalFree .

Este parámetro es necesario si alguno de los parámetros ppsidOwner, ppsidGroup, ppDacl o ppSacl no es NULL.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es un código de error distinto de cero definido en WinError.h.

Comentarios

Si alguno de los parámetros ppsidOwner, ppsidGroup, ppDacl o ppSacl no es NULL y el parámetro SecurityInfo especifica que se recuperarán del objeto, esos parámetros apuntarán a los parámetros correspondientes del descriptor de seguridad devueltos en ppSecurityDescriptor. Si el descriptor de seguridad no contiene la información solicitada, el parámetro correspondiente se establecerá en NULL.

Para leer el propietario, el grupo o la DACL del descriptor de seguridad del objeto, la DACL del objeto debe conceder READ_CONTROL acceso al autor de la llamada o el autor de la llamada debe ser el propietario del objeto.

Para leer la lista de control de acceso del sistema del objeto, el privilegio SE_SECURITY_NAME debe estar habilitado para el proceso de llamada. Para obtener información sobre las implicaciones de seguridad de habilitar privilegios, consulte Ejecución con privilegios especiales.

Puede usar la función GetNamedSecurityInfo con los siguientes tipos de objetos:

Archivos o directorios locales o remotos en un sistema de archivos NTFS
Impresoras locales o remotas
Servicios locales o remotos de Windows
Recursos compartidos de red
Claves del Registro
Semáforos, eventos, exclusión mutua y temporizadores que pueden esperar
Objetos de asignación de archivos
Objetos de servicio de directorio

Esta función no controla las condiciones de carrera. Si el subproceso llama a esta función en el momento aproximado en que otro subproceso cambia el descriptor de seguridad del objeto, esta función podría producir un error.

Esta función transfiere información en texto no cifrado. La información transferida por esta función se firma a menos que se haya desactivado la firma para el sistema, pero no se realiza ningún cifrado.

Para obtener más información sobre cómo controlar el acceso a objetos a través de cuentas de usuario, cuentas de grupo o sesiones de inicio de sesión, vea Cómo controlan el acceso de DACLs a un objeto.

Ejemplos

Para ver un ejemplo que usa GetNamedSecurityInfo, vea Modificación de las ACL de un objeto.

Nota

El encabezado aclapi.h define GetNamedSecurityInfo 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 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	aclapi.h
Library	Advapi32.lib
Archivo DLL	Advapi32.dll