ObjectOpenAuditAlarm

	BOOL ObjectOpenAuditAlarm(SubsystemName, HandleId, ObjectTypeName, ObjectName, pSecurityDescriptor, ClientToken, DesiredAccess, GrantedAccess, Privileges, ObjectCreation, AccessGranted, GenerateOnClose)
	LPTSTR SubsystemName;
	LPVOID HandleId;
	LPTSTR ObjectTypeName;
	LPTSTR ObjectName;
	PSECURITY_DESCRIPTOR pSecurityDescriptor;
	HANDLE ClientToken;
	DWORD DesiredAccess;
	DWORD GrantedAccess;
	PPRIVILEGE_SET Privileges;
	BOOL ObjectCreation;
	BOOL AccessGranted;
	LPBOOL GenerateOnClose;

The ObjectOpenAuditAlarm function generates audit and alarm messages when an attempt is made to access an existing server application object or create a new one.

Parameters

SubsystemName

Pointer to a name string that identifies the subsystem calling this function.

HandleId

A unique value representing the client's handle to the object. If the access is denied this parameter is ignored.

ObjectTypeName

Pointer to a string that is the name of the type of object being accessed.

ObjectName

Pointer to a string that is the name of the object the client accessed or attempted to access.

pSecurityDescriptor

Pointer to the security descriptor of the object being accessed.

ClientToken

Handle to a token object representing the client that requested the operation. This handle must be obtained by opening the token of a thread that is impersonating the client. The token must be open for TOKEN_QUERY access.

DesiredAccess

The desired access mask. This mask must have been previously mapped to contain no generic accesses.

GrantedAccess

Pointer to a variable that the function will fill with an access mask indicating which accesses were granted as a result of the open operation. This access mask should be the same value set by one of the AccessCheckxxx functions into the variable pointed to by its GrantedAccess parameter

Privileges

Optional pointer to a PRIVILEGE_SET structure that gives the set of privileges required for the access attempt.

The PRIVILEGE_SET data structure has the following form:

typedef struct _PRIVILEGE_SET { /* ps */

DWORD PrivilegeCount;

DWORD Control;

LUID_AND_ATTRIBUTES Privilege[ANYSIZE_ARRAY];

} PRIVILEGE_SET;

ObjectCreation

Boolean flag that specifies, if TRUE, that the function will create a new object if access is granted. A value of FALSE specifies that the function will open an existing object if access is granted.

AccessGranted

Pointer to a Boolean value that the function sets to TRUE if the access was granted, FALSE if it was not.

GenerateOnClose

Pointer to a Boolean variable that the audit generation routine sets. This Boolean must be passed to ObjectCloseAuditAlarm when the object handle is closed.

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

Invoking the ObjectOpenAuditAlarm function may result in several messages being generated and sent to Port objects. This may result in a significant latency before returning. The design of routines that call ObjectOpenAuditAlarm must take this potential latency into account. This may have an impact on the approach taken for data structure mutex locking, for example.

The ObjectOpenAuditAlarm function requires the caller to have SeSecurityPrivilege privilege. The test for this privilege is always against the primary token of the calling process, not the impersonation token of the thread.