weave/src/lib/profiles/data-management/Current/EventLogging.h

/*
 *
 *    Copyright (c) 2015-2017 Nest Labs, Inc.
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

/**
 *  @file
 *
 *  @brief
 *    API definitions for Weave Event Logging
 *
 *  This file contains the definitions for the Weave Event Logging.
 *  The file defines the API for configuring and controlling the
 *  logging subsystem as well as the API for emitting the individual
 *  log entries.
*/
#ifndef _WEAVE_DATA_MANAGEMENT_EVENT_LOGGING_CURRENT_H
#define _WEAVE_DATA_MANAGEMENT_EVENT_LOGGING_CURRENT_H

#include <Weave/Profiles/data-management/Current/WdmManagedNamespace.h>
#include <Weave/Profiles/data-management/EventLoggingTags.h>
#include <Weave/Profiles/data-management/EventLoggingTypes.h>

namespace nl {
namespace Weave {
namespace Profiles {
namespace WeaveMakeManagedNamespaceIdentifier(DataManagement, kWeaveManagedNamespaceDesignation_Current) {



/**
 * @brief
 *   Log an event from a pre-serialized form.
 *
 * The function logs an event represented as a ::TLVReader.  This
 * implies that the event data representation is already serialized in
 * the storage underlying the ::TLVReader.  The ::TLVReader is expected to
 * contain at least a single data element, that element must be a
 * structure. The first element read out of the reader is treated as
 * event data and stored in the event log.  The event data MUST
 * contain context tags to be interpreted within the schema identified
 * by inProfileID and inEventType. The tag of the first element will
 * be ignored; the event logging system will replace it with the
 * eventData tag.
 *
 * The event is logged if its inImportance exceeds the logging
 * threshold specified in the LoggingConfiguration.  If the event's
 * importance does not meet the current threshold, it is dropped and
 * the function returns a `0` as the resulting event ID.
 *
 * This variant of the invocation implicitly specifies all the default
 * event options:
 * - the event is timestamped with the current time at the point of the call,
 * - the event is marked as relating to the device that is making the call,
 * - the event is standalone, not relating to any other events,
 * - the event is marked as non-urgent,
 *
 * @param[in] inSchema     Schema defining importance, profile ID, and
 *                         structure type of this event.
 *
 * @param[in] inData       The TLV reader containing the event data as the
 *                         first element.
 *
 * @return event_id_t      The event ID if the event was written to the
 *                         log, 0 otherwise.
 */
event_id_t LogEvent(const EventSchema &inSchema, nl::Weave::TLV::TLVReader &inData);

/**
 * @brief
 *   Log an event from a pre-serialized form, with additional options.
 *
 * The function logs an event represented as a ::TLVReader.  This
 * implies that the event data representation is already serialized in
 * the storage underlying the ::TLVReader.  The ::TLVReader is expected to
 * contain at least a single data element, that element must be a
 * structure. The first element read out of the reader is treated as
 * event data and stored in the event log.  The event data MUST
 * contain context tags to be interpreted within the schema identified
 * by inProfileID and inEventType. The tag of the first element will
 * be ignored; the event logging system will replace it with the
 * eventData tag.
 *
 * The event is logged if its inImportance exceeds the logging
 * threshold specified in the LoggingConfiguration.  If the event's
 * importance does not meet the current threshold, it is dropped and
 * the function returns a `0` as the resulting event ID.
 *
 * This variant of the invocation permits the caller to set any
 * combination of `EventOptions`:
 * - timestamp, when 0 defaults to the current time at the point of
 *   the call,
 * - "root" section of the event source (event source and trait ID);
 *   if NULL, it defaults to the current device. the event is marked as
 *   relating to the device that is making the call,
 * - a related event ID for grouping event IDs; when the related event
 *   ID is 0, the event is marked as not relating to any other events,
 * - urgency; by default non-urgent.
 *
 * @param[in] inSchema     Schema defining importance, profile ID, and
 *                         structure type of this event.
 *
 * @param[in] inData       The TLV reader containing the event data as the
 *                         first element. Must not be NULL
 *
 * @param[in] inOptions    The options for the event metadata. May be NULL.
 *
 * @return event_id_t      The event ID if the event was written to the
 *                         log, 0 otherwise.
 */
event_id_t LogEvent(const EventSchema &inSchema, nl::Weave::TLV::TLVReader &inData, const EventOptions *inOptions);

/**
 * @brief
 *   Log an event via a callback.
 *
 * The function logs an event represented as an ::EventWriterFunct and
 * an app-specific `appData` context.  The function writes the event
 * metadata and calls the `inEventWriter` with an ::TLVWriter
 * reference and `inAppData` context so that the user code can emit
 * the event data directly into the event log.  This form of event
 * logging minimizes memory consumption, as event data is serialized
 * directly into the target buffer.  The event data MUST contain
 * context tags to be interpreted within the schema identified by
 * `inProfileID` and `inEventType`. The tag of the first element will be
 * ignored; the event logging system will replace it with the
 * eventData tag.
 *
 * The event is logged if its inImportance exceeds the logging
 * threshold specified in the LoggingConfiguration.  If the event's
 * importance does not meet the current threshold, it is dropped and
 * the function returns a `0` as the resulting event ID.
 *
 * This variant of the invocation implicitly specifies all the default
 * event options:
 * - the event is timestamped with the current time at the point of the call,
 * - the event is marked as relating to the device that is making the call,
 * - the event is standalone, not relating to any other events,
 * - the event is marked as non-urgent,
 *
 * @param[in] inSchema     Schema defining importance, profile ID, and
 *                         structure type of this event.
 *
 * @param[in] inEventWriter The callback to invoke to actually
 *                         serialize the event data
 *
 * @param[in] inAppData    Application context for the callback.
 *
 * @return event_id_t      The event ID if the event was written to the
 *                         log, 0 otherwise.
 */
event_id_t LogEvent(const EventSchema &inSchema, EventWriterFunct inEventWriter, void *inAppData);

/**
 * @brief
 *   Log an event via a callback, with options.
 *
 * The function logs an event represented as an ::EventWriterFunct and
 * an app-specific `appData` context.  The function writes the event
 * metadata and calls the `inEventWriter` with an ::TLVWriter
 * reference and `inAppData` context so that the user code can emit
 * the event data directly into the event log.  This form of event
 * logging minimizes memory consumption, as event data is serialized
 * directly into the target buffer.  The event data MUST contain
 * context tags to be interpreted within the schema identified by
 * `inProfileID` and `inEventType`. The tag of the first element will be
 * ignored; the event logging system will replace it with the
 * eventData tag.
 *
 * The event is logged if its inImportance exceeds the logging
 * threshold specified in the LoggingConfiguration.  If the event's
 * importance does not meet the current threshold, it is dropped and
 * the function returns a `0` as the resulting event ID.
 *
 * This variant of the invocation permits the caller to set any
 * combination of `EventOptions`:
 * - timestamp, when 0 defaults to the current time at the point of
 *   the call,
 * - "root" section of the event source (event source and trait ID);
 *   if NULL, it defaults to the current device. the event is marked as
 *   relating to the device that is making the call,
 * - a related event ID for grouping event IDs; when the related event
 *   ID is 0, the event is marked as not relating to any other events,
 * - urgency; by default non-urgent.
 *
 * @param[in] inSchema     Schema defining importance, profile ID, and
 *                         structure type of this event.
 *
 * @param[in] inEventWriter The callback to invoke to actually
 *                         serialize the event data
 *
 * @param[in] inAppData    Application context for the callback.
 *
 * @param[in] inOptions    The options for the event metadata. May be NULL.
 *
 * @return event_id_t      The event ID if the event was written to the
 *                         log, 0 otherwise.
 */
event_id_t LogEvent(const EventSchema &inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions);


/**
 * @brief
 *   LogFreeform emits a freeform string to the default event stream.
 *
 * The string will be encapsulated in an debug event structure,
 * structurally identical to other logged strings.  The event profile
 * ID will be that of a Nest Debug event, and the event type will be
 * `kNestDebug_StringLogEntryEvent`.
 *
 * @param inImportance[in]  Importance of the log entry; if the importance
 *                          falls below the current importance, the event is
 *                          not actually logged
 *
 * @param inFormat[in]      `printf`-compliant format string, followed by
 *                          arguments to be formatted
 *
 * @return event_id_t      The event ID if the event was written to the
 *                         log, 0 otherwise.
 *
 */

event_id_t LogFreeform(ImportanceType inImportance, const char * inFormat, ...);

/**
 * @brief
 *   A helper function for emitting a freeform text as a debug
 *   event. The debug event is a structure with a logregion and a
 *   freeform text.
 *
 * @param ioWriter[inout] The writer to use for writing out the event
 *
 * @param inProfileID[in] The profile ID of the event
 *
 * @param inEventType[in] The Event type to be written out
 *
 * @param appData[in]     A pointer to the DebugLogContext, a structure
 *                        that holds a string format, arguments, and a
 *                        log region
 *
 * @retval #WEAVE_NO_ERROR On success.
 *
 * @retval other          Other errors that may be returned from the ioWriter.
 *
 */
WEAVE_ERROR PlainTextWriter(::nl::Weave::TLV::TLVWriter & ioWriter, uint8_t inDataTag, void *appData);

} // WeaveMakeManagedNamespaceIdentifier(DataManagement, kWeaveManagedNamespaceDesignation_Current)
} // Profiles
} // Weave
} //nl
#endif // _WEAVE_DATA_MANAGEMENT_EVENT_LOGGING_CURRENT_H