path: root/longbow/src/LongBow/longBow_EventType.h

/*
 * 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 longBow_EventType.h
 * @ingroup internals
 * @ingroup runtime
 * @ingroup testing
 * @brief LongBow Events and Support.
 *
 */
#ifndef LongBow_longBow_EventType_h
#define LongBow_longBow_EventType_h

#include <LongBow/longBow_Status.h>

struct longbow_event_type;
/**
 * @typedef LongBowEventType
 *
 * A LongBowEventType identifies a specific Event induced or generated by a running programme.
 */
typedef struct longbow_event_type LongBowEventType;

/**
 * @var LongBowAssertEvent
 */
extern LongBowEventType LongBowAssertEvent;

/**
 * @var LongBowTestEvent
 */
extern LongBowEventType LongBowTestEvent;

/**
 * @var LongBowTestSkippedEvent
 */
extern LongBowEventType LongBowTestSkippedEvent;

/**
 * @var LongBowTestUnimplementedEvent
 */
extern LongBowEventType LongBowTestUnimplementedEvent;

/**
 * @var LongBowTrapOutOfMemoryEvent
 */
extern LongBowEventType LongBowTrapOutOfMemoryEvent;

/**
 * @var LongBowTrapUnexpectedStateEvent
 */
extern LongBowEventType LongBowTrapUnexpectedStateEvent;

/**
 * @var LongBowTrapEvent
 */
extern LongBowEventType LongBowTrapEvent;

/**
 * @var LongBowTrapOutOfBounds
 */
extern LongBowEventType LongBowTrapOutOfBounds;

/**
 * @var LongBowTrapIllegalValue
 */
extern LongBowEventType LongBowTrapIllegalValue;

/**
 * @var LongBowTrapInvalidValue
 */
extern LongBowEventType LongBowTrapInvalidValue;

/**
 * @var LongBowTrapUnrecoverableState
 */
extern LongBowEventType LongBowTrapUnrecoverableState;

/**
 * @var LongBowTrapNotImplemented
 */
extern LongBowEventType LongBowTrapNotImplemented;

/**
 * @var LongBowTrapCannotObtainLockEvent
 */
extern LongBowEventType LongBowTrapCannotObtainLockEvent;

/**
 * @var LongBowEventSIGHUP
 */
extern LongBowEventType LongBowEventSIGHUP;

/**
 * @var LongBowEventSIGINT
 */
extern LongBowEventType LongBowEventSIGINT;

/**
 * @var LongBowEventSIGQUIT
 */
extern LongBowEventType LongBowEventSIGQUIT;

/**
 * @var LongBowEventSIGILL
 */
extern LongBowEventType LongBowEventSIGILL;

/**
 * @var LongBowEventSIGTRAP
 */
extern LongBowEventType LongBowEventSIGTRAP;

/**
 * @var LongBowEventSIGABRT
 */
extern LongBowEventType LongBowEventSIGABRT;

/**
 * @var LongBowEventSIGIOT
 */
extern LongBowEventType LongBowEventSIGIOT;

/**
 * @var LongBowEventSIGEMT
 */
extern LongBowEventType LongBowEventSIGEMT;

/**
 * @var LongBowEventSIGFPE
 */
extern LongBowEventType LongBowEventSIGFPE;

/**
 * @var LongBowEventSIGKILL
 */
extern LongBowEventType LongBowEventSIGKILL;

/**
 * @var LongBowEventSIGBUS
 */
extern LongBowEventType LongBowEventSIGBUS;

/**
 * @var LongBowEventSIGSEGV
 */
extern LongBowEventType LongBowEventSIGSEGV;

/**
 * @var LongBowEventSIGSYS
 */
extern LongBowEventType LongBowEventSIGSYS;

/**
 * @var LongBowEventSIGPIPE
 */
extern LongBowEventType LongBowEventSIGPIPE;

/**
 * @var LongBowEventSIGALRM
 */
extern LongBowEventType LongBowEventSIGALRM;

/**
 * @var LongBowEventSIGTERM
 */
extern LongBowEventType LongBowEventSIGTERM;

/**
 * @var LongBowEventSIGURG
 */
extern LongBowEventType LongBowEventSIGURG;

/**
 * @var LongBowEventSIGSTOP
 */
extern LongBowEventType LongBowEventSIGSTOP;

/**
 * @var LongBowEventSIGTSTP
 */
extern LongBowEventType LongBowEventSIGTSTP;

/**
 * @var LongBowEventSIGCONT
 */
extern LongBowEventType LongBowEventSIGCONT;

/**
 * @var LongBowEventSIGCHLD
 */
extern LongBowEventType LongBowEventSIGCHLD;

/**
 * @var LongBowEventSIGTTIN
 */
extern LongBowEventType LongBowEventSIGTTIN;

/**
 * @var LongBowEventSIGTTOU
 */
extern LongBowEventType LongBowEventSIGTTOU;

/**
 * @var LongBowEventSIGIO
 */
extern LongBowEventType LongBowEventSIGIO;

/**
 * @var LongBowEventSIGXCPU
 */
extern LongBowEventType LongBowEventSIGXCPU;

/**
 * @var LongBowEventSIGXFSZ
 */
extern LongBowEventType LongBowEventSIGXFSZ;

/**
 * @var LongBowEventSIGVTALRM
 */
extern LongBowEventType LongBowEventSIGVTALRM;

/**
 * @var LongBowEventSIGPROF
 */
extern LongBowEventType LongBowEventSIGPROF;

/**
 * @var LongBowEventSIGWINCH
 */
extern LongBowEventType LongBowEventSIGWINCH;

/**
 * @var LongBowEventSIGINFO
 */
extern LongBowEventType LongBowEventSIGINFO;

/**
 * @var LongBowEventSIGUSR1
 */
extern LongBowEventType LongBowEventSIGUSR1;

/**
 * @var LongBowEventSIGUSR2
 */
extern LongBowEventType LongBowEventSIGUSR2;

/**
 * Determine if two `LongBowEventType` instances are equal.
 *
 * The following equivalence relations on non-null `LongBowEventType` instances are maintained:
 *
 *   * It is reflexive: for any non-null reference value x, `longBowEventType_Equals(x, x)` must return true.
 *
 *   * It is symmetric: for any non-null reference values x and y, `longBowEventType_Equals(x, y)` must return true if and only if
 *        `longBowEventType_Equals(y x)` returns true.
 *
 *   * It is transitive: for any non-null reference values x, y, and z, if
 *        `longBowEventType_Equals(x, y)` returns true and
 *        `longBowEventType_Equals(y, z)` returns true,
 *        then `longBowEventType_Equals(x, z)` must return true.
 *
 *   * It is consistent: for any non-null reference values x and y, multiple invocations of `longBowEventType_Equals(x, y)`
 *         consistently return true or consistently return false.
 *
 *   * For any non-null reference value x, `longBowEventType_Equals(x, NULL)` must return false.
 *
 *
 * @param [in] x A pointer to a `LongBowEventType` instance.
 * @param [in] y A pointer to a `LongBowEventType` instance.
 *
 * @return true `LongBowEventType` x and y are equal.
 * @return false `LongBowEventType` x and y are not equal.
 *
 * Example:
 * @code
 * {
 *     LongBowEventType *e1 = LongBowAssertEvent;
 *     LongBowEventType *e2 = LongBowAssertEvent;
 *
 *     if (longBowEventType_Equals(bufferA, bufferB)) {
 *         printf("The events are equal.\n");
 *     } else {
 *         printf("The events are NOT equal.\n");
 *     }
 * }
 * @endcode
 */
bool longBowEventType_Equals(const LongBowEventType *x, const LongBowEventType *y);

/**
 * Produce a nul-terminated C string representation of this `LongBowEventType` instance.
 *
 * @param [in] eventType A pointer to a `LongBowEventType` instance.
 *
 * @return The C string name of the given LongBowEventType.
 *
 * Example:
 * @code
 * {
 *     LongBowEventType *event = LongBowAssertEvent;
 *
 *     printf("Event = %s\n", longBowEventType_GetName(event));
 * }
 * @endcode
 */
const char *longBowEventType_GetName(const LongBowEventType *eventType);

/**
 * Test if a `LongBowEventType` is specified to not report a stack backtrace.
 *
 * @param [in] eventType A pointer to a `LongBowEventType` instance.
 *
 * @return true if the LongBowEventType indicates that a backtrace report is not to be printed.
 *
 * Example:
 * @code
 * {
 *     LongBowEvent *event = ...
 *
 *    if (longBowEventType_IsSuppressBacktrace(longBowEvent_GetEventType(event)) == false) {
 *        char **strs = longBowEvent_CreateSymbolicCallstack(event);
 *        if (strs != NULL) {
 *            for (size_t i = 0; i < longBowEvent_GetCallStackLength(event); ++i) {
 *                printf("%s\r\n", strs[i]);
 *            }
 *            free(strs);
 *        }
 *    }
 * }
 * @endcode
 */
bool longBowEventType_IsSuppressBacktrace(const LongBowEventType *eventType);

/**
 * Test if a LongBowEventType is specified to not report an alert.
 *
 * @param [in] eventType A pointer to a `LongBowEventType` instance.
 *
 * @return true if the LongBowEventType is specified to not report an alert.
 *
 * Example:
 * @code
 * {
 *     LongBowEvent *event = ...
 *
 *     if (longBowEventType_IsSuppressAlert(longBowEvent_GetEventType(event)) == false) {
 *         char *location = longBowLocation_ToString(longBowEvent_GetLocation(event));
 *         printf("%s %s %s %s\r\n",
 *             longBowEvent_GetName(event), location, longBowEvent_GetKind(event), longBowEvent_GetMessage(event));
 *
 *         ...
 *     }
 *
 * }
 * @endcode
 */
bool longBowEventType_IsSuppressAlert(const LongBowEventType *eventType);

/**
 * Get the status of the specified `LongBowEventType` instance.
 *
 * @param [in] eventType A pointer to a `LongBowEventType` instance.
 *
 * @return The LongBowStatus associated with the given LongBowEventType.
 *
 * Example:
 * @code
 * {
 *     LongBowEvent *event = ...
 *
 *     LongBowStatus status = longBowEventType_GetStatus(event);
 *     // use the status as needed
 * }
 * @endcode
 */
LongBowStatus longBowEventType_GetStatus(const LongBowEventType *eventType);

/**
 * Get the LongBowEventType corresponding to the given signal.
 *
 * @param [in] signal The signal to index.
 *
 * @return the LongBowEventType corresponding to the given signal.
 *
 * Example:
 * @code
 * {
 *     LongBowEventType *type = longBowEventType_GetEventTypeForSignal(1);
 *     // type is equal to LongBowEventSIGHUP
 * }
 * @endcode
 */
LongBowEventType *longBowEventType_GetEventTypeForSignal(const int signal);
#endif // LongBow_longBow_EventType_h