class RNET::System

This class defines methods to manage the REDnet library. More...

#include <RNETSystem.h>

Public static functions:

static RED_RC	EnableLog ( bool iEnabled, const RED::String & iFile, LOG_CALLBACK iCallback = NULL, void * iCallbackUserData = NULL )
static const RNET::Adapter &	GetAdapter ( )
static RED::String	GetLogPath ( )
static RED_RC	GetREDNETErrorMessage ( RED::String & oMessage, RED_RC iRC )
static RED_RC	Initialize ( RED::String & oHostName, RED::Vector< RNET::Adapter > & oHostAdapters )
static bool	IsInitialized ( )
static void	Log ( const RNET::LogEntry & iLogEntry )
static RED_RC	SetAdapter ( const RNET::Adapter & iAdapter )
static RED_RC	Shutdown ( )

Detailed description:

This class defines methods to manage the REDnet library.

All the class methods are static. Therefore, the class can't be instantiated.

Functions documentation

public static RED_RC RNET::System::EnableLog	(	bool	iEnabled,
		const RED::String &	iFile,
		LOG_CALLBACK	iCallback = NULL,
		void *	iCallbackUserData = NULL
	)

Enables the log of network events.

Events logging can be enabled before calling RNET::System::Initialize.

Network events are filtered and not all of them are logged. Logged events can be sorted into categories:

Information: + Peer/System start/shutdown + socket opening/creation + socket closing...

Warnings: + non-fatal network errors

Errors: + fatal network errors

Log entries follow the format of RED::LogEntry. You can decide to log your own additional events by calling the Log method.

Log entries are appended at the end of the supplied file (except if iCallback is defined). If you want a brand new log, you have to delete the file prior to the call.

The call checks the validity of iFile (if no callback set). If the file can't be accessed to, RED_NET_LOG_FAIL is returned. Hence, subsequent calls to Log will fail without returning anything.

If iCallback is defined, the callback is called upon each new log entry and fully bypass the file. It's then up to the user to decide what to do with log entries.

If both iFile and iCallback are valid, the iCallback will be used.

Parameters:

iEnabled	true to enable log, false to disable it.
iFile	path to the file where log entries are output.
iCallback	user supplied callback. Default is NULL.
iCallbackUserData	additional data to be passed to iCallback. Default is NULL.

Returns:

RED_OK on success,
RED_BAD_PARAM if both iFile is empty and iCallback is NULL,
RED_NET_LOG_FAIL if iFile is defined (but not iCallback) and the file can't be accessed,
RED_FAIL otherwise.

public static const RNET::Adapter & RNET::System::GetAdapter

(

)

Returns:

the the current network adapter used by REDnet.

public static RED::String RNET::System::GetLogPath

(

)

Gets the path to the log file.

If either log is disabled, or callback is used, the returned path is empty. Otherwise, the returned path is the complete path (including the file name) to the log file.

Returns:

the path to the log file.

public static RED_RC RNET::System::GetREDNETErrorMessage	(	RED::String &	oMessage,
		RED_RC	iRC
	)

Gets the formated message string from a REDnet error code.

This function also works with RED_RC error codes.

Parameters:

oMessage:	formated message string corresponding to the given REDnet error code.
iRC:	the RED_RC error code (may also be a RED_RC value).

Returns:

RED_OK on success,
RED_FAIL otherwise.

public static RED_RC RNET::System::Initialize	(	RED::String &	oHostName,
		RED::Vector< RNET::Adapter > &	oHostAdapters
	)

Initializes the REDnet library.

REDnet must be initialized using that function before calling any other API method. Otherwise, API calls will fail returning RED_NET_NOT_INITIALIZED.

The call returns the host name and the list of available network adapters. By default, REDnet uses the first adapter of the list, but if you want to set your preferred adapter instead, just call RNET::System::SetAdapter passing that adapter.

Parameters:

oHostName	host name.
oHostAdapters	list of available host adapters.

Returns:

a RED_RC code describing the result.

public static bool RNET::System::IsInitialized

(

)

Returns:

true if RNET::System::Initialize was successfully called, false otherwise.

public static void RNET::System::Log

(

const RNET::LogEntry &

iLogEntry

)

Logs a custom event.

This method sends the given log entry to the logging system.

The method is silent and returns nothing. The only way to check for a valid log output is to test the code returned by EnableLog.

Parameters:

iLogEntry

log entry.

public static RED_RC RNET::System::SetAdapter

(

const RNET::Adapter &

iAdapter

)

Sets the network adapter to use.

Parameters:

iAdapter

reference to the adapter to use.

Returns:

a RED_RC code describing the result.

public static RED_RC RNET::System::Shutdown

(

)

Terminates the REDnet module.

Once terminated, REDnet can be initialized again by calling RNET::System::Initialize.

Returns:

a RED_RC code describing the result.