Overview
C API (Component Interface)
struct EventGetSymbolString { UINT32 flags; Symbol symbol; char* buffer; UINT32 bufferSize; };

Get a string that specifies what is represented by symbol. This is most useful for converting result codes into human-readable strings, but can also aid in debugging by clarifying to the developer what any symbol represents.

Contract Wrappers

1199
getSymbolString()

Fields

UINT32 flags IN
None defined (must be zero).
Symbol symbol IN
The symbol to translate.
char* buffer IN/OUT
A pointer to a buffer in which the result will be written.
UINT32 bufferSize IN/OUT
The total number of bytes available in the buffer (i.e. including space for the NUL character).

Return Values

  • C_OK
  • E_OVERFLOW=If the buffer is not large enough to hold the result (in this case, bufferSize is set to the required size of the buffer).
Notes
  • If the passed symbol is not recognised, this function writes to cerr and returns a formatted error message as the result, to aid in debugging.

Result

  • A formatted string is returned in buffer or an error is raised.

Example

Taken from 1199. Note that this event can be called with hCaller set to zero.

C Source Code (against Component Interface)
inline std::string getSymbolString(Symbol symbol) { char buffer[256]; EventGetSymbolString data; data.flags = 0; data.symbol = symbol; data.buffer = buffer; data.bufferSize = 256; EngineEvent event; event.hCaller = 0; event.flags = 0; event.type = ENGINE_EVENT_GET_SYMBOL_STRING; event.data = (void*) &data; ____SUCCESS(brahms_engineEvent(&event)); return buffer; }