websocket-sharp/params.json

{"name":"websocket-sharp","tagline":"A C# implementation of the WebSocket protocol client and server","body":"## Welcome to websocket-sharp! ##\r\n\r\n**websocket-sharp** supports:\r\n\r\n- **[WebSocket Client](#websocket-client)** and **[Server](#websocket-server)**\r\n- **[RFC 6455](#supported-websocket-specifications)**\r\n- **[Per-message Compression](#per-message-compression)** extension\r\n- **[Secure Connection](#secure-connection)**\r\n- **[HTTP Authentication](#http-authentication)**\r\n- .NET **3.5** or later (includes compatible)\r\n\r\n## Build ##\r\n\r\nwebsocket-sharp is built as a single assembly, **websocket-sharp.dll**.\r\n\r\nwebsocket-sharp is developed with **[MonoDevelop]**. So the simple way to build is to open **websocket-sharp.sln** and run build for the websocket-sharp project with any of the build configurations (e.g. Debug) in the MonoDevelop.\r\n\r\n## Install ##\r\n\r\n### Self Build ###\r\n\r\nYou should add **websocket-sharp.dll** (e.g. /path/to/websocket-sharp/bin/Debug/websocket-sharp.dll) built yourself to the library references of your project.\r\n\r\nIf you would like to use that websocket-sharp.dll in your **[Unity]** project, you should add that dll to any folder of your project (e.g. Assets/Plugins) in the **Unity Editor**.\r\n\r\n### NuGet Gallery ###\r\n\r\nwebsocket-sharp is available on the **[NuGet Gallery]**, as still a **prerelease** version.\r\n\r\n- **[NuGet Gallery: websocket-sharp]**\r\n\r\nYou can add websocket-sharp to your project using the **NuGet Package Manager**, the following command in the **Package Manager Console**.\r\n\r\n    PM> Install-Package WebSocketSharp -Pre\r\n\r\n### Unity Asset Store ###\r\n\r\nwebsocket-sharp is available on the **Unity Asset Store**.\r\n\r\n- **[WebSocket-Sharp for Unity]**\r\n\r\nIt's priced at **US$15**. I think your $15 makes this project more better and accelerated, **Thank you!**\r\n\r\n## Usage ##\r\n\r\n### WebSocket Client ###\r\n\r\n```cs\r\nusing System;\r\nusing WebSocketSharp;\r\n\r\nnamespace Example\r\n{\r\n  public class Program\r\n  {\r\n    public static void Main (string [] args)\r\n    {\r\n      using (var ws = new WebSocket (\"ws://dragonsnest.far/Laputa\")) {\r\n        ws.OnMessage += (sender, e) =>\r\n          Console.WriteLine (\"Laputa says: \" + e.Data);\r\n\r\n        ws.Connect ();\r\n        ws.Send (\"BALUS\");\r\n        Console.ReadKey (true);\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### Step 1 ####\r\n\r\nRequired namespace.\r\n\r\n```cs\r\nusing WebSocketSharp;\r\n```\r\n\r\nThe `WebSocket` class exists in the `WebSocketSharp` namespace.\r\n\r\n#### Step 2 ####\r\n\r\nCreating an instance of the `WebSocket` class with the WebSocket URL to connect.\r\n\r\n```cs\r\nusing (var ws = new WebSocket (\"ws://example.com\")) {\r\n  ...\r\n}\r\n```\r\n\r\nThe `WebSocket` class inherits the `System.IDisposable` interface, so you can use the `using` statement.\r\n\r\n#### Step 3 ####\r\n\r\nSetting the `WebSocket` events.\r\n\r\n##### WebSocket.OnOpen Event #####\r\n\r\nA `WebSocket.OnOpen` event occurs when the WebSocket connection has been established.\r\n\r\n```cs\r\nws.OnOpen += (sender, e) => {\r\n  ...\r\n};\r\n```\r\n\r\n`e` has passed as the `System.EventArgs.Empty`, so you don't use `e`.\r\n\r\n##### WebSocket.OnMessage Event #####\r\n\r\nA `WebSocket.OnMessage` event occurs when the `WebSocket` receives a message.\r\n\r\n```cs\r\nws.OnMessage += (sender, e) => {\r\n  ...\r\n};\r\n```\r\n\r\n`e` has passed as a `WebSocketSharp.MessageEventArgs`.\r\n\r\n`e.Type` property returns either `WebSocketSharp.Opcode.TEXT` or `WebSocketSharp.Opcode.BINARY` that represents the type of the received message. So by checking it, you determine which item you should use.\r\n\r\nIf `e.Type` is `Opcode.TEXT`, you should use `e.Data` property (returns a `string`) that represents the received **Text** message.\r\n\r\nOr if `e.Type` is `Opcode.BINARY`, you should use `e.RawData` property (returns a `byte []`) that represents the received **Binary** message.\r\n\r\n```cs\r\nif (e.Type == Opcode.TEXT) {\r\n  // Do something with e.Data\r\n  return;\r\n}\r\n\r\nif (e.Type == Opcode.BINARY) {\r\n  // Do something with e.RawData\r\n  return;\r\n}\r\n```\r\n\r\n##### WebSocket.OnError Event #####\r\n\r\nA `WebSocket.OnError` event occurs when the `WebSocket` gets an error.\r\n\r\n```cs\r\nws.OnError += (sender, e) => {\r\n  ...\r\n};\r\n```\r\n\r\n`e` has passed as a `WebSocketSharp.ErrorEventArgs`.\r\n\r\n`e.Message` property returns a `string` that represents the error message. So you should use it to get the error message.\r\n\r\n##### WebSocket.OnClose Event #####\r\n\r\nA `WebSocket.OnClose` event occurs when the WebSocket connection has been closed.\r\n\r\n```cs\r\nws.OnClose += (sender, e) => {\r\n  ...\r\n};\r\n```\r\n\r\n`e` has passed as a `WebSocketSharp.CloseEventArgs`.\r\n\r\n`e.Code` property returns a `ushort` that represents the status code indicating the reason for closure, and `e.Reason` property returns a `string` that represents the reason for closure. So you should use them to get the reason for closure.\r\n\r\n#### Step 4 ####\r\n\r\nConnecting to the WebSocket server.\r\n\r\n```cs\r\nws.Connect ();\r\n```\r\n\r\nIf you would like to connect to the server asynchronously, you should use the `WebSocket.ConnectAsync ()` method.\r\n\r\n#### Step 5 ####\r\n\r\nSending a data to the WebSocket server.\r\n\r\n```cs\r\nws.Send (data);\r\n```\r\n\r\nThe `WebSocket.Send` method is overloaded.\r\n\r\nYou can use the `WebSocket.Send (string)`, `WebSocket.Send (byte [])`, and `WebSocket.Send (System.IO.FileInfo)` methods to send a data.\r\n\r\nIf you would like to send a data asynchronously, you should use the `WebSocket.SendAsync` method.\r\n\r\n```cs\r\nws.SendAsync (data, completed);\r\n```\r\n\r\nAnd if you would like to do something when the send is complete, you should set `completed` to any `Action<bool>`.\r\n\r\n#### Step 6 ####\r\n\r\nClosing the WebSocket connection.\r\n\r\n```cs\r\nws.Close (code, reason);\r\n```\r\n\r\nIf you would like to close the connection explicitly, you should use the `WebSocket.Close` method.\r\n\r\nThe `WebSocket.Close` method is overloaded.\r\n\r\nYou 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.\r\n\r\nIf you would like to close the connection asynchronously, you should use the `WebSocket.CloseAsync` method.\r\n\r\n### WebSocket Server ###\r\n\r\n```cs\r\nusing System;\r\nusing WebSocketSharp;\r\nusing WebSocketSharp.Server;\r\n\r\nnamespace Example\r\n{\r\n  public class Laputa : WebSocketService\r\n  {\r\n    protected override void OnMessage (MessageEventArgs e)\r\n    {\r\n      var msg = e.Data == \"BALUS\"\r\n              ? \"I've been balused already...\"\r\n              : \"I'm not available now.\";\r\n\r\n      Send (msg);\r\n    }\r\n  }\r\n\r\n  public class Program\r\n  {\r\n    public static void Main (string [] args)\r\n    {\r\n      var wssv = new WebSocketServer (\"ws://dragonsnest.far\");\r\n      wssv.AddWebSocketService<Laputa> (\"/Laputa\");\r\n      wssv.Start ();\r\n      Console.ReadKey (true);\r\n      wssv.Stop ();\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### Step 1 ####\r\n\r\nRequired namespace.\r\n\r\n```cs\r\nusing WebSocketSharp.Server;\r\n```\r\n\r\nThe `WebSocketServer` and `WebSocketService` classes exist in the `WebSocketSharp.Server` namespace.\r\n\r\n#### Step 2 ####\r\n\r\nCreating the class that inherits the `WebSocketService` class.\r\n\r\nFor example, if you would like to provide an echo service,\r\n\r\n```cs\r\nusing System;\r\nusing WebSocketSharp;\r\nusing WebSocketSharp.Server;\r\n\r\npublic class Echo : WebSocketService\r\n{\r\n  protected override void OnMessage (MessageEventArgs e)\r\n  {\r\n    Send (e.Data);\r\n  }\r\n}\r\n```\r\n\r\nAnd if you would like to provide a chat service,\r\n\r\n```cs\r\nusing System;\r\nusing WebSocketSharp;\r\nusing WebSocketSharp.Server;\r\n\r\npublic class Chat : WebSocketService\r\n{\r\n  private string _suffix;\r\n\r\n  public Chat ()\r\n    : this (null)\r\n  {\r\n  }\r\n\r\n  public Chat (string suffix)\r\n  {\r\n    _suffix = suffix ?? String.Empty;\r\n  }\r\n\r\n  protected override void OnMessage (MessageEventArgs e)\r\n  {\r\n    Sessions.Broadcast (e.Data + _suffix);\r\n  }\r\n}\r\n```\r\n\r\nIf you override the `WebSocketService.OnMessage (MessageEventArgs)` method, it's called when the `OnMessage` event of the `WebSocket` used by the current session in the WebSocket service occurs.\r\n\r\nAnd if you override the `WebSocketService.OnOpen ()`, `WebSocketService.OnError (ErrorEventArgs)`, and `WebSocketService.OnClose (CloseEventArgs)` methods, each of them is called when each event of the `WebSocket` (the `OnOpen`, `OnError`, and `OnClose`) occurs.\r\n\r\nThe `WebSocketService.Send` method sends a data to the client on the current session in the WebSocket service.\r\n\r\nIf you would like to access the sessions in the WebSocket service, you should use the `WebSocketService.Sessions` property (returns a `WebSocketSharp.Server.WebSocketSessionManager`).\r\n\r\nThe `WebSocketService.Sessions.Broadcast` method broadcasts a data to every client in the WebSocket service.\r\n\r\n#### Step 3 ####\r\n\r\nCreating an instance of the `WebSocketServer` class.\r\n\r\n```cs\r\nvar wssv = new WebSocketServer (4649);\r\nwssv.AddWebSocketService<Echo> (\"/Echo\");\r\nwssv.AddWebSocketService<Chat> (\"/Chat\");\r\nwssv.AddWebSocketService<Chat> (\"/ChatWithNiceBoat\", () => new Chat (\" Nice boat.\"));\r\n```\r\n\r\nYou can add any WebSocket service to your `WebSocketServer` with the specified path to the service, using the `WebSocketServer.AddWebSocketService<TWithNew> (string)` or `WebSocketServer.AddWebSocketService<T> (string, Func<T>)` method.\r\n\r\nThe type of `TWithNew` must inherit the `WebSocketService` class and must have a public parameterless constructor.\r\n\r\nThe type of `T` must inherit the `WebSocketService` class.\r\n\r\nSo you can use the classes created in **Step 2** to add the WebSocket service.\r\n\r\nIf you create an instance of the `WebSocketServer` class without a port number, the `WebSocketServer` set the port number to **80** automatically. So it's necessary to run with root permission.\r\n\r\n    $ sudo mono example2.exe\r\n\r\n#### Step 4 ####\r\n\r\nStarting the WebSocket server.\r\n\r\n```cs\r\nwssv.Start ();\r\n```\r\n\r\n#### Step 5 ####\r\n\r\nStopping the WebSocket server.\r\n\r\n```cs\r\nwssv.Stop (code, reason);\r\n```\r\n\r\nThe `WebSocketServer.Stop` method is overloaded.\r\n\r\nYou can use the `WebSocketServer.Stop ()`, `WebSocketServer.Stop (ushort, string)`, or `WebSocketServer.Stop (WebSocketSharp.CloseStatusCode, string)` method to stop the server.\r\n\r\n### HTTP Server with the WebSocket ###\r\n\r\nI modified the `System.Net.HttpListener`, `System.Net.HttpListenerContext`, and some other classes of **[Mono]** to create the HTTP server that allows to accept the WebSocket connection requests.\r\n\r\nSo websocket-sharp provides the `WebSocketSharp.Server.HttpServer` class.\r\n\r\nYou can add any WebSocket service to your `HttpServer` with the specified path to the service, using the `HttpServer.AddWebSocketService<TWithNew> (string)` or `HttpServer.AddWebSocketService<T> (string, Func<T>)` method.\r\n\r\n```cs\r\nvar httpsv = new HttpServer (4649);\r\nhttpsv.AddWebSocketService<Echo> (\"/Echo\");\r\nhttpsv.AddWebSocketService<Chat> (\"/Chat\");\r\nhttpsv.AddWebSocketService<Chat> (\"/ChatWithNiceBoat\", () => new Chat (\" Nice boat.\"));\r\n```\r\n\r\nFor more information, could you see **[Example3]**?\r\n\r\n### WebSocket Extensions ###\r\n\r\n#### Per-message Compression ####\r\n\r\nwebsocket-sharp supports the **[Per-message Compression][compression]** extension. (But it doesn't support with the [extension parameters].)\r\n\r\nIf you would like to enable this extension as a WebSocket client, you should set like the following.\r\n\r\n```cs\r\nws.Compression = CompressionMethod.DEFLATE;\r\n```\r\n\r\nAnd then your client sends the following header with the connection request to the server.\r\n\r\n    Sec-WebSocket-Extensions: permessage-deflate\r\n\r\nIf the server supports this extension, it returns the same header. And when your client receives that header, it enables this extension.\r\n\r\n### Secure Connection ###\r\n\r\nwebsocket-sharp supports the **Secure Connection (SSL)**.\r\n\r\nAs a **WebSocket Client**, you should create an instance of the `WebSocket` class with the **wss** scheme WebSocket URL to connect.\r\n\r\n```cs\r\nusing (var ws = new WebSocket (\"wss://example.com\")) {\r\n  ...\r\n}\r\n```\r\n\r\nAnd if you would like to set the custom validation for the server certificate, you should set the `WebSocket.ServerCertificateValidationCallback` property.\r\n\r\n```cs\r\nws.ServerCertificateValidationCallback = (sender, certificate, chain, sslPolicyErrors) => {\r\n  // Do something to validate the server certificate.\r\n  return true; // If the server certificate is valid.\r\n};\r\n```\r\n\r\nIf you set this property to nothing, the validation does nothing with the server certificate and returns valid.\r\n\r\nAs a **WebSocket Server**, you should create an instance of the `WebSocketServer` or `HttpServer` class with some settings for the secure connection. It's like the following.\r\n\r\n```cs\r\nvar wssv = new WebSocketServer (4649, true);\r\nwssv.Certificate = new X509Certificate2 (\"/path/to/cert.pfx\", \"password for cert.pfx\");\r\n```\r\n\r\n### HTTP Authentication ###\r\n\r\nwebsocket-sharp supports the **[HTTP Authentication (Basic/Digest)][rfc2617]**.\r\n\r\nAs a **WebSocket Client**, you should set a pair of user name and password for the HTTP authentication, using the `WebSocket.SetCredentials (string, string, bool)` method before connecting.\r\n\r\n```cs\r\nws.SetCredentials (username, password, preAuth);\r\n```\r\n\r\nIf `preAuth` is `true`, the `WebSocket` sends the Basic authentication credentials with the first connection request to the server.\r\n\r\nOr if `preAuth` is `false`, the `WebSocket` sends either the Basic or Digest authentication (determined by the unauthorized response to the first connection request) credentials with the second connection request to the server.\r\n\r\nAs a **WebSocket Server**, you should set an HTTP authentication scheme, a realm, and any function to find the user credentials before starting. It's like the following.\r\n\r\n```cs\r\nwssv.AuthenticationSchemes = AuthenticationSchemes.Basic;\r\nwssv.Realm = \"WebSocket Test\";\r\nwssv.UserCredentialsFinder = identity => {\r\n  var expected = \"nobita\";\r\n  return identity.Name == expected\r\n         ? new NetworkCredential (expected, \"password\", \"gunfighter\") // User name, password, and roles\r\n         : null; // If the user credentials not found.\r\n};\r\n```\r\n\r\nIf you would like to provide the Digest authentication, you should set like the following.\r\n\r\n```cs\r\nwssv.AuthenticationSchemes = AuthenticationSchemes.Digest;\r\n```\r\n\r\n### Logging ###\r\n\r\nThe `WebSocket` class includes the own logging function.\r\n\r\nYou can access it with the `WebSocket.Log` property (returns a `WebSocketSharp.Logger`).\r\n\r\nSo 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.\r\n\r\n```cs\r\nws.Log.Level = LogLevel.DEBUG;\r\n```\r\n\r\nThis means a log with less than `LogLevel.DEBUG` cannot be outputted.\r\n\r\nAnd if you would like to output a log, you should use any of the output methods. The following outputs a log with `LogLevel.DEBUG`.\r\n\r\n```cs\r\nws.Log.Debug (\"This is a debug message.\");\r\n```\r\n\r\nThe `WebSocketServer` and `HttpServer` classes include the same logging function.\r\n\r\n## Examples ##\r\n\r\nExamples using **websocket-sharp**.\r\n\r\n### Example ###\r\n\r\n**[Example]** connects to the **[Echo server]** with the WebSocket.\r\n\r\n### Example1 ###\r\n\r\n**[Example1]** connects to the **[Audio Data delivery server]** with the WebSocket. (But it's only implemented the chat feature, still unfinished.)\r\n\r\nAnd Example1 uses **[Json.NET]**.\r\n\r\n### Example2 ###\r\n\r\n**[Example2]** starts a WebSocket server.\r\n\r\n### Example3 ###\r\n\r\n**[Example3]** starts an HTTP server that allows to accept the WebSocket connection requests.\r\n\r\nCould you access to [http://localhost:4649](http://localhost:4649) to do **WebSocket Echo Test** with your web browser after Example3 running?\r\n\r\n## Supported WebSocket Specifications ##\r\n\r\nwebsocket-sharp supports **[RFC 6455][rfc6455]** and is based on the following WebSocket references.\r\n\r\n- **[The WebSocket Protocol][rfc6455]**\r\n- **[The WebSocket API][api]**\r\n- **[Compression Extensions for WebSocket][compression]**\r\n\r\nThanks for translating to japanese.\r\n\r\n- **[The WebSocket Protocol 日本語訳][rfc6455_ja]**\r\n- **[The WebSocket API 日本語訳][api_ja]**\r\n\r\n## License ##\r\n\r\nwebsocket-sharp is provided under **[The MIT License]**.\r\n\r\n\r\n[Audio Data delivery server]: http://agektmr.node-ninja.com:3000\r\n[Echo server]: http://www.websocket.org/echo.html\r\n[Example]: https://github.com/sta/websocket-sharp/tree/master/Example\r\n[Example1]: https://github.com/sta/websocket-sharp/tree/master/Example1\r\n[Example2]: https://github.com/sta/websocket-sharp/tree/master/Example2\r\n[Example3]: https://github.com/sta/websocket-sharp/tree/master/Example3\r\n[Json.NET]: http://james.newtonking.com/projects/json-net.aspx\r\n[Mono]: http://www.mono-project.com\r\n[MonoDevelop]: http://monodevelop.com\r\n[NuGet Gallery]: http://www.nuget.org\r\n[NuGet Gallery: websocket-sharp]: http://www.nuget.org/packages/WebSocketSharp\r\n[The MIT License]: https://raw.github.com/sta/websocket-sharp/master/LICENSE.txt\r\n[Unity]: http://unity3d.com\r\n[WebSocket-Sharp for Unity]: http://u3d.as/content/sta-blockhead/websocket-sharp-for-unity\r\n[api]: http://www.w3.org/TR/websockets\r\n[api_ja]: http://www.hcn.zaq.ne.jp/___/WEB/WebSocket-ja.html\r\n[compression]: http://tools.ietf.org/html/draft-ietf-hybi-permessage-compression-09\r\n[extension parameters]: http://tools.ietf.org/html/draft-ietf-hybi-permessage-compression-09#section-8.1\r\n[rfc2617]: http://tools.ietf.org/html/rfc2617\r\n[rfc6455]: http://tools.ietf.org/html/rfc6455\r\n[rfc6455_ja]: http://www.hcn.zaq.ne.jp/___/WEB/RFC6455-ja.html\r\n","google":"UA-9752433-2","note":"Don't delete this file! It's used internally to help with page regeneration."}