AccessCheckAndAuditAlarm

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 supported in the current version of Windows NT.

BOOL AccessCheckAndAuditAlarm(
  LPCTSTR SubsystemName,     // subsystem name
  LPVOID HandleId,           // object's handle identifier
  LPTSTR ObjectTypeName,     // type of object
  LPTSTR ObjectName,         // name of object
  PSECURITY_DESCRIPTOR SecurityDescriptor,
                             // address of security descriptor
  DWORD DesiredAccess,       // mask for requested access rights
  PGENERIC_MAPPING GenericMapping,
                             // address of GENERIC_MAPPING
  BOOL ObjectCreation,       // flag is TRUE if creating an object
  LPDWORD GrantedAccess,     // retrieves mask of granted rights
  LPBOOL AccessStatus        // retrieves results of access check
  LPBOOL pfGenerateOnClose   // retrieves flag for audit generation
);
 

Parameters

SubsystemName

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

Pointer to a unique 32-bit value representing the client's handle to the object. If the access is denied, the system ignores this value.

ObjectTypeName

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

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

Pointer to the SECURITY_DESCRIPTOR structure against which access is checked.

DesiredAccess

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

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

ObjectCreation

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

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

AccessStatus

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 returns TRUE. Otherwise, AccessStatus returns FALSE.

pfGenerateOnClose

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 Values

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

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.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, AccessCheck, GENERIC_MAPPING, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, SECURITY_DESCRIPTOR