Files
file	skinmon.h
	This header file defines functions for outputting messages from the skin.

Enumerations
enum	{ MON_DEBUG_ASSERT = MON_CLASS_DEBUG + (3 << MON_SHIFT_SUBCLASS) }
	Sub-class of debug information for HQASSERT(). More...

Functions
void	SwLeSetMonitorFunction (SwLeMONITORCALLBACK *pfnMonitor)
	Set the default monitor information callback function for the SDK. More...

void	SkinMonitorl (int32 cbData, const uint8 *pszMonitorData)
	Display a message through the monitor callback, if provided. More...

void	RIPMonitorl (int32 cbData, const uint8 *pszMonitorData)
	Display a message through the monitor callback, if provided. More...

void	SkinMonitorf (const char *format,...)
	Display a formatted message through monitor events, or the monitor callback, if provided. More...

void	SkinEMonitorf (sw_tl_ref tl, sw_mon_channel channel, sw_mon_type type, const char *format,...)
	Display a formatted message through the event system. More...

void	SkinVEMonitorf (sw_tl_ref tl, sw_mon_channel channel, sw_mon_type type, const char *format, va_list vlist)
	Similar to SkinEMonitorf(), but with an explicit vararg list. More...

Detailed Description

There are two routes for monitor information to be supplied to the skin:

Monitor events. These provide a lot of contextual detail about the monitor information, including machine-parsable Unique IDs for errors, and can be filtered, diverted, suppressed, rerouted, etc., with ease. Monitor events are only available between SwLeSDKStart() and SwLeSDKEnd() calls. The RIP's fallback behaviour for monitor events if not otherwise handled is to be written to the %monitor% device, which in turn uses the monitor function callbacks to output the message.
Monitor callback functions. The SDK uses a default monitor callback function (set by SwLeSetMonitorFunction()) to emit all monitor information from SkinMonitorl(), SkinMonitorf(), SkinEMonitorf(), SkinVEMonitorf(), via the event system (if it is started) or the monitor functions (if the event system is not started, or if the event is handled by the RIP's fallback monitor event handler). The SwLeStart() call can specify an override handler if desired, for use by messages originated in the RIP. The monitor callback function should be a thread-safe function that takes responsibility for writing a buffer of data verbatim to the log or output channel(s), as appropriate.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Sub-class of debug information for HQASSERT().

Enumerator
MON_DEBUG_ASSERT	Any message with class MON_CLASS_DEBUG and this subclass is routed directly to the monitor callback, and not through events.

Function Documentation

◆ RIPMonitorl()

void RIPMonitorl	(	int32	cbData,
		const uint8 *	pszMonitorData
	)

Display a message through the monitor callback, if provided.

Parameters

cbData	The length, in bytes, of a monitor information string.
pszMonitorData	The monitor information string.

If the RIP is running, this function will output through the monitor function passed to SwLeStart(). If a NULL monitor function was passed to SwLeStart(), then it uses the default monitor function installed by SwLeSetMonitorFunction().

◆ SkinEMonitorf()

void SkinEMonitorf	(	sw_tl_ref	tl,
		sw_mon_channel	channel,
		sw_mon_type	type,
		const char *	format,
			...
	)

Display a formatted message through the event system.

Parameters

[in]	tl	A timeline associated with this message. The SkinTimeline() call can be used to supply the top-level skin timeline, if no other suitable timeline is available. It acceptable abbreviation to use 0 for the timeline reference: this is an invalid timeline reference which will be changed to SkinTimeline() by default.
[in]	channel	A monitor channel to output the message to.
[in]	type	A combined UID, message class, and error ID. See the file monevent.h for definitions of the type field.
[in]	format	A swcopyf() format string.
[in]	...	A variable number of arguments, according to the format specification.

If the event system is not started, this call will fall back to the monitor callback, if provided.

The semantics are similar to printf() or fprintf(), but with output sent to the event channel provided, with the timeline and type specified. This channel will usually be routed to the monitor callback.

Messages are formatted into a fixed-size buffer. The message will be truncated if it does not fit into the buffer. If this happens, an additional message will be sent to the monitor callback, warning about the truncation.

If no monitor callback has been supplied, this function does nothing.

◆ SkinMonitorf()

void SkinMonitorf	(	const char *	format,
			...
	)

Display a formatted message through monitor events, or the monitor callback, if provided.

Parameters

[in]	format	A swcopyf() format string.
[in]	...	A variable number of arguments, according to the format specification.

This function calls SkinVEMonitorf() with an invalid timeline, channel MON_CHANNEL_STDOUT, and type MON_CLASS_INFO.

◆ SkinMonitorl()

void SkinMonitorl	(	int32	cbData,
		const uint8 *	pszMonitorData
	)

Display a message through the monitor callback, if provided.

Parameters

cbData	The length, in bytes, of a monitor information string.
pszMonitorData	The monitor information string.

This function only outputs through the default monitor function installed by SwLeSetMonitorFunction().

◆ SkinVEMonitorf()

void SkinVEMonitorf	(	sw_tl_ref	tl,
		sw_mon_channel	channel,
		sw_mon_type	type,
		const char *	format,
		va_list	vlist
	)

Similar to SkinEMonitorf(), but with an explicit vararg list.

Parameters

[in]	tl	A timeline associated with this message. The SkinTimeline() call can be used to supply the top-level skin timeline, if no other suitable timeline is available.
[in]	channel	A monitor channel to output the message to.
[in]	type	A combined UID, message class, and error ID. See the file monevent.h for definitions of the type field.
[in]	format	A swcopyf() format string.
[in]	vlist	A variable argument list, according to the format specification.

◆ SwLeSetMonitorFunction()

void SwLeSetMonitorFunction ( SwLeMONITORCALLBACK * pfnMonitor )

Set the default monitor information callback function for the SDK.

Parameters

[in] pfnMonitor A pointer to a monitor callback function which the skin must implement if it wishes to receive monitor information from the SDK. The callback function should be thread-safe.

Setting a default callback function allows the skin to receive monitor information provided by the SDK while the RIP is not running. If the RIP is running (i.e., between SwLeStart() and SwLeStop() calls), then monitor information will be sent to the callback function supplied to the RIP, or to this function if the SwLeStart() monitor function parameter was NULL.

All monitor information from the SDK is routed through the RIP's monitor function (if running) or this function (if no RIP running).

This function must be called after SwLeInitRuntime().

Files

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ RIPMonitorl()

◆ SkinEMonitorf()

◆ SkinMonitorf()

◆ SkinMonitorl()

◆ SkinVEMonitorf()

◆ SwLeSetMonitorFunction()