Detailed Description

Allows information to be output to a log.

You.i Engine's logging system provides a method for outputting, at run-time, information relating to the application. The CYILogPolicy dictates where the information will be output. By default the majority of supported platforms use the CYIConsoleLogPolicy to output logs to the platform's standard output or error stream, depending on the log message severity. Some platforms have alternate logging methods, in these cases an alternate CYILogPolicy implementation will be used by default. One example of this is CYIAndroidLogPolicy which writes to Android's logging system making the logs visible via Android's Logcat system.

Generating Logs

By default logging is enabled in You.i Engine and all messages will be output using the method of the CYILogPolicy set on the CYILogger. Macros are provided to simplify writing log messages to the logging system. There is a macro for each of the log severities supplied by You.i Engine, the macros are displayed in the following table:

Log Macro	Description
YI_LOGF	Logs a fatal error, this will always abort the application.
YI_LOGE	Logs an error.
YI_LOGW	Logs a warning.
YI_LOGI	Logs information.
YI_LOGD	Logs debug information.

The log macros listed in the table above are in order of highest severity to lowest severity. All log macros have the same syntax and support variadic arguements for the message. The following code snippet displays the use of a log macro:

    // Logs an informational message with the tag MyExampleClass.
    int32_t nValue = 10;
    YI_LOGI("MyExampleClass", "The value of nValue is: %d", nValue);

    Output: I/MyExampleClass: The value of nValue is: 10

Passing Log Tags

The best way to pass a log tag to a YI_LOGx function is to pass a string literal like so:

    YI_LOGI("MyExampleClass", "An example log.");

To avoid repeating the same string in multiple log calls, a #define should be used and should be named LOG_TAG:

    #define LOG_TAG "MyExampleClass"

    YI_LOGI(LOG_TAG, "An example log.");

    YI_LOGW(LOG_TAG, "Another example log.");

String instances can also be passed in. However, note that this is less performant due to the need to copy those strings on some platforms:

    CYIString logTag("MyExampleClass");
    YI_LOGI(logTag, "An example log.");

Warning: Non-static char arrays should never be passed to the logger functions. Passing a non-static char array may result in runtime crashes.

Filtering Ouput

By default logs of all severity and tag will be written, this includes logs generated by You.i Engine. The application developer may not want to output all logs, to accomodate this the logging system has a built-in mechanism for filtering logs. The CYILogger takes a CYIPreferences object which contains key-value pairs that indicate to the logging system which logs to filter out. Severity based filtering can be applied at a system level as well as at a tag level. The key-value pair stored in CYIPreferences related to filtering should be provided in the following format:

Key	Value
Tag to filter	Severity level

When filtering at tag level the tag specified for filtering should be prefixed with TAG_ and to filter at a system level the reserved tag TAG_GENERAL should be used. The severity level that is specified in the preferences is the lowest level of severity that will be logged for the given tag. The severity levels to be used in the value field of the preferences are as follows (in order of decreasing severity):

NONE
FATAL
ERROR
WARNING
INFO
DEBUG

The code snippet below displays an example filtering configuration:

    // Create a preferences object where the filtering key-value pairs will be stored.
    std::shared_ptr<CYIPreferences> pPreferences(new CYIPreferences());

    // Set the system level log filtering to filter at an information severity level.
    // This will display logs of all severity except for debug.
    pPreferences->Set("TAG_GENERAL", "INFO");

    // Add a filter for logs tagged with CYIThreadPriv::Join with severity level none.
    // This will filter out all logs with this tag.
    pPreferences->Set("TAG_CYIThreadPriv::Join", "NONE");

    // Set the preferences on the logger.
    CYILogger::SetPreferences(pPreferences);

On top of the filtering options which can be set on the logging system via the CYIPreferences object there are also additional formatting settings which can be specified. See CYILogPolicy documentation for further detail relating to these formatting settings.

Custom Log Policy

The built-in CYILogPolicy implementations log to the platform's console or logging system. More advanced logging may be required by an application such as logging to a file or to a network source. These logging implementations are possible by subclassing CYILogPolicy and then setting the custom CYILogPolicy on the CYILogger. The following code snippet displays the minimum which must be implemented for a custom log policy:

    class MyLogPolicy : public CYILogPolicy
    {
    public:
        // Open and close are blank for this simple implementation, this is where a file would
        // be opened or closed if necessary.
        void Open(){};
        void Close(){};
        bool IsOpen() const {return true;};

    private:
        void _Write(const YI_LOGGING_PARAMS &loggingParams)
        {
            // Writes the pre-formatted log message to the console.
            printf("%s", loggingParams.m_formattedLogMessage.GetData());
        };
    };

    ...
    ...
    ...

    // Create an instance of the log policy implemented above.
    std::shared_ptr<CYILogPolicy> pMyLogPolicy(new MyLogPolicy());
    // Set the custom log policy on the logger. This will replace the default log policy.
    // The logging system will now write using MyLogPolicy.
    CYILogger:SetLogPolicy(pMyLogPolicy);

Classes
class	CYIAndroidLogPolicy
	Logs information to Android's logging system. More...

class	CYIAppleLogPolicy
	Logs information to Apple OS's logging system. More...

class	CYIConsoleLogPolicy
	Logs information to the system's default console. More...

class	CYILogger
	The logging class reports messages to the programmer via a policy. More...

struct	YI_LOGGING_PARAMS
	Data type to hold various bits of information for logging. More...

class	CYILogPolicy

class	CYITizenNaClLogPolicy
	Logs information to Tizen NaCl's logging system. More...

Macros
#define	PRETTYFUNCTION_PLATFORM __PRETTY_FUNCTION__

#define	YI_TRACE_INFO "", "", 0

#define	YI_LOG_CHECK_PARAMETERS(tag, msg, ...)

#define	YI_LOGF(tag, msg, ...) do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_FATAL, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); abort(); } while (0)

#define	YI_LOGE(tag, msg, ...) do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_ERROR, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

#define	YI_LOGW(tag, msg, ...) do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_WARNING, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

#define	YI_LOGI(tag, msg, ...) do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_INFO, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

#define	YI_LOGD(tag, msg, ...) do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_DEBUG, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

Enumerations
enum	YI_LOG_SEVERITY { YI_LOG_NONE = 1, YI_LOG_FATAL, YI_LOG_ERROR, YI_LOG_WARNING, YI_LOG_INFO, YI_LOG_DEBUG }
	Enumeration for the severity levels. More...

Functions
void	YiLog (const char pModuleName, const char pPrettyFunction, uint32_t unLineNumber, const CYIString &rTagName, YI_LOG_SEVERITY eSeverity, const char *pMessage,...)

void	YiLog (const char pModuleName, const char pPrettyFunction, uint32_t unLineNumber, const std::string &rTagName, YI_LOG_SEVERITY eSeverity, const char *pMessage,...)

void	YiLog (const char pModuleName, const char pPrettyFunction, uint32_t unLineNumber, const char pTagName, YI_LOG_SEVERITY eSeverity, const char pMessage,...)

Variables
const uint32_t	YI_LOG_MESSAGE_MAX_SIZE = 8192

Macro Definition Documentation

#define PRETTYFUNCTION_PLATFORM __PRETTY_FUNCTION__

#define YI_LOG_CHECK_PARAMETERS	(	tag,
		msg,
		...
	)

#define YI_LOGD	(	tag,
		msg,
		...
	)	do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_DEBUG, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

Use this macro to log a debug message.

#define YI_LOGE	(	tag,
		msg,
		...
	)	do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_ERROR, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

Use this macro to log an error.

#define YI_LOGF	(	tag,
		msg,
		...
	)	do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_FATAL, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); abort(); } while (0)

Use this macro to log a fatal error.

Warning: This log macro will abort the application.

#define YI_LOGI	(	tag,
		msg,
		...
	)	do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_INFO, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

Use this macro to log some information.

#define YI_LOGW	(	tag,
		msg,
		...
	)	do { YI_LOG_CHECK_PARAMETERS(tag, msg, ##__VA_ARGS__) YiLog(YI_TRACE_INFO, (tag), YI_LOG_WARNING, YI_ENSURE_STRING_LITERAL(msg), ##__VA_ARGS__); } while (0)

Use this macro to log a warning.

#define YI_TRACE_INFO "", "", 0

Enumeration Type Documentation

enum YI_LOG_SEVERITY

Enumeration for the severity levels.

The available severity levels use for controlling the verbosity of information being reported in the log.

Enumerator
YI_LOG_NONE
YI_LOG_FATAL
YI_LOG_ERROR
YI_LOG_WARNING
YI_LOG_INFO
YI_LOG_DEBUG

Function Documentation

void YiLog	(	const char *	pModuleName,
		const char *	pPrettyFunction,
		uint32_t	unLineNumber,
		const CYIString &	rTagName,
		YI_LOG_SEVERITY	eSeverity,
		const char *	pMessage,
			...
	)

CYILogger helper function used by the logging helper macros.

See also: CYILogger

void YiLog	(	const char *	pModuleName,
		const char *	pPrettyFunction,
		uint32_t	unLineNumber,
		const std::string &	rTagName,
		YI_LOG_SEVERITY	eSeverity,
		const char *	pMessage,
			...
	)

void YiLog	(	const char *	pModuleName,
		const char *	pPrettyFunction,
		uint32_t	unLineNumber,
		const char *	pTagName,
		YI_LOG_SEVERITY	eSeverity,
		const char *	pMessage,
			...
	)

Variable Documentation

const uint32_t YI_LOG_MESSAGE_MAX_SIZE = 8192

The maximum size of a log message in bytes.

Detailed Description

Generating Logs

Passing Log Tags

Filtering Ouput

Custom Log Policy

Classes

Macros

Enumerations

Functions

Variables

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation