Server API

User Manual

Home	Data API \| Friend List Integration

Introduction
Get Server Running Status from the files
Get numbers
Get username list of each room
Send command to server to push or query the real-time data
Add room
Delete room
Edit room
Broadcast
Private message
Start group
Stop group

Introduction

123 Flash Chat Server provides some userful server APIs for the third-party application to invoke data using socket or read room or user data from server data folder.

Get Server Running Status from the files

When a chat server is running, some parameters are stored in text files which can be read by your application. Useful information can be extracted from them.

This feature is included in the standard version of 123 Flash Chat.

Get numbers

To obtain a current connection number, the logon user number and the room number from a record file, use the following format:
<123FC installation directory>/server/data/default/online.txt

This file will real-timely change according to the chat room status.

Format:

<connection number >|<logon user number>|<room numbers>
Sample: 230|193|10
The example above shows that there are 230 connections on the chat server, 193 of them have logged in and there are 10 chat rooms altogether.
This data can be read and displayed in php, asp or other dynamic webpages.

Get username list of each room

You can display the user name list of each room on your webpage by retrieving data from "room_*.txt".

In the <123 installation directory>/server/data/default/, you can find the following files:
"room_1.txt ", "room_2.txt", etc.
These files store the online user lists of relevant rooms. These will keep changing depending on the changes of specific rooms.

Send command to server to push or query the real-time data

This feature can be very handy for an advanced user.
With it you can develop an application to connect to the chat server via a socket. Then a TCP string command can be sent to push or query the real-time data.

In "<123flashchat installation directory>/server/etc/groups/default/server.xml" file you will find:
<Server-API enable="On">

<auth-password>3874-3459-9393-2194</auth-password>

<allow-access-from-ip>127.0.0.1</allow-access-from-ip>
</Server-API>

The socket message string being sent is in standard syntax which will appear as shown below:
<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="api_pwd_in_default.xml_file" type="command_type" "command_parameters...." />

Note:

Remember to terminate XML-commands with a zero byte.

add_room

Rooms can be added on the fly using the 'add room' command.
The following parameters are indispensable:

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	add_room	Specify the type of the command being sent.
name	String		Expected room name
owner	String		New room moderator
desc	String		New room description
max	Number		max number of people the new room can hold
speaker	String		New room speaker
member	Boolean(0/1)		Enable or disable guest to enter room. 0 means disable 1 means enable
pwd	String		New room password
passallmessage	Boolean(0/1)		Enable or disable the moderator chat mode.(need moderator chat module) 0 means disable 1 means enable
en	Boolean(0/1)		The room status is open or close 0 means close 1 means open
st	Number		It determines the room will only be displayed in the avatar chat client, or in the text chat room list as well. 0 means it will be displayed in text chat room list too. 2 means it will be only displayed in the avatar chat client side.
wm	String		The room's welcome message
audio	Boolean(0/1)		Enable or disable audio in the room, it needs audio video module. 0 means disable 1 means enable
video	Boolean(0/1)		Enable or disable video in the room, it needs audio video module. 0 means disable 1 means enable
wb	Boolean(0/1)		Enable or disable white board in the room, it needs white board module. 0 means disable 1 means enable
roomOpen	Element		(Only supported when user have event chat module)
roomOpen->Time	Element
Time->o	String		Option: day1~day31 special
Time->e	String		End time
Time->s	String		Start time

A full sample of this command is shown below:

<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="add_room" name="test room" owner="aaa" desc="room for test" max="200" speaker="bbb" member="false" pwd="" passallmessage="true" >
<roomOpen>
<Time o="day2" e="10:00:00" s="00:00:00"></Time>
</roomOpen>
</Command>

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="add_room" name="test room" owner="aaa" desc="room for test" max="200" speaker="bbb" member="false" pwd="" passallmessage="true" />';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

For advanced details, please check webpage:
http://www.123flashchat.com/addroom-serverapi.html

del_room

Rooms can be deleted dynamically using this command.

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	del_room	Specify the type of the command being sent.
room_id	Number	?	The id of the room which is needed to be removed.

A full sample of this command can be seen below:
<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="del_room" room_id="1" />

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="del_room" room_id="1" />';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

edit_room

Rooms can be edited dynamically using this command.

The following parameters are indispensable:

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	edit_room	Specify the type of the command being sent.
roomid	String		The id of the room which is needed to be edited.
name	String		Expected room name
owner	String		New room moderator
desc	String		New room description
max	Number		max number of people the new room can hold
speaker	String		New room speaker
member	Boolean(0/1)		Enable or disable guest to enter room 0 means disable 1 means enable
pwd	String		New room password
passallmessage	Boolean(0/1)		Enable or disable the moderator chat mode.(need moderator chat module) 0 means disable 1 means enable
en	Boolean(0/1)		The room status is open or close 0 means close 1 means open
st	Number		It determines the room will only be displayed in the avatar chat client, or in the text chat room list as well. 0 means displayed in text chat room list too. 2 means only displayed in the avatar chat client side
wm	String		The room's welcome message
audio	Boolean(0/1)		Enable or disable audio in the room, it needs audio video module. 0 means disable 1 means enable
video	Boolean(0/1)		Enable or disable video in the room, it needs audio video module. 0 means disable 1 means enable
wb	Boolean(0/1)	?	Enable or disable white board in the room, it needs white board module. 0 means disable 1 means enable

A full sample of this command is shown below:

<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="edit_room" roomid="3412" name="new name" owner="new_owner" desc="new_desc" max="300" speaker="new_speaker" member="true" pwd="new_pwd" passallmessage="false" />

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="edit_room" roomid="3412" name="new name" owner="new_owner" desc="new_desc" max="300" speaker="new_speaker" member="true" pwd="new_pwd" passallmessage="false" />';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

broadcast

This command will broadcast messages to every logon user, whether or not they have entered their username or entered a room.
The following parameters are indispensable:

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	broadcast	Specify the type of the command being sent.
userid	String	?	What name should be used to broadcast.
msg	String	?	Broadcast message.

A full sample of this command can be seen below:

<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="broadcast" userid="test" msg="welcome to 123flashcaht" />

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="broadcast" userid="test" msg="welcome to 123flashcaht" />';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

private_message

This allows a private message to be sent to a specific user.

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	private_message	Specify the type of the command being sent.
dest_uid	String		The receiver's userid
msg	String		Message to be sent
avatar	String		Avatar name in the message(could be "e1" , "e2" ..."e32")
owner_uid	String		The sender's userid
owner_nick	String		The sender's nickname
b	"1" or "0"		1-bold font for the message being sent 0- not bold
i	"1" or "0"		1- italic font 0- not italic
u	"1" or "0"		1- underlined font 0- no underline
color	Hexadecimal Number		Color value must begin with "0x", eg: red is "0xFF0000"

A full sample of this command can be seen below:

<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="private_message" dest_uid="test" msg="hello world" emotion="e2" owner_uid="admin" owner_nick="admin" b="1" i="1" u="1" color="0xff00ff" />

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="private_message" dest_uid="test" msg="hello world" emotion="e2" owner_uid="admin" owner_nick="admin" b="1" i="1" u="1" color="0xff00ff" />';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

start group

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	start_group	Specify the type of the command being sent.

A full sample of this command can be seen below:
<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="start_group"/>

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="start_group"/>';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

stop group

Parameter	Type	Default Value	Description
group	String	default	group name, in the standard version, the group value has to be "default"
api_pwd	String	3874-3459-9393-2194	server api password defined in "server.xml"->Server-API->auth-password
type	String	stop_group	Specify the type of the command being sent.

A full sample of this command can be seen below:
<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="stop_group"/>

php sample code

How to use above server APIs with php to send command to chat server, here is the sample code:

<?php
$host = "127.0.0.1";
$port = 51127;
$apiCommand = '<?xml version="1.0" encoding="UTF-8"?><Command group="default" api_pwd="3874-3459-9393-2194" type="stop_group"/>';
$result = "";
$resultDoc = "";
$fp = @fsockopen($host, $port, &$errno, &$errstr, 2);
if(!$fp)
{
echo "Failed to excute api command,maybe host chat server is not started";
}
else
{
fputs($fp,$apiCommand."\0");
while (!feof($fp))
{
$resultDoc .= fgets($fp, 1024);
$resultDoc = rtrim($resultDoc);
}
$parser = xml_parser_create("UTF-8");
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
if (!xml_parse_into_struct($parser, $resultDoc, $values, $tags))
{
printf("XML error: %s at line %d while parsing entity n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser));
echo "xml parse error";
}
else
{
print_r($values);
xml_parser_free($parser);
fclose($fp);
}
}
?>

Related links:

For Developers

Home	Data API \| Friend List Integration