/*
* Percepio Trace Recorder for Tracealyzer v4.8.0.hotfix1
* Copyright 2023 Percepio AB
* www.percepio.com
*
* SPDX-License-Identifier: Apache-2.0
*/

/**
 * @file 
 * 
 * @brief Public trace object APIs.
 */

#ifndef TRC_OBJECT_H
#define TRC_OBJECT_H

#if (TRC_USE_TRACEALYZER_RECORDER == 1)

#if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)

#include <trcTypes.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup trace_object_apis Trace Object APIs
 * @ingroup trace_recorder_apis
 * @{
 */

/**
 * @brief Registers trace object.
 * 
 * @param[in] uiEventCode Event code.
 * @param[in] pvObject Object.
 * @param[in] szName Name.
 * @param[in] uxStateCount State count. 
 * @param[in] uxStates States.
 * @param[in] uxOptions Options.
 * @param[out] pxObjectHandle Pointer to uninitialized trace object.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectRegisterInternal(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxStateCount, const TraceUnsignedBaseType_t uxStates[], TraceUnsignedBaseType_t uxOptions, TraceObjectHandle_t* pxObjectHandle);

/**
 * @brief Registers trace object.
 * 
 * @param[in] uiEventCode Event code.
 * @param[in] pvObject Object.
 * @param[in] szName Name.
 * @param[in] uxState State.
 * @param[out] pxObjectHandle Pointer to uninitialized trace object.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectRegister(uint32_t uiEventCode, void* const pvObject, const char* szName, TraceUnsignedBaseType_t uxState, TraceObjectHandle_t *pxObjectHandle);

/**
 * @brief Unregisters trace object.
 * 
 * @param[in] xObjectHandle Pointer to initialized trace object.
 * @param[in] uiEventCode Event code.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectUnregister(TraceObjectHandle_t xObjectHandle, uint32_t uiEventCode, TraceUnsignedBaseType_t uxState);

/**
 * @brief Sets trace object name.
 * 
 * @param[in] xObjectHandle Pointer to initialized trace object.
 * @param[in] szName Name.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectSetName(TraceObjectHandle_t xObjectHandle, const char *szName);

/**
 * @brief Sets trace object state.
 * 
 * @param[in] xObjectHandle Pointer to initialized trace object.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
#define xTraceObjectSetState(xObjectHandle, uxState) xTraceObjectSetSpecificState(xObjectHandle, 0, uxState)

/**
 * @brief Sets trace object specific state state.
 * 
 * @param[in] xObjectHandle Pointer to initialized trace object.
 * @param[in] uiIndex State Index.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
#define xTraceObjectSetSpecificState(xObjectHandle, uiIndex, uxState) xTraceEntrySetState((TraceEntryHandle_t)(xObjectHandle), uiIndex, uxState)

/**
 * @brief Sets trace object options.
 * 
 * @param[in] xObjectHandle Pointer to initialized trace object.
 * @param[in] uiOptions Options.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
#define xTraceObjectSetOptions(xObjectHandle, uiOptions) xTraceEntrySetOptions((TraceEntryHandle_t)(xObjectHandle), uiOptions)

/**
 * @brief Registers trace object without trace object handle.
 * 
 * @param[in] uiEventCode Event code.
 * @param[in] pvObject Object.
 * @param[in] szName Name.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectRegisterWithoutHandle(uint32_t uiEventCode, void* pvObject, const char* szName, TraceUnsignedBaseType_t uxState);

/**
 * @brief Unregisters trace object without trace object handle.
 * 
 * @param[in] uiEventCode Event code.
 * @param[in] pvObject Object.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectUnregisterWithoutHandle(uint32_t uiEventCode, void* pvObject, TraceUnsignedBaseType_t uxState);

/**
 * @brief Set trace object name without trace object handle.
 * 
 * @param[in] pvObject Object.
 * @param[in] szName Name.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectSetNameWithoutHandle(void* pvObject, const char* szName);

/**
 * @brief Set trace object state without trace object handle.
 * 
 * @param[in] pvObject Object.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
#define xTraceObjectSetStateWithoutHandle(pvObject, uxState) xTraceObjectSetSpecificStateWithoutHandle(pvObject, 0, uxState)

/**
 * @brief Sets trace object specific state without trace object
 * handle.
 * 
 * @param[in] pvObject Object. 
 * @param[in] uiIndex State index.
 * @param[in] uxState State.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectSetSpecificStateWithoutHandle(void* pvObject, uint32_t uiIndex, TraceUnsignedBaseType_t uxState);

/**
 * @brief Sets trace object options without trace object handle.
 * 
 * @param[in] pvObject Object.
 * @param[in] uiOptions Options.
 * 
 * @retval TRC_FAIL Failure
 * @retval TRC_SUCCESS Success
 */
traceResult xTraceObjectSetOptionsWithoutHandle(void* pvObject, uint32_t uiOptions);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */

#endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */

#endif /* TRC_OBJECT_H */