12 KiB
websocket-sharp is a C# implementation of the WebSocket protocol client and server.
Usage
WebSocket Client
using System;
using WebSocketSharp;
namespace Example {
public class Program {
public static void Main(string[] args)
{
using (var ws = new WebSocket("ws://dragonsnest.far/Laputa"))
{
ws.OnMessage += (sender, e) =>
{
Console.WriteLine("Laputa says: {0}", e.Data);
};
ws.Connect();
ws.Send("BALUS");
Console.ReadKey(true);
}
}
}
}
Step 1
Required namespace.
using WebSocketSharp;
The WebSocket class exists in the WebSocketSharp namespace.
Step 2
Creating a instance of the WebSocket class with the specified WebSocket URL to connect.
using (var ws = new WebSocket("ws://example.com"))
{
...
}
The WebSocket class inherits the IDisposable interface, so you can use the using statement.
Step 3
Setting the WebSocket events.
WebSocket.OnOpen event
A WebSocket.OnOpen event occurs when the WebSocket connection has been established.
ws.OnOpen += (sender, e) =>
{
...
};
e has come across as EventArgs.Empty, so there is no operation on e.
WebSocket.OnMessage event
A WebSocket.OnMessage event occurs when the WebSocket receives a WebSocket data frame.
ws.OnMessage += (sender, e) =>
{
...
};
e.Type (WebSocketSharp.MessageEventArgs.Type, the type of this property is WebSocketSharp.Opcode) indicates the Frame type of a WebSocket frame, so by checking this property, you determine which item you should operate.
if (e.Type == Opcode.TEXT)
{
// Do something with e.Data
return;
}
if (e.Type == Opcode.BINARY)
{
// Do something with e.RawData
return;
}
If e.Type equaled Opcode.TEXT, you would operate e.Data (WebSocketSharp.MessageEventArgs.Data, the type of this property is string).
If e.Type equaled Opcode.BINARY, you would operate e.RawData (WebSocketSharp.MessageEventArgs.RawData, the type of this property is byte[]).
WebSocket.OnError event
A WebSocket.OnError event occurs when the WebSocket gets an error.
ws.OnError += (sender, e) =>
{
...
};
e.Message (WebSocketSharp.ErrorEventArgs.Message, the type of this property is string) contains an error message, so you operate this.
WebSocket.OnClose event
A WebSocket.OnClose event occurs when the WebSocket connection has been closed.
ws.OnClose += (sender, e) =>
{
...
};
e.Code (WebSocketSharp.CloseEventArgs.Code, the type of this property is ushort) contains a status code indicating the reason for closure and e.Reason (WebSocketSharp.CloseEventArgs.Reason, the type of this property is string) contains the reason for closure, so you operate these.
Step 4
Connecting to the WebSocket server.
ws.Connect();
Step 5
Sending a data.
ws.Send(data);
The Send method is overloaded.
The types of data are string, byte[] and FileInfo class.
Step 6
Closing the WebSocket connection.
ws.Close(code, reason);
If you wanted to close the WebSocket connection explicitly, you would use the Close method.
And the Close method is overloaded. The types of code are WebSocketSharp.CloseStatusCode and ushort, the type of reason is string.
In addition, the Close() and Close(code) methods exist.
WebSocket Server
using System;
using WebSocketSharp;
using WebSocketSharp.Server;
namespace Example {
public class Laputa : WebSocketService
{
protected override void OnMessage(MessageEventArgs e)
{
var msg = e.Data.ToLower().Equals("balus")
? "I've been balused already..."
: "I'm not available now.";
Send(msg);
}
}
public class Program {
public static void Main(string[] args)
{
var wssv = new WebSocketServiceHost<Laputa>("ws://dragonsnest.far/Laputa");
wssv.Start();
Console.ReadKey(true);
wssv.Stop();
}
}
}
Step 1
Required namespace.
using WebSocketSharp.Server;
The WebSocketServer, WebSocketServiceHost<T> and WebSocketService classes exist in the WebSocketSharp.Server namespace.
Step 2
Creating a class that inherits the WebSocketService class.
For example, if you want to provide the echo service,
using System;
using WebSocketSharp;
using WebSocketSharp.Server;
public class Echo : WebSocketService
{
protected override void OnMessage(MessageEventArgs e)
{
Send(e.Data);
}
}
Or if you want to provide the chat service,
using System;
using WebSocketSharp;
using WebSocketSharp.Server;
public class Chat : WebSocketService
{
protected override void OnMessage(MessageEventArgs e)
{
Broadcast(e.Data);
}
}
If you override the OnMessage method, it is bound to the server side WebSocket.OnMessage event.
In addition, if you override the OnOpen, OnError and OnClose methods, each of them is bound to the WebSocket.OnOpen, WebSocket.OnError and WebSocket.OnClose events.
Step 3
Creating a instance of the WebSocketServiceHost<T> class if you want the single WebSocket service server.
var wssv = new WebSocketServiceHost<Echo>("ws://example.com:4649");
Or creating a instance of the WebSocketServer class if you want the multi WebSocket service server.
var wssv = new WebSocketServer(4649);
wssv.AddWebSocketService<Echo>("/Echo");
wssv.AddWebSocketService<Chat>("/Chat");
You can add any WebSocket service with a specified path to the service to your WebSocketServer by using the WebSocketServer.AddWebSocketService<T> method.
The type of T inherits WebSocketService class, so you can use a class that was created in Step 2.
If you created a instance of the WebSocketServer class without the port number, the WebSocketServer would set the port number to 80 automatically. So it is necessary to run with root permission.
$ sudo mono example2.exe
Step 4
Setting the event.
WebSocketServiceHost<T>.OnError event
A WebSocketServiceHost<T>.OnError event occurs when the WebSocketServiceHost<T> gets an error.
wssv.OnError += (sender, e) =>
{
...
};
e.Message (WebSocketSharp.ErrorEventArgs.Message, the type of this property is string) contains an error message, so you operate this.
WebSocketServer.OnError event
Same as the WebSocketServiceHost<T>.OnError event.
Step 5
Starting the server.
wssv.Start();
Step 6
Stopping the server.
wssv.Stop();
HTTP Server with the WebSocket
I modified the System.Net.HttpListener, System.Net.HttpListenerContext and some other classes of Mono to create the HTTP server that can upgrade the connection to the WebSocket connection when receives a WebSocket connection request.
You can add any WebSocket service with a specified path to the service to your HttpServer by using the HttpServer.AddWebSocketService<T> method.
var httpsv = new HttpServer(4649);
httpsv.AddWebSocketService<Echo>("/");
For more information, could you see Example3?
Logging
The WebSocket class includes own logging functions.
The WebSocket.Log property provides the logging functions.
If you wanted to change the current logging level (the default is the LogLevel.ERROR), you would operate the WebSocket.Log.Level property.
ws.Log.Level = LogLevel.DEBUG;
This setting means that the logging outputs with a less than the LogLevel.DEBUG are not outputted.
And if you wanted to output a log, you would use some output methods. The following outputs a log with the LogLevel.DEBUG.
ws.Log.Debug("This is a debug message.");
The WebSocketServiceHost<T>, WebSocketServer and HttpServer classes include the same logging functions.
Examples
Examples of using websocket-sharp.
Example
Example connects to the Echo server using the WebSocket.
Example1
Example1 connects to the Audio Data delivery server using the WebSocket (Example1 is only implemented the chat feature, still unfinished).
And Example1 uses the Json.NET.
Example2
Example2 starts a WebSocket server.
Example3
Example3 starts an HTTP server that can upgrade the connection to the WebSocket connection.
Could you access to http://localhost:4649 to do WebSocket Echo Test with your web browser after Example3 running?
websocket-sharp for Unity
websocket-sharp has now been displayed on the Unity Asset Store!
Required Environment
C# 3.0, .NET 3.5 compatible or later.
Supported WebSocket Specifications
websocket-sharp supports RFC 6455.
- branch: hybi-00 supports older draft-ietf-hybi-thewebsocketprotocol-00 ( hybi-00 ).
- branch: draft75 supports even more old draft-hixie-thewebsocketprotocol-75 ( hixie-75 ).
Supported WebSocket Extensions
Per-message Compression
websocket-sharp supports Per-message Compression extension. (But, does not support with extension parameters.)
If you want to enable this extension as a WebSocket client, you should do like the following.
ws.Compression = CompressionMethod.DEFLATE;
And then your client sends the following header in the opening handshake to a WebSocket server.
Sec-WebSocket-Extensions: permessage-deflate
If the server supports this extension, responds the same header. And when your client receives the header, enables this extension.
WebSocket References
Thanks for translating to japanese.
License
Copyright © 2010 - 2013 sta.blockhead
Licensed under the MIT License.