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
Points to a
null-terminated string specifying the subsystem calling this function, for
example, DEBUG or WIN32 .
HandleId
Points to a
unique 32-bit value representing the client s handle of the object. If the
access is denied, this parameter is ignored.
ObjectTypeName
Points to a
null-terminated string specifying the type of object to which the client is
requesting access. This string appears in the audit log for the object.
ObjectName
Points to a
null-terminated string specifying the name of the object to which the client
gained access or attempted to gain access. This string appears in the audit log
for the object.
pSecurityDescriptor
Points 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
Points 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
Points 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.
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.
See Also