Cross-Platform C++

ot
class System

#include "ot/base/System.h"

Class module providing useful system-level functions as well as providing a well-known and accessible root from which to navigate to other essential services.




Method Summary
static String GetAppMessage(const String& org, const String& app, size_t messageID, const char* szDefault)
         Retrieves the text for a user-defined message.
static String GetEnvironmentString(const String& name)
         Returns the specified environment variable as a String.
static const String& GetLineEnding()
         Returns a String containing the line ending character(s) for the platform.
static RefPtr< MessageFactory > GetMessageFactory()
         Returns the MessageFactory for the application if one has been previously installed.
static ObjectManager& GetObjectManager()
         Returns a reference to the global ObjectManager, which can be used to hold instances of reference-counted objects for the lifetime of the application.
static String GetProperty(const String& name)
         Returns the system property with the supplied name.
static String GetProperty(const String& name, const String& defaultValue)
         Returns the system property with the supplied name.
static bool GetPropertyBool(const String& name, bool bDefault)
         Returns the value of the named property as a boolean value.
static long GetPropertyLong(const String& name, long defaultValue)
         Returns the value of the named property as a long integer.
static String GetSysMessage(const String& lib, size_t messageID, const char* szDefault)
         Retrieves the text for a system message.
static unsigned long GetVersion()
         Returns the current version of the OpenTop library.
static String GetVersionAsString()
         Returns the version of OpenTop as a formatted string.
static void SetMessageFactory(MessageFactory* pFactory)
         Sets the MessageFactory global object.
static void SetProperty(const String& name, const String& value)
         Creates a system property with the specified name and assigns it the supplied value.
static void SetPropertyBool(const String& name, bool bSet)
         Creates a system property with the specified name and assigns it the supplied value.
static void SetPropertyLong(const String& name, long value)
         Creates a system property with the specified name and assigns it the supplied value.
static void Terminate()
         Called by the application when it is about to terminate.

Method Detail

GetAppMessage

static String GetAppMessage(const String& org,
                            const String& app,
                            size_t messageID,
                            const char* szDefault)
Retrieves the text for a user-defined message. This function is can be used by applications or libraries built on top of OpenTop to access internationalized error and informational messages.

The requested message is identified by the 3 parameters: org, app and messageID. These are passed to the application-supplied MessageFactory to locate the requested message. If the MessageFactory cannot provide the message then szDefault is converted into a String and returned.

Parameters:
org - name of the organization which created the application or library. This can be any name except elcel which is reserved.
app - name of the application or library which is requesting the message
messageID - identifier for the message (unique within the library specified by app)
szDefault - null-terminated ASCII string containing the default message text
Returns:
the requested message text or the default value if no message is available.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetEnvironmentString

static String GetEnvironmentString(const String& name)
Returns the specified environment variable as a String.

Parameters:
name - the name of the environment variable to return
Returns:
the value of the environment variable name or an empty String if the environment variable is not set
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetLineEnding

static const StringGetLineEnding()
Returns a String containing the line ending character(s) for the platform.

Returns:
A String containing the line-ending characters. On Unix this is '\n', on Windows it is '\r\n'.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetMessageFactory

static RefPtr< MessageFactoryGetMessageFactory()
Returns the MessageFactory for the application if one has been previously installed.

Returns:
The previously installed MessageFactory or null if no MessageFactory has been installed.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetObjectManager

static ObjectManagerGetObjectManager()
Returns a reference to the global ObjectManager, which can be used to hold instances of reference-counted objects for the lifetime of the application.

Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetProperty

static String GetProperty(const String& name)
Returns the system property with the supplied name.

Parameters:
name - the name of the property
Returns:
the requested property or the empty string if it doesn't exist.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetProperty

static String GetProperty(const String& name,
                          const String& defaultValue)
Returns the system property with the supplied name.

Parameters:
name - the name of the property
defaultValue - the default value
Returns:
the requested property or defaultValue if it doesn't exist.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetPropertyBool

static bool GetPropertyBool(const String& name,
                            bool bDefault)
Returns the value of the named property as a boolean value.

Parameters:
name - the name of the property
bDefault - the default value
Returns:
true if the property is set to "true" or "1"; false if it is set to any other value. If the property is not set the bDefault value is returned.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetPropertyLong

static long GetPropertyLong(const String& name,
                            long defaultValue)
Returns the value of the named property as a long integer.

Parameters:
name - the name of the property
defaultValue - the default value
Returns:
the property as a long integer if it has been set; returns defaultValue otherwise.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetSysMessage

static String GetSysMessage(const String& lib,
                            size_t messageID,
                            const char* szDefault)
Retrieves the text for a system message. Uses the application-supplied MessageFactory to locate the requested message. If the MessageFactory cannot provide the message then szDefault is converted into a String and returned.

This function is used throughout the OpenTop library to access internationalized error and informational messages.

Parameters:
lib - name of the library component which is requesting the message
messageID - identifier for the message (unique within the library specified by lib)
szDefault - null-terminated ASCII string containing the default message text
Returns:
the requested message text or the default value if no message is available.
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetVersion

static unsigned long GetVersion()
Returns the current version of the OpenTop library. The version number is made up of a major version, a minor version and a minor release number combined together to make an unsigned long integer like this:

   unsigned long version = (_OPENTOP_MAJOR_VERSION * 100000)
                         + (_OPENTOP_MINOR_VERSION * 1000)
                         + _OPENTOP_MINOR_RELEASE;

The OpenTop version may also be obtained at compile time from the _OPENTOP_VERSION macro.

Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

GetVersionAsString

static String GetVersionAsString()
Returns the version of OpenTop as a formatted string. The returned string takes the form "a.b.c" where -a is the major version (_OPENTOP_MAJOR_VERSION) -b is the minor version number (_OPENTOP_MINOR_VERSION) -c is the minor release number (_OPENTOP_MINOR_RELEASE)

Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

SetMessageFactory

static void SetMessageFactory(MessageFactory* pFactory)
Sets the MessageFactory global object. Installs a MessageFactory that will be used for subsequent message retrieval.

To ensure that the passed object exists for as long as the application needs it, the MessageFactory object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination.

Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

SetProperty

static void SetProperty(const String& name,
                        const String& value)
Creates a system property with the specified name and assigns it the supplied value.

Parameters:
name - the name of the property
value - the required value of the property
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

SetPropertyBool

static void SetPropertyBool(const String& name,
                            bool bSet)
Creates a system property with the specified name and assigns it the supplied value.

Parameters:
name - the name of the property
bSet - the required value of the property
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

SetPropertyLong

static void SetPropertyLong(const String& name,
                            long value)
Creates a system property with the specified name and assigns it the supplied value.

Parameters:
name - the name of the property
value - the required value of the property
Multi-threaded considerations:
Can safely be called from multiple concurrent threads.

Terminate

static void Terminate()
Called by the application when it is about to terminate. Releases any resources acquired during execution of the application including references to lazily instantiated global objects. Once Terminate() has been called, further use of OpenTop classes is not supported.

It is always a good idea for an application to call Terminate() to allow the OpenTop library to perform clean-up operations. This is especially true when using OpenTop threads because System::Terminate() is responsible for ensuring that all user threads have terminated before it returns to the caller.

It is also a good idea to ensure Terminate() is called correctly when using a memory-leak checker such as BoundsChecker or the debug version of the Microsoft C Run-time Library.

For safety, if the application has created daemon threads which are still active, Terminate() will not free the memory for global objects. The daemon threads will terminate when the process terminates.

To ensure that Terminate() is called even after an application throws an exception, it is recommended that the application make use of the SystemMonitor class rather than attempting to call Terminate() directly.

See also:
SystemMonitor


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements