/*
 * Copyright (c) Likewise Software.  All rights Reserved.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the license, or (at
 * your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
 * General Public License for more details.  You should have received a copy
 * of the GNU Lesser General Public License along with this program.  If
 * not, see <http://www.gnu.org/licenses/>.
 *
 * LIKEWISE SOFTWARE MAKES THIS SOFTWARE AVAILABLE UNDER OTHER LICENSING
 * TERMS AS WELL.  IF YOU HAVE ENTERED INTO A SEPARATE LICENSE AGREEMENT
 * WITH LIKEWISE SOFTWARE, THEN YOU MAY ELECT TO USE THE SOFTWARE UNDER THE
 * TERMS OF THAT SOFTWARE LICENSE AGREEMENT INSTEAD OF THE TERMS OF THE GNU
 * LESSER GENERAL PUBLIC LICENSE, NOTWITHSTANDING THE ABOVE NOTICE.  IF YOU
 * HAVE QUESTIONS, OR WISH TO REQUEST A COPY OF THE ALTERNATE LICENSING
 * TERMS OFFERED BY LIKEWISE SOFTWARE, PLEASE CONTACT LIKEWISE SOFTWARE AT
 * license@likewisesoftware.com
 */

/*
 * Module Name:
 *
 *        eventlog.h
 *
 * Abstract:
 *
 *        Low-level event logging API
 *
 * Authors: Brian Koropoff (bkoropoff@likewise.com)
 *
 */

#ifndef __LWBASE_EVENTLOG_H__
#define __LWBASE_EVENTLOG_H__

#include <lw/eventlog-types.h>

LW_BEGIN_EXTERN_C

/**
 * @file eventlog.h
 * @brief Eventlog APIs
 */

/**
 * @defgroup eventlog Event logging
 * @brief Structured event logging
 *
 * The RTL event logging API provides a generic mechanism for logging structured events
 * of interest to system administrators, such as hardware failures and file access
 * attempts.
 */

/*@{*/

/**
 * @brief Completion callback
 *
 * A function which is invoked when posting events has completed.
 *
 * @param[in] pContext a user context pointer
 * @param[in] Status the result of the post attempt
 */
typedef LW_VOID
(*LW_RTL_EVENTLOG_COMPLETE_CALLBACK)(
    LW_PVOID pContext,
    LW_NTSTATUS Status
    );

/**
 * @brief Post callback
 *
 * A function which is invoked to actually post events submitted
 * via #LwRtlEventlogPostEvents().
 */
typedef LW_NTSTATUS
(*LW_RTL_EVENTLOG_POST_CALLBACK)(
    LW_IN LW_ULONG RecordCount,
    LW_IN PLW_RTL_EVENTLOG_RECORD pRecords,
    LW_IN LW_OPTIONAL LW_RTL_EVENTLOG_COMPLETE_CALLBACK Complete,
    LW_IN LW_OPTIONAL LW_PVOID pContext
    );

/**
 * @brief Register callback
 *
 * A function which is invoked to actually register event type information
 * via #LwRtlEventlogRegisterEventType().
 */
typedef LW_NTSTATUS
(*LW_RTL_EVENTLOG_REGISTER_TYPE_CALLBACK)(
    LW_IN LW_PCGUID pGuid,
    LW_IN LW_RTL_EVENTLOG_TYPE_INFO_FORMAT Format,
    LW_IN PLW_RTL_EVENTLOG_TYPE_INFO pTypeInfo
    );

/**
 * @brief Set event callback functions
 *
 * Sets global callback functions which are invoked by
 * #LwRtlEventlogPostEvents() and #LwRtlEventlogRegisterEventType()
 * to handle structured events in an application-specific manner.
 *
 * @param[in] Post The event post function.
 * @param[in] Register The event type registration function.
 *
 * @retval LW_STATUS_SUCCESS Success.
 * @retval ... Error.
 */
LW_NTSTATUS
LwRtlEventlogSetCallbacks(
    LW_IN LW_RTL_EVENTLOG_POST_CALLBACK Post,
    LW_IN LW_RTL_EVENTLOG_REGISTER_TYPE_CALLBACK Register
    );

/**
 * @brief Post events
 *
 * Posts one or more event records.  If passed a completion callback,
 * this function may return #LW_STATUS_PENDING and invoke the callback
 * at a later time to indicate when the post attempt has completed.
 *
 * @param[in] RecordCount the number of records to submit
 * @param[in] pRecords the event records
 * @param[in] Complete an optional completion callback
 * @param[in] pContext an optional context pointer for the completion callback
 *
 * @retval LW_STATUS_SUCESS Success.
 * @retval LW_STATUS_PENDING The operation is pending, and the provided completion
 * callback will be invoked in an arbitrary thread when the post attempt has completed.
 * @retval ... Error.
 */
LW_NTSTATUS
LwRtlEventlogPostEvents(
    LW_IN LW_ULONG RecordCount,
    LW_IN PLW_RTL_EVENTLOG_RECORD pRecords,
    LW_IN LW_OPTIONAL LW_RTL_EVENTLOG_COMPLETE_CALLBACK Complete,
    LW_IN LW_OPTIONAL LW_PVOID pContext
    );

/**
 * @brief Register event type information
 *
 * Registers type information for events with the given type GUID.  Events
 * with associated type information will have their @a pData field treated
 * as structured data rather than as a flat data blob.
 *
 * @param[in] pGuid The event type GUID.
 * @param[in] Format The format of the type information.  If
 *                   #LW_RTL_EVENTLOG_TYPE_INFO_NONE, existing type
 *                   information for @a pGuid is unregistered.
 * @param[in] pTypeInfo The type information.  If @a Format is
 *                      #LW_RTL_EVENTLOG_TYPE_INFO_NONE, this must be
 *                      @a NULL.  If #LW_RTL_EVENTLOG_TYPE_INFO_LWMSG,
 *                      this must be an @a LWMsgTypeSpec*.
 *
 * @retval LW_STATUS_SUCCESS Success.
 * @retval ... Error.
 */
LW_NTSTATUS
LwRtlEventlogRegisterEventType(
    LW_IN LW_PCGUID pGuid,
    LW_IN LW_RTL_EVENTLOG_TYPE_INFO_FORMAT Format,
    LW_IN PLW_RTL_EVENTLOG_TYPE_INFO pTypeInfo
    );

/*@}*/

LW_END_EXTERN_C

#endif
