Changes between Initial Version and Version 1 of APIFunctions

Timestamp:

Jun 1, 2009, 5:24:28 AM (15 years ago)

Author:

IgorL

Comment:

--

APIFunctions

@@ +1 @@
+== API functions ==
+
+
+API function means all functions that you can use for your XML Server application work. These are all functions from "'''modules/global/inc/apiFunctions.inc.php'''" and "'''modules/global/inc/customFunctions.inc.php'''" files.
+
+"'''apiFunctions.inc.php'''" file contains unchangeable functions, and "'''customFunctions.inc.php'''" contains functions that depend on script structure (integrational functions). By default these functions are configured for "Dolphin" script.
+
+
+"'''apiFunctions.inc.php'''" file functions:
+
+    1. '''parseXml'''
+
+{{{
+/**
+* Parse XML template using specified information.
+* @param aXmlTemplates - array with XML templates grouped by type.
+* @param ... - variable amount of incoming parameters with information to be used in the process of
+parsing.
+* @return $sContent - XML entry
+*/
+function parseXml($aXmlTemplates){ ... }
+}}}
+
+This function accepts the XML entry template, inserts the given values and returns the resulting XML entry:
+
+{{{
+$aXmlTemplates = array (
+"result" => array (
+1 => "<result value=\"#1#\" />",
+2 => "<result value=\"#1#\" status=\"#2#\" />"
+)
+);
+$sContents = parseXml($aXmlTemplates["result"], "some_value", "success");
+echo $sContents;
+///////////////////
+<result value="some_value" status="success" />
+}}}
+
+    2. '''makeGroup'''
+
+{{{
+/**
+* Group specified content.
+* @param sXmlContent - content to be grouped.
+* @param sXmlGroup - group name.
+*/
+function makeGroup($sXmlContent, $sXmlGroup = "ray"){ ... }
+}}}
+
+This function accepts some XML content that should be grouped, group name and returns the grouped XML entries:
+
+{{{
+$sEntries = "<item value=\"some_value\" /><item value=\"another_value\" />";
+$sContents = makeGroup($sEntries,"items");
+echo $sContents;
+///////////////////
+<items><item value="some_value" /><item value="another_value" /></items>
+}}}
+
+    3. '''setSettingValue'''
+
+{{{
+/**
+* Saves the setting value in the config.xml file of the specified widget.
+* @param sWidget - widget's name.
+* @param sSettingKey - setting's key.
+* @param sSettingValue - new value for specified setting.
+*/
+function setSettingValue($sWidget, $sSettingKey, $sSettingValue){ ... }
+}}}
+
+This function sets the value of a given key setting in a given widget configuration file 
+
+{{{
+([widget_name]/xml/config.xml):
+[some_widget]/xml/config.xml before:
+<items><item key="some_key"><![CDATA[some_value]]></item></items>
+setSettingValue("some_widget", "some_key", "another_value");
+[some_widget]/xml/config.xml after:
+<items><item key="some_key"><![CDATA[another_value]]></item></items>
+}}}
+
+    4. '''getSettingValue'''
+
+{{{
+/**
+* Gets the setting value from config.xml file.
+* @param sWidget - widget's name.
+* @param $sSettingKey - setting's name.
+*/
+function getSettingValue($sWidget, $sSettingKey, $bFullReturn = false){ ... }
+}}}
+
+This function gets the value of a given key setting from a given widget configuration file 
+
+{{{
+([widget_name]/xml/config.xml):
+[some_widget]/xml/config.xml:
+<items><item key="some_key"><![CDATA[some_value]]></item></items>
+$sValue = getSettingValue("some_widget", "some_key");
+$aValue = getSettingValue("some_widget", "some_key", true);
+echo $sValue;
+print_r($aValue);
+/////////////////////
+some_value
+Array('value' => "some_value", 'status' => "success")
+}}}
+
+    5. '''getRMSUrl'''
+
+{{{
+/**
+* returns the RMS Url to the given application
+* @param sApplication - application name.
+* @return sRMSUrl - RMS Url.
+*/
+function getRMSUrl($sApplication){ ... }
+}}}
+
+This function returns the full url to the RMS application by given server application name:
+
+{{{
+$sRMSUrl = getRMSUrl("chat");
+echo $sRMSUrl;
+/////////////////////
+rtmp://195.132.156.124:1935/chat/
+}}}
+
+    6. '''updateOnline'''
+
+{{{
+/**
+* Update online users
+* Clear TrackUsers table if it is necessary.
+* @param sId - user ID to update status
+* @param sStatus - user new status
+*/
+function updateOnline($sId = "", $sStatus = ""){ ... }
+}}}
+
+This function updates online status for a user with a given ID and resets his online status, if there is one. Status can be "offline"/"online". It also deletes all tracks for users that exceed the delete timeout.
+
+
+    7. '''getOnline'''
+
+{{{
+/**
+* get online users
+* @param aRange - users IDs range to select from
+* @param $bInRange - get users that in(not in) range
+*/
+function getOnline($aRange = array(), $bInRange = true) { ... }
+}}}
+
+This function retrieves the currently online members array. If $aRange variable is not empty this function retrieves the currently online members from the given list ($bInRange is true) or excludes this list ($bInRange is false).
+
+
+    8. '''getUserStatus'''
+
+{{{
+/**
+* get user status
+* @param sId - user id
+* @return sStatus - user status
+*/
+function getUserStatus ($sId){ ... }
+}}}
+
+This function retrieves the online status for a user with a given ID. The possible result values so far: "offline", "online".
+
+
+    9. '''getExtraFiles'''
+
+{{{
+/**
+* get extra files list for given module
+* @param $sModule - module name
+* @param $sFolder - folder name for where to look for files
+* @param $bGetUserFile - get current user file (true) or default file (false)
+* @param $bGetDate - get dates of files
+* @return $aResult - files array without extension and/or current file and extension separately
+*/
+function getExtraFiles($sModule, $sFolder = "langs", $bGetUserFile = true, $bGetDate = false) { ... }
+}}}
+
+This function retrieves files(cuts the last 4 characters from filename as extension) from a given folder and/or current user/default file of the given widget (skins or languages). This is mainly for language and skins lists generating:
+
+{{{
+$aSkins = getExtraFiles("chat", "skins");
+print_r($aSkins);
+/////////////////////
+Array("files" => Array(0 => "default", 1 => "heaven"), "current" =>"default", "extension" => "swf")
+}}}
+
+    10. '''setCurrentFile'''
+
+{{{
+/**
+* set current file for module to cookie
+* @param $sModule - module name
+* @param $sFile - file value
+* @param $sFolder - folder name for which value is set
+*/
+function setCurrentFile($sModule, $sFile, $sFolder = "langs") { ... }
+}}}
+
+This function saves current file (language or skin) as a cookie in the browser.
+
+
+    11. '''printFiles'''
+
+{{{
+/**
+* get extra files for module in XML format
+* @param $sModule - module name
+* @param $sFolder - folder name for which value is set
+* @param $bGetDate - get dates of files
+* @return $sContents - XML formatted result
+*/
+function printFiles($sModule, $sFolder = "langs", $bGetDate = false) { ... }
+}}}
+
+This function returns extra files information (languages or skins) for the given widget in XML format:
+
+{{{
+$sSkins = printFiles ("chat", "skins");
+echo $sSkins;
+/////////////////////
+<files>
+<file name="default" />
+<file name="heaven" />
+</files>
+<current name="heaven" url="http://[your_site]/ray/modules/chat/skins/heaven.swf" />
+}}}
+
+    12. '''getSiteName'''
+
+{{{
+/**
+ * return Site Name set by web-master
+ * @return sSiteName - Site Name
+ */
+function getSiteName (){ ... }
+}}}
+
+This function returns site name set by web-master.
+
+{{{
+$sSiteName = getSiteName();
+echo $sSiteName;
+/////////////////////
+Dolphin Site
+}}}
+
+
+"'''customFunctions.inc.php'''" file functions:
+
+
+    1. '''loginUser'''
+
+{{{
+/**
+* Authorize user by specified ID and Password or Login and Password.
+* @param $sName - user login/ID * @param $sPassword - user password
+* @param $bLogin - search for login (true) or ID (false) * @return true/false
+*/
+function loginUser($sName, $sPassword, $bLogin = false) { ... }
+}}}
+
+This function authorizes user by ID and password or by nick and password:
+
+{{{
+$sResult = loginUser("1", "12345");
+echo $sResult;
+$sResult = loginUser("nick", "12345");
+echo $sResult;
+/////////////////////
+true false
+}}}
+
+    2. '''loginAdmin'''
+
+{{{
+/**= o ns = "urn:schemas-microsoft-com:office:office" />
+* Authorize administrator by specified Login and Password.
+* @param $sLogin - administrator login
+* @param $sPassword - administrator password
+* @return true/false
+*/
+function loginAdmin($sLogin, $sPassword) { ... }
+}}}
+
+This function authorizes admin by nick and password:
+
+{{{
+$sResult = loginAdmin("admin", "dolphin");
+echo $sResult;
+/////////////////////
+true
+}}}
+
+    3. '''getUserInfo'''
+
+{{{
+/**
+* Gets user's information from database by user's id
+* @param $sId - user ID
+* @return $aInfo - user info
+*/
+function getUserInfo($sId) { ... }
+}}}
+
+This function retrieves user info by given ID:
+
+{{{
+$aInfo = getUserInfo("1");
+print_r($aInfo);
+/////////////////////
+Array("nick" => "Macho", "sex" => "Male", "age" => 25, "desc" => "some description goes here",
+"photo" => "http://[your_site]/[images_folder]/1.pg", "profile" => "http://[your_site]/profile.php?ID=1")
+}}}
+
+    4. '''searchUser'''
+
+{{{
+/**
+* Searches for user by field $sField with value $sValue
+* @param $sValue - value to search for
+* @param $sField - field to search
+* @return $sId - found user ID
+*/
+function searchUser($sValue, $sField = "ID") { ... }
+Searches user by $sField field ("ID" by default) for $sValue value and returns user ID:
+$sId = searchUser("Macho", "Nick");
+echo $sId;
+/////////////////////
+1
+}}}