diff options
Diffstat (limited to 'libparc/parc/logging/parc_Log.h')
-rw-r--r-- | libparc/parc/logging/parc_Log.h | 418 |
1 files changed, 0 insertions, 418 deletions
diff --git a/libparc/parc/logging/parc_Log.h b/libparc/parc/logging/parc_Log.h deleted file mode 100644 index 29e401e0..00000000 --- a/libparc/parc/logging/parc_Log.h +++ /dev/null @@ -1,418 +0,0 @@ -/* - * Copyright (c) 2017 Cisco and/or its affiliates. - * 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 parc_Log.h - * @brief Event logging. - * - * This is an logging mechanism patterned after the Syslog logging protocol (RFC 5424), - * and influenced by `java.util.logging` and Apache Log4J. - * - * The lifecycle of a `PARCLog` starts with creating an instance via `parcLog_Create` - * and calling the various functions to emit log messages. - * - * Finally the log is released via `parcLog_Release` which ensures - * that any queued log messages are transmitted and resources are released. - * - * Every PARCLog instance has a logging level, a threshold that is set via `parcLog_SetLevel` - * that determines what kind of PARCLogEntry instances are actually logged. - * The PARCLogLevel PARCLogLevel_Emergency is always logged regardless of the current logging level. - * - */ -#ifndef libparc_parc_Logger_h -#define libparc_parc_Logger_h - -#include <stdarg.h> - -#include <parc/logging/parc_LogReporter.h> -#include <parc/logging/parc_LogEntry.h> -#include <parc/logging/parc_LogLevel.h> - -struct PARCLog; -typedef struct PARCLog PARCLog; - -/** - * Create a valid PARCLog instance. - * - * The initial instance's log level is set to `PARCLogLevel_Off`. - * - * @param [in] hostName A pointer to a nul-terminated C string, or NULL (See {@link PARCLogEntry}). - * @param [in] applicationName A pointer to a nul-terminated C string, or NULL (See {@link PARCLogEntry}). - * @param [in] processId A pointer to a nul-terminated C string, or NULL (See {@link PARCLogEntry}). - * @param [in] reporter A pointer to a valid `PARCLogReporter` instance. - * - * @return non-NULL A valid PARCLog instance. - * @return NULL An error occurred. - * - * Example: - * @code - * { - * PARCFileOutputStream *fileOutput = parcFileOutputStream_Create(1); - * PARCOutputStream *output = parcFileOutputStream_AsOutputStream(fileOutput); - * - * PARCLogReporter *reporter = parcLogReporterFile_Create(output); - * - * parcOutputStream_Release(&output); - * parcFileOutputStream_Release(&fileOutput); - * - * PARCLog *log = parcLog_Create("localhost", "myApp", "daemon", reporter); - * parcLogReporter_Release(&reporter); - * } - * @endcode - */ -PARCLog *parcLog_Create(const char *hostName, const char *applicationName, const char *processId, PARCLogReporter *reporter); - -/** - * Increase the number of references to a `PARCLog`. - * - * Note that new `PARCLog` is not created, - * only that the given `PARCLog` reference count is incremented. - * Discard the reference by invoking `parcLog_Release`. - * - * @param [in] parcLog A pointer to a `PARCLog` instance. - * - * @return The input `PARCLog` pointer. - * - * Example: - * @code - * { - * PARCFileOutputStream *fileOutput = parcFileOutputStream_Create(1); - * PARCOutputStream *output = parcFileOutputStream_AsOutputStream(fileOutput); - * - * PARCLogReporter *reporter = parcLogReporterFile_Create(output); - * - * parcOutputStream_Release(&output); - * parcFileOutputStream_Release(&fileOutput); - * - * PARCLog *log = parcLog_Create("localhost", "myApp", "daemon", reporter); - * - * PARCLog *x_2 = parcLog_Acquire(log); - * - * parcLog_Release(&log); - * parcLog_Release(&x_2); - * } - * @endcode - */ -PARCLog *parcLog_Acquire(const PARCLog *parcLog); - -/** - * Release a previously acquired reference to the specified instance, - * decrementing the reference count for the instance. - * - * The pointer to the instance is set to NULL as a side-effect of this function. - * - * If the invocation causes the last reference to the instance to be released, - * the instance is deallocated and the instance's implementation will perform - * additional cleanup and release other privately held references. - * - * @param [in,out] logPtr A pointer to a PARCLog instance pointer, which will be set to zero on return. - * - * Example: - * @code - * { - * PARCFileOutputStream *fileOutput = parcFileOutputStream_Create(1); - * PARCOutputStream *output = parcFileOutputStream_AsOutputStream(fileOutput); - * - * PARCLogReporter *reporter = parcLogReporterFile_Create(output); - * - * parcOutputStream_Release(&output); - * parcFileOutputStream_Release(&fileOutput); - * - * PARCLog *log = parcLog_Create("localhost", "myApp", "daemon", reporter); - * parcLogReporter_Release(&reporter); - * - * parcLog_Release(&log); - * } - * @endcode - */ -void parcLog_Release(PARCLog **logPtr); - -/** - * Set the log severity level to the given value. - * - * The level is the maximum severity that will be logged via the PARCLogReporter. - * The log severity PARCLogLevel_Emergency cannot be blocked. - * - * @param [in] log A pointer to valid instance of PARCLog. - * @param [in] level A pointer to valid instance of PARCLogLevel. - * - * @return The previous value of the threshold. - * - * Example: - * @code - * { - * PARCFileOutputStream *fileOutput = parcFileOutputStream_Create(1); - * PARCOutputStream *output = parcFileOutputStream_AsOutputStream(fileOutput); - * - * PARCLogReporter *reporter = parcLogReporterFile_Create(output); - * - * parcOutputStream_Release(&output); - * parcFileOutputStream_Release(&fileOutput); - * - * PARCLog *log = parcLog_Create("localhost", "myApp", "daemon", reporter); - * parcLogReporter_Release(&reporter); - * - * PARCLogLevel old = parcLog_SetLevel(log, PARCLogLevel_Warning); - * - * parcLog_SetLevel(log, old); - * - * parcLog_Release(&log); - * } - * @endcode - */ -PARCLogLevel parcLog_SetLevel(PARCLog *log, const PARCLogLevel level); - -/** - * Get the severity level of the given PARCLog instance. - * - * The level is the maximum severity that will be logged via the PARCLogReporter. - * The log severity PARCLogLevel_Emergency cannot be blocked. - * - * @param [in] log A pointer to valid instance of PARCLog. - * - * @return The severity level of the given PARCLog instance. - * - * Example: - * @code - * { - * PARCFileOutputStream *fileOutput = parcFileOutputStream_Create(1); - * PARCOutputStream *output = parcFileOutputStream_AsOutputStream(fileOutput); - * - * PARCLogReporter *reporter = parcLogReporterFile_Create(output); - * - * parcOutputStream_Release(&output); - * parcFileOutputStream_Release(&fileOutput); - * - * PARCLog *log = parcLog_Create("localhost", "myApp", "daemon", reporter); - * parcLogReporter_Release(&reporter); - * - * PARCLogLevel level = parcLog_GetLevel(log, PARCLogLevel_Warning); - * - * parcLog_Release(&log); - * } - * @endcode - */ -PARCLogLevel parcLog_GetLevel(const PARCLog *log); - -/** - * Test if a PARCLogLevel would be logged by the current state of the given PARCLog instance. - * - * @param [in] log A pointer to valid instance of PARCLog. - * @param [in] level An instance of PARCLogLevel. - * - * @return true A PARCLogEntry of the given level would be logged. - * @return false A PARCLogEntry of the given level would be logged. - * - * Example: - * @code - * { - * PARCFileOutputStream *fileOutput = parcFileOutputStream_Create(1); - * PARCOutputStream *output = parcFileOutputStream_AsOutputStream(fileOutput); - * - * PARCLogReporter *reporter = parcLogReporterFile_Create(output); - * - * parcOutputStream_Release(&output); - * parcFileOutputStream_Release(&fileOutput); - * - * PARCLog *log = parcLog_Create("localhost", "myApp", "daemon", reporter); - * parcLogReporter_Release(&reporter); - * - * if (parcLog_IsLoggable(log, PARCLogLevel_Warning)) { - * printf("Logging is set to Warning severity level\n"); - * } - * - * parcLog_Release(&log); - * } - * @endcode - */ - -#define parcLog_IsLoggable(_log_, _level_) \ - (_level_ == PARCLogLevel_Emergency) || (parcLogLevel_Compare(parcLog_GetLevel(_log_), _level_) >= 0) -//bool parcLog_IsLoggable(const PARCLog *log, const PARCLogLevel level); - -/** - * Compose and emit a log message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] level An instance of PARCLogLevel. - * @param [in] messageId A value for the message identifier. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ap A `va_list` representing the parameters for the format specification. - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower than the specified PARCLogLevel. - * - * Example: - * @code - * parcLog_MessageVaList(log, PARCLogLevel_Warning, 123, "This is a warning message."); - * @endcode - */ -bool parcLog_MessageVaList(PARCLog *log, PARCLogLevel level, uint64_t messageId, const char *format, va_list ap); - -/** - * Compose and emit a log message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] level An instance of PARCLogLevel. - * @param [in] messageId A value for the message identifier. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower than the specified PARCLogLevel. - * - * Example: - * @code - * parcLog_Message(log, PARCLogLevel_Warning, "This is a warning message."); - * @endcode - */ -bool parcLog_Message(PARCLog *log, PARCLogLevel level, uint64_t messageId, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Warning message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_Warning(log, "This is a warning message."); - * @endcode - */ -bool parcLog_Warning(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Message level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_Info(log, "This is an info message."); - * @endcode - */ -bool parcLog_Info(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Notice level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_Notice(log, "This is a notice message."); - * @endcode - */ -bool parcLog_Notice(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Debug level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_DebugMessage(log, "This is a debug message."); - * @endcode - */ -bool parcLog_Debug(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Error level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_ErrorMessage(log, "This is an error message."); - * @endcode - */ -bool parcLog_Error(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Critical level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_CriticalMessage(log, "This is a critical message."); - * @endcode - */ -bool parcLog_Critical(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Alert level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_AlertMessage(log, "This is an alert message."); - * @endcode - */ -bool parcLog_Alert(PARCLog *log, const char *restrict format, ...); - -/** - * Compose and emit a PARCLogLevel_Emergency level message. - * - * @param [in] log A pointer to a valid PARCLog instance. - * @param [in] format A pointer to a nul-terminated C string containing a printf format specification. - * @param [in] ... Zero or more parameters as input for the format specification). - * - * @return true The message was logged. - * @return false The message was not logged because the log severity threshold level is lower. - * - * Example: - * @code - * parcLog_EmergencyMessage(log, "This is an emergency message."); - * @endcode - */ -bool parcLog_Emergency(PARCLog *log, const char *restrict format, ...); -#endif // libparc_parc_Logger_h |