# class Engine

Engine globals. More...

Full name | `TelEngine::Engine`
Definition | `#include <yatengine.h>`
List of all Methods

Annotated List
Files
Globals
Hierarchy
Index

#### Public Types

- enum RunMode { Stopped = 0, Console = 1, Server = 2, Client = 3, ClientProxy = 4, }
- enum CallAccept { Accept = 0, Partial = 1, Congestion = 2, Reject = 3, }
- enum PluginMode { LoadFail = 0, LoadLate, LoadEarly }

#### Public Methods

- int engineInit ()
- int engineCleanup ()
- int run ()
- inline void setHook (MessagePostHook* hook, bool remove = false)
- int usedPlugins ()
- inline unsigned int messageCount ()
- inline unsigned int handlerCount ()
- bool loadPluginDir (const String& relPath)

#### Public Static Methods

- static int main (int argc, const char** argv, const char** env, RunMode mode = Console, EngineLoop loop = 0, bool fail = false)
- static void help (bool client, bool errout = false)
- static Engine* self ()
- static RunMode mode ()
- static inline CallAccept accept ()
- static inline void setAccept (CallAccept ca)
- static inline const TokenDict* getCallAcceptStates ()
- static inline bool clientMode ()
- static bool Register (const Plugin* plugin, bool reg = true)
- static inline const String& nodeName ()
- static inline const String& sharedPath ()
- static String configFile (const char* name, bool user = false)
- static const String& configPath (bool user = false)
- static inline const String& configSuffix ()
- static inline const String& modulePath ()
- static void extraPath (const String& path)
- static void userPath (const String& path)
- static inline const String& moduleSuffix ()
- static const char* pathSeparator ()
- static const Configuration& config ()
- static unsigned int runId ()
- static inline const NamedList& runParams ()
- static void init ()
- static bool init (const String& name)
- static void halt (unsigned int code)
- static bool restart (unsigned int code, bool gracefull = false)
- static bool exiting ()
- static bool install (MessageHandler* handler)
- static bool uninstall (MessageHandler* handler)
- static bool enqueue (Message* msg)
- static inline bool enqueue (const char* name, bool broadcast = false)
- static bool dispatch (Message* msg)
- static bool dispatch (Message& msg)
- static bool dispatch (const char* name, bool broadcast = false)
- static void pluginMode (PluginMode mode)
- static const ObjList* events (const String& type)
- static void clearEvents (const String& type)
- static SharedVars& sharedVars ()

#### Protected Methods

- ~Engine ()
- bool loadPlugin (const char* file, bool local = false, bool nounload = false)
- void loadPlugins ()
- void initPlugins ()

## Detailed Description

This class holds global information about the engine. Note: this is a singleton class.

enum RunMode { Stopped = 0, Console = 1, Server = 2, Client = 3, ClientProxy = 4, }

### RunMode

Running modes - run the engine as Console, Client or Server.

enum CallAccept { Accept = 0, Partial = 1, Congestion = 2, Reject = 3, }

### CallAccept

enum PluginMode { LoadFail = 0, LoadLate, LoadEarly }

### PluginMode

Plugin load and initialization modes. Default is LoadLate that initailizes the plugin after others. LoadEarly will move the plugin to the front of the init order. LoadFail causes the plugin to be unloaded.

int main (int argc, const char** argv, const char** env, RunMode mode = Console, EngineLoop loop = 0, bool fail = false)

### main

[static]

Main entry point to be called directly from a wrapper program

Parameters:

argc | Argument count
argv | Argument array
env | Environment variables
mode | Mode the engine must run as - Console, Client or Server
loop | Callback function to the main thread's loop
fail | Fail and return after parsing command line arguments

Returns: Program exit code

void help (bool client, bool errout = false)

### help

[static]

Display the help information on console

Parameters:

client | Display help for client running mode
errout | Display on stderr intead of stdout

int engineInit ()

### engineInit

Initialize the engine

Returns: Error code, 0 for success

int engineCleanup ()

### engineCleanup

Do engine cleanup

Returns: Error code, 0 for success

int run ()

### run

Run the engine.

Returns: Error code, 0 for success

Engine* self ()

### self

[static]

Get a pointer to the unique instance.

Returns: A pointer to the singleton instance of the engine

RunMode mode ()

### mode

[static]

Get the running mode of the engine

Returns: Engine's run mode as enumerated value

inline CallAccept accept ()

### accept

[static]

Get call accept status

Returns: Engine's call accept status as enumerated value

inline void setAccept (CallAccept ca)

### setAccept

[static]

Set call accept status

Parameters:

ca | New call accept status as enumerated value

inline const TokenDict* getCallAcceptStates ()

### getCallAcceptStates

[static]

Get call accept states

Returns: states Pointer to the call accept states TokenDict

inline bool clientMode ()

### clientMode

[static]

Check if the engine is running as telephony client

Returns: True if the engine is running in client mode

bool Register (const Plugin* plugin, bool reg = true)

### Register

[static]

Register or unregister a plugin to the engine.

Parameters:

plugin | A pointer to the plugin to (un)register
reg | True to register (default), false to unregister

Returns: True on success, false on failure

inline const String& nodeName ()

### nodeName

[static]

Get the server node name, should be unique in a cluster

Returns: Node identifier string, defaults to host name

inline const String& sharedPath ()

### sharedPath

[static]

Get the application's shared directory path

Returns: The base path for shared files and directories

String configFile (const char* name, bool user = false)

### configFile

[static]

Get the filename for a specific configuration

Parameters:

name | Name of the configuration requested
user | True to build a user settings path

Returns: A full path configuration file name

const String& configPath (bool user = false)

### configPath

[static]

Get the system or user configuration directory path

Parameters:

user | True to get the user settings path

Returns: The directory path for system or user configuration files

inline const String& configSuffix ()

### configSuffix

[static]

Get the configuration file suffix

Returns: The suffix for configuration files

inline const String& modulePath ()

### modulePath

[static]

The module loading path

void extraPath (const String& path)

### extraPath

[static]

Add a relative extra module loading path. The list is empty by default but can be filled by a main program before calling main()

Parameters:

path | Relative path to extra modules to be loaded

void userPath (const String& path)

### userPath

[static]

Set the per user application data path. This method must be called by a main program before calling main() or help() Path separators are not allowed. The default is taken from CFG_DIR.

Parameters:

path | Single relative path component to write user specific data

inline const String& moduleSuffix ()

### moduleSuffix

[static]

Get the module filename suffix

Returns: The suffix for module files

const char* pathSeparator ()

### pathSeparator

[static]

Get the canonical path element separator for the operating system

Returns: The operating system specific path element separator

const Configuration& config ()

### config

[static]

The global configuration of the engine. You must use this resource with caution. Note that sections [general], [modules], [preload] and [postload] are reserved by the engine. Also [telephony] is reserved by the drivers.

Returns: A reference to the read-only engine configuration

unsigned int runId ()

### runId

[static]

Get a - supposedly unique - instance ID

Returns: Unique ID of the current running instance

inline const NamedList& runParams ()

### runParams

[static]

Get the engine parameters specific to this run.

Returns: A reference to the list of run specific parameters

void init ()

### init

[static]

Reinitialize the plugins

bool init (const String& name)

### init

[static]

Reinitialize one plugin

Parameters:

name | Name of the plugin to initialize, emplty, "*" or "all" to initialize all

Returns: True if plugin(s) were reinitialized

void halt (unsigned int code)

### halt

[static]

Stop the engine and the entire program

Parameters:

code | Return code of the program

bool restart (unsigned int code, bool gracefull = false)

### restart

[static]

Stop and restart the engine and the entire program

Parameters:

code | Return code of the program
gracefull | Attempt to wait until no plugin is busy

Returns: True if restart was initiated, false if exiting or no supervisor

bool exiting ()

### exiting

[static]

Check if the engine is currently exiting

Returns: True if exiting, false in normal operation

bool install (MessageHandler* handler)

### install

[static]

Installs a handler in the dispatcher.

Parameters:

handler | A pointer to the handler to install

Returns: True on success, false on failure

bool uninstall (MessageHandler* handler)

### uninstall

[static]

Uninstalls a handler drom the dispatcher.

Parameters:

handler | A pointer to the handler to uninstall

Returns: True on success, false on failure

bool enqueue (Message* msg)

### enqueue

[static]

Enqueue a message in the message queue for asynchronous dispatching

Parameters:

msg | The message to enqueue, will be destroyed after dispatching

Returns: True if enqueued, false on error (already queued)

inline bool enqueue (const char* name, bool broadcast = false)

### enqueue

[static]

Convenience function. Enqueue a new parameterless message in the message queue

Parameters:

name | Name of the parameterless message to put in queue
broadcast | Broadcast flag, true if handling the mesage must not stop it

Returns: True if enqueued, false on error (already queued)

bool dispatch (Message* msg)

### dispatch

[static]

Synchronously dispatch a message to the registered handlers

Parameters:

msg | Pointer to the message to dispatch

Returns: True if one handler accepted it, false if all ignored

bool dispatch (Message& msg)

### dispatch

[static]

Synchronously dispatch a message to the registered handlers

Parameters:

msg | The message to dispatch

Returns: True if one handler accepted it, false if all ignored

bool dispatch (const char* name, bool broadcast = false)

### dispatch

[static]

Convenience function. Dispatch a parameterless message to the registered handlers

Parameters:

name | The name of the message to create and dispatch
broadcast | Broadcast flag, true if handling the mesage must not stop it

Returns: True if one handler accepted it, false if all ignored

inline void setHook (MessagePostHook* hook, bool remove = false)

### setHook

Install or remove a hook to catch messages after being dispatched

Parameters:

hook | Pointer to a post-dispatching message hook
remove | Set to True to remove the hook instead of adding

int usedPlugins ()

### usedPlugins

Get a count of plugins that are actively in use

Returns: Count of plugins in use

inline unsigned int messageCount ()

### messageCount

Get the number of messages waiting in the queue

Returns: Count of messages in the queue

inline unsigned int handlerCount ()

### handlerCount

Get the number of handlers in the dispatcher

Returns: Count of handlers

bool loadPluginDir (const String& relPath)

### loadPluginDir

Loads the plugins from an extra plugins directory or just an extra plugin

Parameters:

relPath | Path to the extra directory, relative to the main modules

Returns: True if the plugin was loaded or the directory could at least be opened

void pluginMode (PluginMode mode)

### pluginMode

[static]

Set the load and init mode of the currently loading Plugin

Parameters:

mode | Load and init mode, default LoadLate

const ObjList* events (const String& type)

### events

[static]

Retrive the list of captured events of a specific type

Parameters:

type | Type of captured events, an empty name returns engine events

Returns: List containing captured events of specified type, NULL if not found

void clearEvents (const String& type)

### clearEvents

[static]

Clear the list of captured events of a specific type

Parameters:

type | Type of captured events, an empty name clear engine events

SharedVars& sharedVars ()

### sharedVars

[static]

Access the engine's shared variables

Returns: Reference to the static variables shared between modules

~Engine ()

### ~Engine

[protected]

Destroys the engine and everything. You must not call it directly, run() will do it for you.

bool loadPlugin (const char* file, bool local = false, bool nounload = false)

### loadPlugin

[protected]

Loads one plugin from a shared object file

Parameters:

file | Name of the plugin file to load
local | Attempt to keep symbols local if supported by the system
nounload | Never unload the module from memory, finalize if possible

Returns: True if success, false on failure

void loadPlugins ()

### loadPlugins

[protected]

Loads the plugins from the plugins directory

void initPlugins ()

### initPlugins

[protected]

Initialize all registered plugins

Generated by: paulc on bussard on Fri Dec 21 16:28:34 2012, using kdoc 2.0a54.