ObjectOpenAuditAlarm

The ObjectOpenAuditAlarm function generates audit messages when a client application attempts to gain access to an object or to create a new one. Alarms are not supported in the current version of Windows NT.

BOOL ObjectOpenAuditAlarm(
  LPCTSTR SubsystemName,  // address of string for subsystem name
  LPVOID HandleId,        // address of handle identifier
  LPTSTR ObjectTypeName,  // address of string for object type
  LPTSTR ObjectName,      // address of string for object name
  PSECURITY_DESCRIPTOR pSecurityDescriptor,
                          // address of security descriptor
  HANDLE ClientToken,     // handle of client's access token
  DWORD DesiredAccess,    // mask for desired access rights
  DWORD GrantedAccess,    // mask for granted access rights
  PPRIVILEGE_SET Privileges,  // address of privileges
  BOOL ObjectCreation,    // flag for object creation
  BOOL AccessGranted,     // flag for results
  LPBOOL GenerateOnClose   // address of 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 of the object. If the access is denied, this parameter is ignored.

ObjectTypeName

Pointer to a null-terminated string specifying the type of object to which the client is requesting access. This string appears in any audit message that the function generates.

ObjectName

Pointer to a null-terminated string specifying the name of the object to which the client is requesting access. This string appears in any audit message that the function generates.

pSecurityDescriptor

Pointer to the SECURITY_DESCRIPTOR structure for the object being accessed.

ClientToken

Identifies an access token representing the client requesting the operation. This handle must be obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access.

DesiredAccess

Specifies the desired access mask. This mask must have been previously mapped by the MapGenericMask function to contain no generic access rights.

GrantedAccess

Specifies an access mask indicating which access rights are granted. This access mask is intended to be the same value set by one of the access-checking functions in its GrantedAccess parameter. Examples of access-checking functions include AccessCheckAndAuditAlarm and AccessCheck.

Privileges

Pointer to a PRIVILEGE_SET structure that specifies the set of privileges required for the access attempt. This parameter can be NULL.

ObjectCreation

Specifies a flag that determines whether the application creates a new object when access is granted. When this flag is TRUE, the application creates a new object; when it is FALSE, the application opens an existing object.

AccessGranted

Specifies a flag indicating whether access was granted or denied in a previous call to an access-checking function, such as AccessCheck. If access was granted, this flag is TRUE. If not, it is FALSE.

GenerateOnClose

Pointer to a flag set by the audit-generation routine when the function returns. This flag must be passed 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 ObjectOpenAuditAlarm function requires the calling application to have the SE_AUDIT_NAME privilege enabled. The test for this privilege is always performed against the primary token of the calling process, not the impersonation token of the thread. This allows the calling process to impersonate a client during the call.

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, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectDeleteAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, PRIVILEGE_SET, SECURITY_DESCRIPTOR