Export (0) Print
Expand All
Expand Minimize

AccessCheckAndAuditAlarm function

The AccessCheckAndAuditAlarm function determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling thread. If the security descriptor has a SACL with ACEs that apply to the client, the function generates any necessary audit messages in the security event log.

Alarms are not currently supported.

Syntax


BOOL WINAPI AccessCheckAndAuditAlarm(
  _In_      LPCTSTR SubsystemName,
  _In_opt_  LPVOID HandleId,
  _In_      LPTSTR ObjectTypeName,
  _In_opt_  LPTSTR ObjectName,
  _In_      PSECURITY_DESCRIPTOR SecurityDescriptor,
  _In_      DWORD DesiredAccess,
  _In_      PGENERIC_MAPPING GenericMapping,
  _In_      BOOL ObjectCreation,
  _Out_     LPDWORD GrantedAccess,
  _Out_     LPBOOL AccessStatus,
  _Out_     LPBOOL pfGenerateOnClose
);

Parameters

SubsystemName [in]

A pointer to a null-terminated string specifying the name of the subsystem calling the function. This string appears in any audit message that the function generates.

HandleId [in, optional]

A pointer to a unique value representing the client's handle to the object. If the access is denied, the system ignores this value.

ObjectTypeName [in]

A pointer to a null-terminated string specifying the type of object being created or accessed. This string appears in any audit message that the function generates.

ObjectName [in, optional]

A pointer to a null-terminated string specifying the name of the object being created or accessed. This string appears in any audit message that the function generates.

SecurityDescriptor [in]

A pointer to the SECURITY_DESCRIPTOR structure against which access is checked.

DesiredAccess [in]

Access mask that specifies the access rights to check. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.

If this parameter is MAXIMUM_ALLOWED, the function sets the GrantedAccess access mask to indicate the maximum access rights the security descriptor allows the client.

GenericMapping [in]

A pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked.

ObjectCreation [in]

Specifies a flag that determines whether the calling application will create a new object when access is granted. A value of TRUE indicates the application will create a new object. A value of FALSE indicates the application will open an existing object.

GrantedAccess [out]

A pointer to an access mask that receives the granted access rights. If AccessStatus is set to FALSE, the function sets the access mask to zero. If the function fails, it does not set the access mask.

AccessStatus [out]

A pointer to a variable that receives the results of the access check. If the security descriptor allows the requested access rights to the client, AccessStatus is set to TRUE. Otherwise, AccessStatus is set to FALSE.

pfGenerateOnClose [out]

A pointer to a flag set by the audit-generation routine when the function returns. Pass this flag to the ObjectCloseAuditAlarm function when the object handle is closed.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

For more information, see the How AccessCheck Works overview.

The AccessCheckAndAuditAlarm function requires the calling process to have the SE_AUDIT_NAME privilege enabled. The test for this privilege is performed against the primary token of the calling process, not the impersonation token of the thread.

The AccessCheckAndAuditAlarm function fails if the calling thread is not impersonating a client.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

AccessCheckAndAuditAlarmW (Unicode) and AccessCheckAndAuditAlarmA (ANSI)

See also

Client/Server Access Control
Client/Server Access Control Functions
How AccessCheck Works
AccessCheck
GENERIC_MAPPING
MakeAbsoluteSD
MapGenericMask
ObjectCloseAuditAlarm
ObjectOpenAuditAlarm
ObjectPrivilegeAuditAlarm
PrivilegeCheck
PrivilegedServiceAuditAlarm
SECURITY_DESCRIPTOR

 

 

Community Additions

ADD
Show:
© 2014 Microsoft