Skip to content
This repository
Browse code

Updating README.

  • Loading branch information...
commit 6b6dfb0ee0fe99dd65bc210f7b175959b5e36487 1 parent 62e27ae
Hiroshi Ichikawa authored April 03, 2011

Showing 1 changed file with 57 additions and 23 deletions. Show diff stats Hide diff stats

  1. 80  README.md
80  README.md
Source Rendered
... ...
@@ -1,4 +1,4 @@
1  
-### How to try
  1
+## How to try the sample
2 2
 
3 3
 Assuming you have Web server (e.g. Apache) running at **http://example.com/** .
4 4
 
@@ -15,7 +15,37 @@ Assuming you have Web server (e.g. Apache) running at **http://example.com/** .
15 15
 \#1: First argument of echo_server.rb means that it accepts Web Socket connection from HTML pages in example.com.
16 16
 
17 17
 
18  
-### Troubleshooting
  18
+## How to use it in your application
  19
+
  20
+1. Copy swfobject.js, web_socket.js, WebSocketMain.swf to your application directory.
  21
+2. Write JavaScript code:
  22
+    <!-- Imports JavaScript Libraries. -->
  23
+    <script type="text/javascript" src="swfobject.js"></script>
  24
+    <script type="text/javascript" src="web_socket.js"></script>
  25
+   
  26
+    <script type="text/javascript">
  27
+      
  28
+      // Let the library know where WebSocketMain.swf is:
  29
+      WebSocket.__swfLocation = "WebSocketMain.swf";
  30
+      
  31
+      // Write your code in the same way as for native WebSocket:
  32
+      var ws = new WebSocket("ws://example.com:10081/");
  33
+      ws.onopen = function() {
  34
+        ws.send("Hello");  // Sends a message.
  35
+      };
  36
+      ws.onmessage = function(e) {
  37
+        // Receives a message.
  38
+        alert(e.data);
  39
+      };
  40
+      ws.onclose = function() {
  41
+        alert("closed");
  42
+      };
  43
+      
  44
+    </script>
  45
+3. Put Flash socket policy file to your server unless you use web-socket-ruby or em-websocket as your WebSocket server. See "Flash socket policy file" section below for details.
  46
+
  47
+
  48
+## Troubleshooting
19 49
 
20 50
 If it doesn't work, try these:
21 51
 
@@ -40,53 +70,58 @@ and use Developer Tools (Chrome/Safari) or Firebug (Firefox) to see if console.l
40 70
 
41 71
 6. Make sure the port used for WebSocket (10081 in example above) is not blocked by your server/client's firewall.
42 72
 
43  
-7. Install debugger version of Flash Player available here to see Flash errors:
44  
-[http://www.adobe.com/support/flashplayer/downloads.html](http://www.adobe.com/support/flashplayer/downloads.html)
  73
+7. Install [debugger version of Flash Player](http://www.adobe.com/support/flashplayer/downloads.html) to see Flash errors.
45 74
 
46 75
 
47  
-### Supported environments
  76
+## Supported environments
48 77
 
49 78
 It should work on:
50 79
 
51 80
 - Google Chrome 4 or later (just uses native implementation)
52  
-- Firefox 3.x, Internet Explorer 8 + Flash Player 10 or later
  81
+- Firefox 3.x, 4.x, Internet Explorer 8, 9 + Flash Player 10 or later
53 82
 
54 83
 It may or may not work on other browsers such as Safari, Opera or IE 6. Patch for these browsers are appreciated, but I will not work on fixing issues specific to these browsers by myself.
55 84
 
56 85
 
  86
+## Limitations/differences compared to native WebSocket
  87
+
  88
+- You need some more lines in your JavaScript code. See "How to use it in your application" section above for details.
  89
+- It requires Flash Player 10 or later unless the browser supports native WebSocket.
  90
+- Your server must provide Flash socket policy file, unless you use web-socket-ruby or em-websocket. See "Flash socket policy file" section below for details.
  91
+- It has limited support for Cookies on WebSocket. See "Cookie support" section below for details.
  92
+- It doesn't use proxies specified in browser config. See "Proxy support" section below for details.
  93
+
  94
+
57 95
 ### Flash socket policy file
58 96
 
59 97
 This implementation uses Flash's socket, which means that your server must provide Flash socket policy file to declare the server accepts connections from Flash.
60 98
 
61  
-If you use web-socket-ruby available at
62  
-[http://github.com/gimite/web-socket-ruby/tree/master](http://github.com/gimite/web-socket-ruby/tree/master)
63  
-, you don't need anything special, because web-socket-ruby handles Flash socket policy file request. But if you already provide socket policy file at port **843**, you need to modify the file to allow access to Web Socket port, because it precedes what web-socket-ruby provides.
  99
+If you use [web-socket-ruby](http://github.com/gimite/web-socket-ruby/tree/master) or [em-websocket](https://github.com/igrigorik/em-websocket), you don't need anything special, because web-socket-ruby handles Flash socket policy file request. But if you already provide socket policy file at port **843**, you need to modify the file to allow access to Web Socket port, because it precedes what web-socket-ruby provides.
  100
+
  101
+If you use other Web Socket server implementation, you need to provide socket policy file yourself. See [Setting up A Flash Socket Policy File](http://www.lightsphere.com/dev/articles/flash_socket_policy.html) for details and sample script to run socket policy file server. [node.js implementation is available here](http://github.com/LearnBoost/Socket.IO-node/blob/master/lib/socket.io/transports/flashsocket.js).
64 102
 
65  
-If you use other Web Socket server implementation, you need to provide socket policy file yourself. See
66  
-[http://www.lightsphere.com/dev/articles/flash_socket_policy.html](http://www.lightsphere.com/dev/articles/flash_socket_policy.html)
67  
-for details and sample script to run socket policy file server. node.js implementation is available here:
68  
-[http://github.com/LearnBoost/Socket.IO-node/blob/master/lib/socket.io/transports/flashsocket.js](http://github.com/LearnBoost/Socket.IO-node/blob/master/lib/socket.io/transports/flashsocket.js)
  103
+Actually, it's still better to provide socket policy file at port 843 even if you use web-socket-ruby or em-websocket. Flash always try to connect to port 843 first, so providing the file at port 843 makes startup faster.
69 104
 
70  
-Actually, it's still better to provide socket policy file at port 843 even if you use web-socket-ruby. Flash always try to connect to port 843 first, so providing the file at port 843 makes startup faster.
71 105
 
  106
+### Cookie support
72 107
 
73  
-### Cookie considerations
  108
+web-socket-js has limited supported for Cookies on WebSocket.
74 109
 
75  
-Cookie is sent if Web Socket host is the same as the origin of JavaScript. Otherwise it is not sent, because I don't know way to send right Cookie (which is Cookie of the host of Web Socket, I heard).
  110
+Cookie is sent if Web Socket host is exactly the same as the origin of JavaScript (The port can be different). Otherwise it is not sent, because I don't know way to send right Cookie (which is Cookie of the host of Web Socket, I heard). Also, HttpOnly Cookies are not sent.
76 111
 
77 112
 Note that it's technically possible that client sends arbitrary string as Cookie and any other headers (by modifying this library for example) once you place Flash socket policy file in your server. So don't trust Cookie and other headers if you allow connection from untrusted origin.
78 113
 
79 114
 
80  
-### Proxy considerations
  115
+### Proxy support
81 116
 
82  
-The WebSocket spec (http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol) specifies instructions for User Agents to support proxied connections by implementing the HTTP CONNECT method.
  117
+[The WebSocket spec](http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol) specifies instructions for User Agents to support proxied connections by implementing the HTTP CONNECT method.
83 118
 
84 119
 The AS3 Socket class doesn't implement this mechanism, which renders it useless for the scenarios where the user trying to open a socket is behind a proxy. 
85 120
 
86 121
 The class RFC2817Socket (by Christian Cantrell) effectively lets us implement this, as long as the proxy settings are known and provided by the interface that instantiates the WebSocket. As such, if you want to support proxied conncetions, you'll have to supply this information to the WebSocket constructor when Flash is being used. One way to go about it would be to ask the user for proxy settings information if the initial connection fails.
87 122
 
88 123
 
89  
-### How to host HTML file and SWF file in different domains
  124
+## How to host HTML file and SWF file in different domains
90 125
 
91 126
 By default, HTML file and SWF file must be in the same domain. You can follow steps below to allow hosting them in different domain.
92 127
 
@@ -97,15 +132,14 @@ By default, HTML file and SWF file must be in the same domain. You can follow st
97 132
 3. In JavaScript, set WEB_SOCKET_SWF_LOCATION to URL of your WebSocketMainInsecure.swf.
98 133
 
99 134
 
100  
-### How to build WebSocketMain.swf
  135
+## How to build WebSocketMain.swf
101 136
 
102  
-Install Flex 4 SDK:
103  
-[http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4](http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4)
  137
+Install [Flex 4 SDK](http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4).
104 138
 
105 139
     $ cd flash-src
106 140
     $ ./build.sh
107 141
 
108 142
 
109  
-### License
  143
+## License
110 144
 
111 145
 New BSD License.

0 notes on commit 6b6dfb0

Please sign in to comment.
Something went wrong with that request. Please try again.