XMLSocket :: F.A.Q & API :: Socket class for JavaScript using Flash Player >= 6 bridge

F.A.Q.

What is XMLSocket ?

XMLSocket is a JavaScript class that would replace magic Flash MX or greater XMLSocket class.

Why XMLSocket ?

Ajax doesn't support socket connection and many ajax based applications (chat, im or others) requires a refresh every N seconds. This "delayed" way to interact requires a dedicated control too to verify if users are connected or not. Every message, sent or recieved, will be displayed every N seconds, but is really necessary this reload interval ? Not if you have a socket, where there's no delay or refresh and where every message is sent in real-time to each user. With a socket you have every time the real status of connections and a system based on socket doesn't require a database, all messages are managed by the socket and not by a generic db engine. However, for advanced applications, you can choose to storage all informations in any kind of datadase. Then socket is one of the best ways to develop real-time multiple users interaction applications.

[compatibility] Why I need two swf files and not one ?

First beta version was based on Flash Player 8 because its introduce a new class called External Interface. This class is a must for every Internet Explorer browser because it's faster and more powerfull then a generic getURL("javascript:something()"); command and resolves a lot of problems that getURL has on IE browser. This public stable version introduce a new swf file, called XMLSocketMX that will be supported from every player version 6 compatible browser or platform. That's because Adobe (Macromedia) has not yet created a player verion 8 for Linux based systems, then if your browser has not been updated with last player 8 or your browser hasn't support for this version, it will be able to use this JavaScript XMLSocket porting.

What are requirements ?

[client] A JavaScript compatible and enabled browser with flash player version 6 or greater
[server] A server-side script/program language that can create and manage a socket listener (then requires a bit of server-side skill) [ top menu ]

Why I should use this JavaScript porting and not directly the original Flash ActionScript classes ?

Because sometimes a developer doesn't need to buy an expensive IDE as Adobe Flash is, but sometimes he should need to use some features of that IDE. XMLSocket, as FileReference or FileReferenceList, are both ActionScript classes that maybe a Flash designer will never use but a generic client/server developer should really need to create its "new and awesome" applications that should do single or multiple uploads with a real and perfect progress status or should connect clients with a dedicated server socket. Are you thinking about Eclipse ? ... Sure, that's good, but isn't simpler to use theese "just and well done" portings ? I hope so :-)

API :: XMLSocket Methods

constructor

Any parameter to construct an XMLSocket object.
var xmls = new XMLSocket();
[ top menu ]

close

Close socket connection. Any parameter is required but for a better control, check if connection was created before call it.
var xmls = new XMLSocket();
var connected = false;
document.getElementById("socket-close").onclick = function() {
	if(connected)
		xmls.close();
};
// then swith connected to true while create a connection
[ top menu ]

connect

Connects to a socket if server has created one. Accepts a string as ip or server name and an integer as dedicated socket port.
// ... create an XMLSocket object then init them and connect with ...
var serverName = 'localhost';
var socketPort = 2000;
xmls.connect(serverName, socketPort);
Remember that Flash XMLSocket class accept only ports greater than 1023. Then use 1024 or greater number. [ top menu ]

getFlashPlayerVersion

This method is used by class to know what version of swf must be used but you can use it if you need this check.
var xmls = new XMLSocket();
alert(xmls.getFlashPlayerVersion());
It doesn't require parameters and returns an ingeter greater than 0 if Flash Player plugin was found. Returns zero with IE4 or with browsers that haven't this plugin then you can use it to show an alternative message for users that will not be able to use your system. [ top menu ]

init

This method initialize the XMLSocket object with the name of unique id of dedicated div. It puts inside them the correct swf then manages internal vars to prepare XMLSocket to work.
<html>
	<head>
		<script>
		// just an example
		var connected = false;
		onload = function() {
			var xmls = new XMLSocket();
			xmls.init("xmlsocket-div");
			
			// if you need to connect directly use a delay
			// function because swf that's will be add
			// inside div should be totally downloaded.
			// Max 700 bytes of swf requires
			// about 1 or 2 seconds to be downloaded.
			function connect() {
				xmls.onConnect = function(success) {
					if(success)
						connected = true;
				};
				xmls.connect('host', 1024);
			};
			setTimeout(connect, 1500);
		};
		</script>
	</head>
	<body>
		<div id="xmlsocket-div"></div>
	</body>
</html>
Remember that used div will disappear from the document, then don't worry about page layout. [ top menu ]

send

This method send to server any kind of string if object is connected.
xmls.send("Hello Server Socket :-)");
[ top menu ]

API :: XMLSocket Events

onClose

Called when server side socket is closed (not when user close the socket connection). Any parameter will be sent to this event.
xmls.onClose = function() {
	alert("server has gone away");
};
[ top menu ]

onConnect

Called when a client try to connect to the server. Recieves a boolean value of false, if there's no connection or true, if connection has been created.
xmls.onConnect = function(success) {
	if(success)
		alert("connection created");
	else
		alert("any connection");
};
[ top menu ]

onData

Called when users recieve a message from the socket.
xmls.onData = function(text) {
	alert(text);
};
[ top menu ]

onXML

Called when users recieve an XML document from the socket.
xmls.onXML = function(xml) {
	alert(xml.getElementsByTagName("item").length);
};
[ top menu ]