== 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
}}}