System

Detailed Description

class System

This class defines methods to manage the REDnet library.

@related class RNET::IPeer, class RNET::IMessage, class RNET::Adapter, class RNET::Address, class RNET::LogEntry

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

Licensing

REDnet, like any other TechSoft3D products, requires authorization. To authorize REDnet, you must use the RED::ILicense interface from your instance of the resource manager. Authorization has to be done at the very beginning of your REDnet-based application.

Usage

REDnet needs to be initialized before being used. When you’re done using it, it also has to be shutdown properly. This is accomplished using the RNET::System::Initialize and RNET::System::Shutdown methods. At any time, you can know if REDnet was correctly initialized by calling RNET::System::IsInitialized.

For example, your program will probably start with:

RED::String host_name;
RED::Vector< RED::Adapter > host_adapters;

if( RNET::System::Initialize( host_name, host_adapters ) != RED_OK )
{
  // some error processing...
}

and will end with:

RNET::System::Shutdown();

Public Static Functions

static RED_RC 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.

static bool IsInitialized()
Returns:true if RNET::System::Initialize was successfully called, false otherwise.
static RED_RC 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.
static RED_RC 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.
static const RNET::Adapter &GetAdapter()
Returns:the the current network adapter used by REDnet.
static RED_RC 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.

static RED_RC 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.

static void 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.
static RED::String 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.