ObjectPrivilegeAuditAlarm

ObjectPrivilegeAuditAlarm

The ObjectPrivilegeAuditAlarm function generates audit messages as a result of a client's attempt to perform a privileged operation on a server application object using an already opened handle of that object. Alarms are not supported in the current version of Windows NT.

BOOL ObjectPrivilegeAuditAlarm(

LPCTSTR SubsystemName,	// pointer to string for subsystem name
LPVOID HandleId,	// pointer to handle identifier
HANDLE ClientToken,	// handle to client's access token
DWORD DesiredAccess,	// mask for desired access rights
PPRIVILEGE_SET Privileges,	// pointer to privileges
BOOL AccessGranted	// flag for results
);

Parameters

SubsystemName

Points to a null-terminated string specifying the name of the subsystem calling the function; for example, "DEBUG" or "WIN32".

HandleId

Points to a unique 32-bit value representing the client's handle to the object.

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 an access mask indicating the privileged access types being used or whose use is being attempted. The access mask can be mapped by the MapGenericMask function so it does not contain any generic access types.

Privileges

Points to a PRIVILEGE_SET structure specifying the set of privileges required for the requested operation. The information in this structure is supplied by a call to the PrivilegeCheck function. This parameter can be NULL.

AccessGranted

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

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 ObjectPrivilegeAuditAlarm function requires the calling process to have SE_AUDIT_NAME privilege. 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.

The ObjectPrivilegeAuditAlarm function can send many messages to port objects. This can result in a significant delay before the function returns. The design of applications calling ObjectPrivilegeAuditAlarm can take this potential delay into account. For example, this consideration may affect the design of an application using mutexes to lock structures.