1 /*
2 * Percepio Trace Recorder for Tracealyzer v4.10.3
3 * Copyright 2023 Percepio AB
4 * www.percepio.com
5 *
6 * SPDX-License-Identifier: Apache-2.0
7 */
8 
9 /**
10  * @file
11  *
12  * @brief Public trace string APIs.
13  */
14 
15 #ifndef TRC_STRING_H
16 #define TRC_STRING_H
17 
18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) && (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)
19 
20 #include <trcTypes.h>
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 /**
27  * @defgroup trace_string_apis Trace String APIs
28  * @ingroup trace_recorder_apis
29  * @{
30  */
31 
32 /**
33  * @brief Registers a trace string.
34  *
35  * This routine registers a strings in the recorder, e.g. for names of user
36  * event channels.
37  *
38  * Example:
39  *	 TraceStringHandle_t myEventHandle;
40  *	 xTraceStringRegister("MyUserEvent", &myEventHandle);
41  *	 ...
42  *	 xTracePrintF(myEventHandle, "My value is: %d", myValue);
43  *
44  * @param[in] szString String.
45  * @param[out] pString Pointer to uninitialized trace string.
46  *
47  * @retval TRC_FAIL Failure
48  * @retval TRC_SUCCESS Success
49  */
50 traceResult xTraceStringRegister(const char *szString, TraceStringHandle_t* pString);
51 
52 /**
53  * @brief Registers a trace string.
54  *
55  * @deprecated Remains for backward compability with pre v4.6 versions
56  * of the recorder.
57  *
58  * @param[in] name Name.
59  *
60  * @return TraceStringHandle_t
61  */
62 TraceStringHandle_t xTraceRegisterString(const char *name);
63 
64 /** @} */
65 
66 #ifdef __cplusplus
67 }
68 #endif
69 
70 #else
71 
72 #define xTraceStringRegister(__szString, __pString) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__szString), (void)(__pString), TRC_SUCCESS)
73 
74 #endif
75 
76 #endif
77