View source for Incubator/DataBundleHelper/Detailed specifications

==DataBundleHelper library detailed specification==

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

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.
 
{| border = "1"
|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.

{| border = "1"
|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

{| border = "1"
|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.

{| border = "1"
|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.

{| border = "1"
|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.

{|  border = "1"
|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.

{|  border = "1"
|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.

{|  border = "1"
|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.

{|  border = "1"
|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.

{|  border = "1"
|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.

{|  border = "1"
|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

{| border = "1"
|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.

{| border = "1"
|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.<br>
''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.'' 

{| border = "1"
|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

{| border = "1"
|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 : &lt;kuid:401543:1181&gt;

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.<br>
To work, you need to define in the asset kuidtable : dbhelper  &lt;kuid:401543:1181&gt;  


dbhelper interface :

<tt>
  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) ;
  //
  ...
  }
</tt>

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.


----