AuthzReportSecurityEvent function

The AuthzReportSecurityEvent function generates a security audit for a registered security event source.

Auditing for the object access event category must be enabled for the AuthzReportSecurityEvent function to generate a security audit. The available audit types are defined in the AUDIT_PARAM_TYPE enumeration.

Syntax

BOOL WINAPI AuthzReportSecurityEvent(
  _In_     DWORD                                dwFlags,
  _Inout_  AUTHZ_SECURITY_EVENT_PROVIDER_HANDLE hEventProvider,
  _In_     DWORD                                dwAuditId,
  _In_opt_ PSID                                 pUserSid,
  _In_     DWORD                                dwCount,
  _In_                                          ...
);

Parameters

dwFlags [in]

Flags that specify the type of audit generated. The following table shows the possible values.

Value	Meaning
APF_AuditFailure 0x00000000	Failure audits are generated.
APF_AuditSuccess 0x00000001	Success audits are generated.

 

hEventProvider [in, out]

A handle to the registered security event source to use for the audit.

dwAuditId [in]

The identifier of the audit.

pUserSid [in, optional]

A pointer to the security identifier (SID) that will be listed as the source of the audit in the event log.

dwCount [in]

The number of AuditParamFlag type/value pairs that appear in the variable arguments section that follows this parameter.

... [in]

A list of AuditParamFlag type/value pairs that provide additional information about the event.

Return value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE. For extended error information, call GetLastError.

Examples

The following example shows the use of the AuthzReportSecurityEvent function to generate an audit in the security event log.

This example assumes that an event source with the name "AUDIT_SOURCE_NAME" was registered by a previous call to the AuthzInstallSecurityEventSource function, and that the caller has the SeAuditPrivilege privilege to call the AuthzRegisterSecurityEventSource function. For information about privilege constants, see Authorization Constants.

// Declare and initialize variables.

BOOL bResult = TRUE;
DWORD dwError;
AUTHZ_SECURITY_EVENT_PROVIDER_HANDLE hEventProvider = NULL;
  
// Register the audit provider.


bResult = AuthzRegisterSecurityEventSource(
          0,
          AUDIT_SOURCE_NAME,
          &hEventProvider);

if (!bResult)
{
    dwError = GetLastError();

    wprintf(
    L"AuthzRegisterSecurityEventSource %d\n", 
    dwError);

    goto Cleanup;
}

wprintf(L"Registered provider.\n");

// Generate the audit. 

bResult = AuthzReportSecurityEvent(
          APF_AuditSuccess,
          hEventProvider,
          AUDITID_BIRTHDAY,
          NULL,
          3,
          APT_String, L"Jay Hamlin",
          APT_String, L"March 21, 1960",
          APT_Ulong,  45);

if (!bResult)
{
    dwError = GetLastError();

    wprintf(
    L"AuthzReportSecurityEvent %d\n", 
    dwError);

    goto Cleanup;
}

wprintf(L"Generated audit.\n");

Cleanup:

if (hEventProvider)
{
    AuthzUnregisterSecurityEventSource(
    0,
    &hEventProvider);
}

Requirements

See also

AuthzRegisterSecurityEventSource

AuthzReportSecurityEventFromParams