Incubator/DataBundleHelper/Detailed specifications

From TrainzOnline
Jump to: navigation, search

DataBundleHelper library detailed specification

'The Incubator/DataBundleHelper library has been released in version v7 - 21/01/2009 - in beta SP2 build 38841.

The specifications below are the release specications and should be consider as definitive. Future versions should be upward compatible and may include new functions or more detailed return codes if needed.

Interface specification

Library interface specification v7 - 21.01.2009 - available from beta SP2 build 38841.


Library is called through standard library LibraryCall interface :


public string LibraryCall(string sFunction, string[] sParms1, GSObject[] oParms) ;


information below gives for each function implemented, the expected parameters and the string returned value. In case of common errors, common error string will be returned :

string sError9 = "9 - function not found" ;

string sError8 = "8 - invalid function parameters" ;

string sError7 = "7 - function not found - library not available" ;



GetLastRetCode


returns last request return explanation string under format : code - explanation.

sFunction GetLastRetCode
sParms[] no string parameter
oParms[] no GSObject parameter
sRet last request return explanation string



SetDebugMode


Activates or deactivates library debug mode. When debug mode is active, all calls to the library will be logged. At startup, debug mode is deactivated. When testing a new rule using the library, it may be helpfull to activate debug mode.

sFunction SetDebugMode
sParm[0] "true" or "false"
oParms[] no GSObject parameter
sRet ""



RegisterDataBundle


register a new DataBundle in the library. if the DataBundle definition allready exists, it increases its registration count and updates description string and KUID string

sFunction RegisterDataBundle
sParm[0] short unique token string identifying the DataBundle type
sParm[1] long description string for the DataBundle type
sParm[2] KUID string for the DataBundle icon
oParms[] no object parameter
sRet ""



UnregisterDataBundle


Unregister a DataBundle from the library. It decreases the DataBundle registration count and removes the DataBundle definition if the DataBundle registration count is zero.

sFunction UnregisterDataBundle
sParm[0] short unique token string identifying the DataBundle type.
oParms[] no object parameter
sRet ""



IsDataBundleRegistered


Searches for a DataBundle definition in the library and returns its registration count.

sFunction IsDataBundleRegistered
sParm[0] short unique token string identifying the DataBundle type
oParms[] no object parameter
sRet "n" where n is the registration count



MakeDataBundle


Adds the registered DataBundle short unique token to the soup passed as object parameter.

sFunction MakeDataBundle
sParm[0] short unique token string identifying the DataBundle type.
oParm[0] databundle soup
sRet ""



ClearDataBundleSoup


Reverse MakeDataBundle processing by retracting from the DataBundle soup all extensions tags added by MakeDataBundle.

sFunction ClearDataBundleSoup
sParms[] no string parameter
oParm[0] Databundle soup
sRet ""



GetDataBundleType


Returns the short unique token string from the DataBundle soup passed as object parameter.

sFunction GetDataBundleType
sParms[] no string parameter
oParm[0] databundle soup
sRet short unique token string identifying the DataBundle type or ""



GetDataBundleDesc


Returns the description string from the DataBundle soup passed as object parameter.

sFunction GetDataBundleDesc
sParms[] no string parameter
oParm[0] databundle soup
sRet string description associated to the DataBundle type or ""



GetDataBundleIcon


Returns the DataBundle KUID string icon.

sFunction GetDataBundleIcon
sParms[] no string parameter
oParm[0] databundle soup
sRet string KUID icon to use for this DataBundle or ""



RegisterDataHandler


Registers a rule as a DataHandler for a DataBundle and operation.

sFunction RegisterDataHandler
sParm[0] short unique token string identifying the DataBundle type
sParm[1] name of operation to register or "" for any operations on DataBundle
sParm[2] priority level
oParm[0] gameobject to register for callback

the gameobject subclass used should either be a ScenarioBehavior rule or a Library object.

sRet ""



UnregisterDataHandler


Unregister from the library a rule as a DataHandler for a DataBundle and operation

sFunction UnregisterDataHandler
sParm[0] short unique token string identifying the DataBundle type
sParm[1] name of operation to register or "" for any operations on DataBundle
oParm[0] gameobject used to register
sRet ""



IsDataHandlerRegistered


Searches for a DataHandler in the library and returns its registration count.

sFunction IsDataHandlerRegistered
sParm[0] short unique token string identifying the DataBundle type
sParm[1] name of operation to register or "" for any operations on DataBundle
sParm[2] priority level to check or -1 for any priority level
oParm[0] gameobject to check for callback or null for any gameobject
sRet "n" where n is the registration count either 0 or 1.



ExecuteOperation


ExecuteOperation will call all the DataHandler registered for the DataBundle and operation with priority defined less or equals than priority level passed as a parameter. The calls are ordered following priority defined ascendant order.
For example, if operation A is called on databundle B with priority level 256, all data handlers for operation A on databundle B with priority 0 to 256 will be selected. Handlers will be called in ascendant priority order until there is no more handlers to be called or one handler returns a no blank string return code which in this case terminates the operation.

sFunction ExecuteOperation
sParm[0] name of operation to execute
sParm[1] priority level
oParm[0] databundle soup
sRet value returned by the last rule scenariobehavior callback called.


if there is one or more DataHandler for the DataBundle & operation requested, the DataHandler objects will be called back through : <DataHandler object>.LibraryCall("DataHandlerCallBack",string[] sParm, GSObject[] oParm) with

sFunction DataHandlerCallBack
sParm[0] sOperation = name of operation being executed
sParm[1] sToken = short token string of current DataBundle soup
sParm[2] sPrio = priority level of DataHandler callback defined at registration
oParm[0] databundle soup
sRet string return value to LibraryCall will be passed back as string return value for ExecuteOperation. The string return value should be "" for a completed operation.

When several DataBundleHandler are eligible for the same DataBundle, they are called one after one in the priority order defined. If one DataBundleHandler returns a string return value not equal to "" the chaining of calls is stopped and the not empty string return code is returned. if all the DataBundleHandler are called the empty string return code is returned.



Other general information



The library is available as an independant asset to be loaded through standard World.GetLibrary(...) interface.

Library kuid to use is : <kuid:401543:1181>

There is also a dbhelper.gs scriptfile included with the library asset that defines a dbhelper static class with public procedures to call the different functions included in the library. dbhelper.gs usage is recommanded for future upgrade compatibility. A copy of the dbhelper.gs scriptfile can be included in any asset using the databundle library.
To work, you need to define in the asset kuidtable : dbhelper <kuid:401543:1181>


dbhelper interface :

 static class dbhelper
 {
 // constantes
 define string sRet7 = "7 - function not found - library not available" ;
 // interface publique 
 public void Init(Asset p_asset) ; 
 public bool IsLibraryAvailable(void) ;
 public string GetLastRetCode(void) ;
 public void SetDebugMode(bool bDebug) ;
 public string RegisterDataBundle(string sToken,string sDesc, string sKUIDicon) ;
 public string UnregisterDataBundle(string sToken) ;
 public int IsDataBundleRegistered(string sToken) ;
 public string MakeDataBundle(string sToken, Soup oSoup) ;
 public string ClearDataBundleSoup(Soup oSoup) ;
 public string GetDataBundleType(Soup oSoup) ;
 public string GetDataBundleDesc(Soup oSoup) ;
 public string GetDataBundleIcon(Soup oSoup) ;
 public string RegisterDataHandler(string sToken,string sOperation,int iPrioLevel,GameObject oGo) ;
 public string UnregisterDataHandler(string sToken,string sOperation,int iPrioLevel, GameObject oGo) ;
 public int IsDataHandlerRegistered(string sToken,string sOperation,int iPrioLevel, GameObject oGo) ;
 public int IsDataHandlerRegistered(string sToken, string sOperation) ;
 public string ExecuteOperation(string sOperation, int iPrioLevel, Soup oSoup) ;
 //
 ...
 }

SetProperties(...)/GetProperties() restore and save procedure

As DataBundle and DataHandler definition are generally registered at startup in the .init(...) or .setproperties(...) procedure or in a "world", "moduleinit" message handler, the library will not save/restore DataBundle and DataHandler definitions in its own SetProperties(...)/GetProperties() procedure. This means that rules or other script code using the library are in charge of saving/restoring their registration data in save/restore processing.



Personal tools