websocket-sharp使用手册

Welcome to websocket-sharp!

websocket-sharp supports:

Build

websocket-sharp is built as a single assembly, websocket-sharp.dll.

websocket-sharp is developed with MonoDevelop. So a simple way to build is to open websocket-sharp.sln and run build for websocket-sharp project with any of the build configurations (e.g. Debug) in MonoDevelop.

Install

Self Build

You should add your websocket-sharp.dll (e.g. /path/to/websocket-sharp/bin/Debug/websocket-sharp.dll) to the library references of your project.

If you would like to use that dll in your Unity project, you should add it to any folder of your project (e.g. Assets/Plugins) in Unity Editor.

NuGet Gallery

websocket-sharp is available on the NuGet Gallery, as still a prerelease version.

You can add websocket-sharp to your project with the NuGet Package Manager, by using the following command in the Package Manager Console.

PM> Install-Package WebSocketSharp -Pre

Unity Asset Store

websocket-sharp is available on the Unity Asset Store.

It works with Unity Free, but there are some limitations:

  • Security Sandbox of the Webplayer (The server isn't available in Web Player)
  • WebGL Networking (Not available in WebGL)
  • Incompatible platform (Not available for such UWP)
  • Limited support for the System.IO.Compression (The compression extension isn't available on Windows)
  • .NET Socket Support for iOS/Android (It requires iOS/Android Pro if your Unity is earlier than Unity 5)
  • .NET API 2.0 compatibility level for iOS/Android

.NET API 2.0 compatibility level for iOS/Android may require to fix lack of some features for later than .NET 2.0, such as the System.Func<...> delegates (so i have added them in that asset package).

And it's priced at US$15. I think your $15 makes this project more better and accelerated, Thank you!

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: " + 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 new instance of the WebSocket class with the WebSocket URL to connect.

using (var ws = new WebSocket ("ws://example.com")) {
  ...
}

The WebSocket class inherits the System.IDisposable interface, so you can use the using statement. And the WebSocket connection will be closed with close status 1001 (going away) when the control leaves the using block.

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 passed as the System.EventArgs.Empty, so you don't need to use it.

WebSocket.OnMessage Event

A WebSocket.OnMessage event occurs when the WebSocket receives a message.

ws.OnMessage += (sender, e) => {
    ...
  };

e has passed as a WebSocketSharp.MessageEventArgs.

If you would like to get the message data, you should access e.Data or e.RawData property.

And you can determine which property you should access by checking e.IsText or e.IsBinary property.

If e.IsText is true, you should access e.Data that returns a string (represents a text message).

Or if e.IsBinary is true, you should access e.RawData that returns a byte[] (represents a binary message).

if (e.IsText) {
  // Do something with e.Data.
  ...

  return;
}

if (e.IsBinary) {
  // Do something with e.RawData.
  ...

  return;
}

And if you would like to notify that a ping has been received, via this event, you should set the WebSocket.EmitOnPing property to true, such as the following.

ws.EmitOnPing = true;
ws.OnMessage += (sender, e) => {
    if (e.IsPing) {
      // Do something to notify that a ping has been received.
      ...

      return;
    }
  };
WebSocket.OnError Event

A WebSocket.OnError event occurs when the WebSocket gets an error.

ws.OnError += (sender, e) => {
    ...
  };

e has passed as a WebSocketSharp.ErrorEventArgs.

e.Message property returns a string that represents the error message.

If the error is due to an exception, e.Exception property returns a System.Exception instance that caused the error.

WebSocket.OnClose Event

A WebSocket.OnClose event occurs when the WebSocket connection has been closed.

ws.OnClose += (sender, e) => {
    ...
  };

e has passed as a WebSocketSharp.CloseEventArgs.

e.Code property returns a ushort that represents the status code for the close, and e.Reason property returns a string that represents the reason for the close.

Step 4

Connecting to the WebSocket server.

ws.Connect ();

If you would like to connect to the server asynchronously, you should use the WebSocket.ConnectAsync () method.

Step 5

Sending data to the WebSocket server.

ws.Send (data);

The WebSocket.Send method is overloaded.

You can use the WebSocket.Send (string), WebSocket.Send (byte[]), or WebSocket.Send (System.IO.FileInfo) method to send the data.

If you would like to send the data asynchronously, you should use the WebSocket.SendAsync method.

ws.SendAsync (data, completed);

And also if you would like to do something when the send is complete, you should set completed to any Action<bool> delegate.

Step 6

Closing the WebSocket connection.

ws.Close (code, reason);

If you would like to close the connection explicitly, you should use the WebSocket.Close method.

The WebSocket.Close method is overloaded.

You can use the WebSocket.Close (), WebSocket.Close (ushort), WebSocket.Close (WebSocketSharp.CloseStatusCode), WebSocket.Close (ushort, string), or WebSocket.Close (WebSocketSharp.CloseStatusCode, string) method to close the connection.

If you would like to close the connection asynchronously, you should use the WebSocket.CloseAsync method.

WebSocket Server

using System;
using WebSocketSharp;
using WebSocketSharp.Server;

namespace Example
{
  public class Laputa : WebSocketBehavior
  {
    protected override void OnMessage (MessageEventArgs e)
    {
      var msg = e.Data == "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 WebSocketServer ("ws://dragonsnest.far");
      wssv.AddWebSocketService<Laputa> ("/Laputa");
      wssv.Start ();
      Console.ReadKey (true);
      wssv.Stop ();
    }
  }
}

Step 1

Required namespace.

using WebSocketSharp.Server;

The WebSocketBehavior and WebSocketServer classes exist in the WebSocketSharp.Server namespace.

Step 2

Creating the class that inherits the WebSocketBehavior class.

For example, if you would like to provide an echo service,

using System;
using WebSocketSharp;
using WebSocketSharp.Server;

public class Echo : WebSocketBehavior
{
  protected override void OnMessage (MessageEventArgs e)
  {
    Send (e.Data);
  }
}

And if you would like to provide a chat service,

using System;
using WebSocketSharp;
using WebSocketSharp.Server;

public class Chat : WebSocketBehavior
{
  private string _suffix;

  public Chat ()
    : this (null)
  {
  }

  public Chat (string suffix)
  {
    _suffix = suffix ?? String.Empty;
  }

  protected override void OnMessage (MessageEventArgs e)
  {
    Sessions.Broadcast (e.Data + _suffix);
  }
}

You can define the behavior of any WebSocket service by creating the class that inherits the WebSocketBehavior class.

If you override the WebSocketBehavior.OnMessage (MessageEventArgs) method, it will be called when the WebSocket used in a session in the service receives a message.

And if you override the WebSocketBehavior.OnOpen (), WebSocketBehavior.OnError (ErrorEventArgs), and WebSocketBehavior.OnClose (CloseEventArgs) methods, each of them will be called when each of the WebSocket events (OnOpen, OnError, and OnClose) occurs.

The WebSocketBehavior.Send method can send data to the client on a session in the service.

If you would like to get the sessions in the service, you should access the WebSocketBehavior.Sessions property (returns a WebSocketSharp.Server.WebSocketSessionManager).

The WebSocketBehavior.Sessions.Broadcast method can send data to every client in the service.

Step 3

Creating a new instance of the WebSocketServer class.

var wssv = new WebSocketServer (4649);
wssv.AddWebSocketService<Echo> ("/Echo");
wssv.AddWebSocketService<Chat> ("/Chat");
wssv.AddWebSocketService<Chat> ("/ChatWithNyan", () => new Chat (" Nyan!"));

You can add any WebSocket service to your WebSocketServer with the specified behavior and path to the service, by using the WebSocketServer.AddWebSocketService<TBehaviorWithNew> (string) or WebSocketServer.AddWebSocketService<TBehavior> (string, Func<TBehavior>) method.

The type of TBehaviorWithNew must inherit the WebSocketBehavior class, and must have a public parameterless constructor.

And also the type of TBehavior must inherit the WebSocketBehavior class.

So you can use the classes created in Step 2 to add the service.

If you create a instance of the WebSocketServer class without a port number, the WebSocketServer class set the port number to 80 automatically. So it's necessary to run with root permission.

$ sudo mono example2.exe

Step 4

Starting the WebSocket server.

wssv.Start ();

Step 5

Stopping the WebSocket server.

wssv.Stop (code, reason);

The WebSocketServer.Stop method is overloaded.

You can use the WebSocketServer.Stop (), WebSocketServer.Stop (ushort, string), or WebSocketServer.Stop (WebSocketSharp.CloseStatusCode, string) method to stop the server.

HTTP Server with the WebSocket

I have modified the System.Net.HttpListener, System.Net.HttpListenerContext, and some other classes from Mono to create an HTTP server that allows to accept the WebSocket handshake requests.

So websocket-sharp provides the WebSocketSharp.Server.HttpServer class.

You can add any WebSocket service to your HttpServer with the specified behavior and path to the service, by using the HttpServer.AddWebSocketService<TBehaviorWithNew> (string) or HttpServer.AddWebSocketService<TBehavior> (string, Func<TBehavior>) method.

var httpsv = new HttpServer (4649);
httpsv.AddWebSocketService<Echo> ("/Echo");
httpsv.AddWebSocketService<Chat> ("/Chat");
httpsv.AddWebSocketService<Chat> ("/ChatWithNyan", () => new Chat (" Nyan!"));

For more information, would you see Example3?

WebSocket Extensions

Per-message Compression

websocket-sharp supports the Per-message Compression extension (but doesn't support this extension with the context take over).

As a WebSocket client, if you would like to enable this extension, you should set such as the following.

ws.Compression = CompressionMethod.Deflate;

And then your client will send the following header in the handshake request to the server.

Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; client_no_context_takeover

If the server accepts this extension, it will return the same header which has the corresponding value. And when your client receives it, this extension will be available.

Ignoring the extensions

As a WebSocket server, if you would like to ignore the extensions requested from a client, you should set the WebSocketBehavior.IgnoreExtensions property to true in your WebSocketBehavior constructor or initializing it, such as the following.

wssv.AddWebSocketService<Chat> (
  "/Chat",
  () =>
    new Chat () {
      // To ignore the extensions requested from a client.
      IgnoreExtensions = true
    }
);

If it's set to true, the service will not return the Sec-WebSocket-Extensions header in its handshake response.

I think this is useful when you get something error in connecting the server and exclude the extensions as a cause of the error.

Secure Connection

websocket-sharp supports the Secure Connection with SSL/TLS.

As a WebSocket Client, you should create a new instance of the WebSocket class with the wss scheme WebSocket URL.

using (var ws = new WebSocket ("wss://example.com")) {
  ...
}

And if you would like to use the custom validation for the server certificate, you should set the WebSocket.SslConfiguration.ServerCertificateValidationCallback property.

ws.SslConfiguration.ServerCertificateValidationCallback =
  (sender, certificate, chain, sslPolicyErrors) => {
    // Do something to validate the server certificate.
    ...

    return true; // If the server certificate is valid.
  };

If you set this property to nothing, the validation does nothing with the server certificate, and returns true.

As a WebSocket Server, you should create a new instance of the WebSocketServer or HttpServer class with some settings for secure connection, such as the following.

var wssv = new WebSocketServer (5963, true);
wssv.SslConfiguration.ServerCertificate =
  new X509Certificate2 ("/path/to/cert.pfx", "password for cert.pfx");

HTTP Authentication

websocket-sharp supports the HTTP Authentication (Basic/Digest).

As a WebSocket Client, you should set a pair of user name and password for the HTTP authentication, by using the WebSocket.SetCredentials (string, string, bool) method before connecting.

ws.SetCredentials ("nobita", "password", preAuth);

If preAuth is true, the WebSocket sends the Basic authentication credentials with the first handshake request to the server.

Or if preAuth is false, the WebSocket sends either the Basic or Digest (determined by the unauthorized response to the first handshake request) authentication credentials with the second handshake request to the server.

As a WebSocket Server, you should set an HTTP authentication scheme, a realm, and any function to find the user credentials before starting, such as the following.

wssv.AuthenticationSchemes = AuthenticationSchemes.Basic;
wssv.Realm = "WebSocket Test";
wssv.UserCredentialsFinder = id => {
    var name = id.Name;

    // Return user name, password, and roles.
    return name == "nobita"
           ? new NetworkCredential (name, "password", "gunfighter")
           : null; // If the user credentials aren't found.
  };

If you would like to provide the Digest authentication, you should set such as the following.

wssv.AuthenticationSchemes = AuthenticationSchemes.Digest;

Query String, Origin header and Cookies

As a WebSocket Client, if you would like to send the Query String with the handshake request to the server, you should create a new instance of the WebSocket class with the WebSocket URL that includes the Query string parameters.

using (var ws = new WebSocket ("ws://example.com/?name=nobita")) {
  ...
}

And if you would like to send the Origin header with the handshake request to the server, you should set the WebSocket.Origin property to an allowable value as the Origin header before connecting, such as the following.

ws.Origin = "http://example.com";

And also if you would like to send the Cookies with the handshake request to the server, you should set any cookie by using the WebSocket.SetCookie (WebSocketSharp.Net.Cookie) method before connecting, such as the following.

ws.SetCookie (new Cookie ("name", "nobita"));

As a WebSocket Server, if you would like to get the Query String included in a handshake request, you should access the WebSocketBehavior.Context.QueryString property, such as the following.

public class Chat : WebSocketBehavior
{
  private string _name;
  ...

  protected override void OnOpen ()
  {
    _name = Context.QueryString["name"];
  }

  ...
}

And if you would like to validate the Origin header, Cookies, or both included in a handshake request, you should set each validation with your WebSocketBehavior, for example, by using the AddWebSocketService<TBehavior> (string, Func<TBehavior>) method with initializing, such as the following.

wssv.AddWebSocketService<Chat> (
  "/Chat",
  () =>
    new Chat () {
      OriginValidator = val => {
          // Check the value of the Origin header, and return true if valid.
          Uri origin;
          return !val.IsNullOrEmpty ()
                 && Uri.TryCreate (val, UriKind.Absolute, out origin)
                 && origin.Host == "example.com";
        },
      CookiesValidator = (req, res) => {
          // Check the cookies in 'req', and set the cookies to send to
          // the client with 'res' if necessary.
          foreach (Cookie cookie in req) {
            cookie.Expired = true;
            res.Add (cookie);
          }

          return true; // If valid.
        }
    }
);

And also if you would like to get each value of the Origin header and cookies, you should access each of the WebSocketBehavior.Context.Origin and WebSocketBehavior.Context.CookieCollection properties.

Connecting through the HTTP Proxy server

websocket-sharp supports to connect through the HTTP Proxy server.

If you would like to connect to a WebSocket server through the HTTP proxy server, you should set the proxy server URL, and if necessary, a pair of user name and password for the proxy server authentication (Basic/Digest), by using the WebSocket.SetProxy (string, string, string) method before connecting.

var ws = new WebSocket ("ws://example.com");
ws.SetProxy ("http://localhost:3128", "nobita", "password");

I have tested this with Squid. It's necessary to disable the following configuration option in squid.conf (e.g. /etc/squid/squid.conf).

# Deny CONNECT to other than SSL ports
#http_access deny CONNECT !SSL_ports

Logging

The WebSocket class has the own logging function.

You can use it with the WebSocket.Log property (returns a WebSocketSharp.Logger).

So if you would like to change the current logging level (WebSocketSharp.LogLevel.Error as the default), you should set the WebSocket.Log.Level property to any of the LogLevel enum values.

ws.Log.Level = LogLevel.Debug;

The above means a log with lower than LogLevel.Debug cannot be outputted.

And if you would like to output a log, you should use any of the output methods. The following outputs a log with LogLevel.Debug.

ws.Log.Debug ("This is a debug message.");

The WebSocketServer and HttpServer classes have the same logging function.

Examples

Examples using websocket-sharp.

Example

Example connects to the Echo server with the WebSocket.

Example2

Example2 starts a WebSocket server.

Example3

Example3 starts an HTTP server that allows to accept the WebSocket handshake requests.

Would you access to http://localhost:4649 to do WebSocket Echo Test with your web browser while Example3 is running?

Supported WebSocket Specifications

websocket-sharp supports RFC 6455, and it's based on the following WebSocket references:

Thanks for translating to japanese.

License

websocket-sharp is provided under The MIT License.

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 204,590评论 6赞 478
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 86,808评论 2赞 381
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 151,151评论 0赞 337
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,779评论 1赞 277
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,773评论 5赞 367
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,656评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,022评论 3赞 398
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,678评论 0赞 258
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 41,038评论 1赞 299
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,659评论 2赞 321
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,756评论 1赞 330
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,411评论 4赞 321
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,005评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,973评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,203评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,053评论 2赞 350
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,495评论 2赞 343

推荐阅读更多精彩内容