Modules
	Log functions

	Macros for composing and decomposing report codes from/into its components: type, domain, message.

	Report types

	Report domains

	Report messages

Functions
bool	gcgReport (int code, const char *format=NULL,...)
	Reports an error. To avoid serialization, it is NEVER called for successful operations inside GCGlib. The last report might not have been issued by the last call. Check the error/warning only when a method or function fails. It saves the error/warning information and, if logging is enabled, send an error string to the stream. If the type is GCG_SUCCESS, nothing is sent to the log. Codes of information type might be sent only to the log. Ex. gcgReport(GCG_REPORT_CODE(GCG_ERROR, GCG_MEMORY, GCG_ALLOCATIONERROR)). To report a successful operation, call gcgReport(GCG_SUCCESS). More...

int	gcgGetReport (int sizestring=0, char *extrastring=NULL)
	Returns the code of the last report. Use GCG_REPORT_TYPE(), GCG_REPORT_DOMAIN(), and GCG_REPORT_MESSAGE() to extract the details of the error code. More...

const char *	gcgGetReportString (char typestr=NULL, char domainstr=NULL)
	Gets the strings of the last report. More...

bool	gcgEnableReportLog (int code, bool enable)
	Enables or disables the logging of messages of a specific type or domain. When a type or domain is enabled, the gcgReport() function sends any message of that type or domain to gcgOutputLog(). To enable all types and domains, call gcgEnableReportLog(GCG_REPORT_ALL, true). Likewise, to disable them all call gcgEnableReportLog(GCG_REPORT_ALL, false). To enable all messages of a specific type, INFORMATION for example, call gcgEnableReportLog(GCG_INFORMATION, true). All information messages will be logged. In the other hand, to disable all INFORMATION messages, call gcgEnableReportLog(GCG_INFORMATION, false). To enable all messages of a specific domain, GRAPHICS for example, call gcgEnableReportLog(GCG_DOMAIN_GRAPHICS, true). All messages related to graphics functions will be logged for all types. By default, only the type GCG_ERROR is enabled and reported. More...

Detailed Description

GCGlib provides logging functions, used by the functions and methods to report errors, warnings or events. They are also interesting for programmers to concentrate messages in a unique place. gcgOutputLog() has the same form of the standard C function printf().

GCGlib has three types of messages: errors, warnings and information. When functions or methods check status or fails executing, they report an error or warning depending on the problem severity. Typically, errors prevent the function continue to run. In this case, the result might not be the desired upon the call. In the other hand, warnings are lighter problems that can prevent a step to be executed, but the overall task is performed totally or partially. When there is no error/warning but the library needs to report something, the message type is called information.

All errors and warnings issued by GCGlib can be retrieved by calling gcgGetReport(). To avoid serialization, successful operations inside GCGlib are NEVER reported. The last error might not have been issued by the last call. Check the report code ONLY when a method or function returns a fail. If logging is enabled, a string is sent to the stream, except when the error/warning type is GCG_SUCCESS.

Reports are formed by a TYPE, DOMAIN and MESSAGE codes. The TYPE indicates if the message is an error, warning or information. The DOMAIN tells the main functionality the report is related to: network, memory, video, etc.. The programmer can enable/disable the logging of a specific DOMAIN using gcgEnableLog() or gcgDisableLog() respectively. This helps developers to get information only of the interested functionalities. The MESSAGE code is more specific in relation to the event occurred.

In addition to the error/warnings/information reports, functions and methods might send complementary information to the log stream.

Function Documentation

◆ gcgEnableReportLog()

bool gcgEnableReportLog	(	int	code,
		bool	enable
	)

Enables or disables the logging of messages of a specific type or domain. When a type or domain is enabled, the gcgReport() function sends any message of that type or domain to gcgOutputLog(). To enable all types and domains, call gcgEnableReportLog(GCG_REPORT_ALL, true). Likewise, to disable them all call gcgEnableReportLog(GCG_REPORT_ALL, false). To enable all messages of a specific type, INFORMATION for example, call gcgEnableReportLog(GCG_INFORMATION, true). All information messages will be logged. In the other hand, to disable all INFORMATION messages, call gcgEnableReportLog(GCG_INFORMATION, false). To enable all messages of a specific domain, GRAPHICS for example, call gcgEnableReportLog(GCG_DOMAIN_GRAPHICS, true). All messages related to graphics functions will be logged for all types. By default, only the type GCG_ERROR is enabled and reported.

Parameters

[in]	code	code of the report type or domain that must be sent to the log.
[in]	enable	if true, indicates the type or domain has to be enabled, i.e., generates a message. If false, the type or domain messages are not reported.

Returns: true if the type or domain is successfully enabled or disabled.

See also: gcgReport()

Since: 0.03.14

◆ gcgGetReport()

int gcgGetReport	(	int	sizestring = `0`,
		char *	extrastring = `NULL`
	)

Returns the code of the last report. Use GCG_REPORT_TYPE(), GCG_REPORT_DOMAIN(), and GCG_REPORT_MESSAGE() to extract the details of the error code.

Parameters

[in]	sizestring	maximum number of chars that extrastring supports. Ignored if it is zero.
[out]	extrastring	pointer to a buffer that receives a copy of the last extra message. A NULL value is ignored.

Returns: Integer code of the last report. Use GCG_REPORT_TYPE(), GCG_REPORT_DOMAIN(), and GCG_REPORT_MESSAGE() to extract the details of the error code.

See also: gcgReport(); gcgGetReportString(); GCG_REPORT_TYPE(); GCG_REPORT_DOMAIN(); GCG_REPORT_MESSAGE()

Since: 0.02.0

◆ gcgGetReportString()

const char* gcgGetReportString	(	char **	typestr = `NULL`,
		char **	domainstr = `NULL`
	)

Gets the strings of the last report.

Parameters

[out]	typestr	pointer to a string that should receive the string of last message's TYPE. A NULL value is ignored.
[out]	domainstr	pointer to a string that should receive the string of last message's DOMAIN. A NULL value is ignored.

Returns: the pointer of the char string representing the last message.

See also: gcgReport(); gcgGetReport()

Since: 0.02.0

◆ gcgReport()

bool gcgReport	(	int	code,
		const char *	format = `NULL`,
			...
	)

Reports an error. To avoid serialization, it is NEVER called for successful operations inside GCGlib. The last report might not have been issued by the last call. Check the error/warning only when a method or function fails. It saves the error/warning information and, if logging is enabled, send an error string to the stream. If the type is GCG_SUCCESS, nothing is sent to the log. Codes of information type might be sent only to the log. Ex. gcgReport(GCG_REPORT_CODE(GCG_ERROR, GCG_MEMORY, GCG_ALLOCATIONERROR)). To report a successful operation, call gcgReport(GCG_SUCCESS).

Parameters

[in]	code	code of the report. Use GCG_REPORT_CODE() to form the 32bits code.
[in]	format	pointer to an extra format string to be reported. Usually indicates extra information about the event. It uses the standard C format string as documented for printf(). If NULL, the report text is generated from the code indicated by code.

Returns: returns true if the event was reported by calling gcgOutputLog(). This is affected by gcgEnableReportLog().

See also: gcgSetLogStream(); gcgGetReport(); GCG_REPORT_CODE(); gcgEnableReportLog(); gcgOutputLog()

Since: 0.02.0

Modules

Functions

Detailed Description

Function Documentation

◆ gcgEnableReportLog()

◆ gcgGetReport()

◆ gcgGetReportString()

◆ gcgReport()