Class WebSocket

Implements the WebSocket interface.

Inheritance

System.Object

WebSocket

Implements

System.IDisposable

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Mars.Common.Socket

Assembly: Mars.Common.dll

Syntax

public class WebSocket : IDisposable

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Constructors

WebSocket(String, String[])

Initializes a new instance of the WebSocket class with url and protocols.

Declaration

public WebSocket(string url, params string[] protocols)

Parameters

Type	Name	Description
System.String	url	A System.String that specifies the URL of the WebSocket server to connect.
System.String[]	protocols	An array of System.String that specifies the names of the subprotocols if necessary. Each value of the array must be a token defined in RFC 2616 .

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Exceptions

Type	Condition
System.ArgumentNullException	url is null.
System.ArgumentException	url is an empty string. -or- url is an invalid WebSocket URL string. -or- protocols contains a value that is not a token. -or- protocols contains a value twice.

Fields

FragmentLength

Represents the length used to determine whether the data should be fragmented in sending.

Declaration

public static int FragmentLength

Field Value

Type	Description
System.Int32

Remarks

The data will be fragmented if that length is greater than the value of this field.

If you would like to change the value, you must set it to a value between 125 and Int32.MaxValue - 14 inclusive.

Properties

Compression

Gets or sets the compression method used to compress a message.

Declaration

public CompressionMethod Compression { get; set; }

Property Value

Type	Description
CompressionMethod	One of the CompressionMethod enum values. It represents the compression method used to compress a message. The default value is None.

Remarks

The set operation does nothing if the connection has already been established or it is closing.

Exceptions

Type	Condition
System.InvalidOperationException	The set operation cannot be used by servers.

EmitOnPing

Gets or sets a value indicating whether the WebSocket emits a OnMessage event when receives a ping.

Declaration

public bool EmitOnPing { get; set; }

Property Value

Type	Description
System.Boolean	true if the WebSocket emits a OnMessage event when receives a ping; otherwise, false. The default value is false.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

EnableRedirection

Gets or sets a value indicating whether the URL redirection for the handshake request is allowed.

Declaration

public bool EnableRedirection { get; set; }

Property Value

Type	Description
System.Boolean	true if the URL redirection for the handshake request is allowed; otherwise, false. The default value is false.

Remarks

The set operation does nothing if the connection has already been established or it is closing.

Exceptions

Type	Condition
System.InvalidOperationException	The set operation cannot be used by servers.

Extensions

Gets the WebSocket extensions selected by the server.

Declaration

public string Extensions { get; }

Property Value

Type	Description
System.String	A System.String that represents the extensions if any. The default value is System.String.Empty.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

IsAlive

Gets a value indicating whether the WebSocket connection is alive.

Declaration

public bool IsAlive { get; }

Property Value

Type	Description
System.Boolean	true if the connection is alive; otherwise, false.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Origin

Gets or sets the value of the HTTP Origin header to send with the handshake request.

Declaration

public string Origin { get; set; }

Property Value

Type	Description
System.String	A System.String that represents the value of the Origin header to send. The syntax is <scheme>://<host>[:<port>]. The default value is null.

Remarks

The HTTP Origin header is defined in Section 7 of RFC 6454 .

This instance sends the Origin header if this property has any.

The set operation does nothing if the connection has already been established or it is closing.

Exceptions

Type	Condition
System.InvalidOperationException	The set operation is not available if this instance is not a client.
System.ArgumentException	The value specified for a set operation is not an absolute URI string. -or- The value specified for a set operation includes the path segments.

Protocol

Gets the WebSocket subprotocol selected by the server.

Declaration

public string Protocol { get; }

Property Value

Type	Description
System.String	A System.String that represents the subprotocol if any. The default value is System.String.Empty.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

ReadyState

Gets the state of the WebSocket connection.

Declaration

public WebSocketState ReadyState { get; }

Property Value

Type	Description
WebSocketState	One of the WebSocketState enum values that indicates the current state of the connection. The default value is Connecting.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Url

Gets the WebSocket URL used to connect, or accepted.

Declaration

public Uri Url { get; }

Property Value

Type	Description
System.Uri	A System.Uri that represents the URL used to connect, or accepted.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

WaitTime

Gets or sets the time to wait for the response to the ping or close.

Declaration

public TimeSpan WaitTime { get; set; }

Property Value

Type	Description
System.TimeSpan	A System.TimeSpan to wait for the response. The default value is the same as 5 seconds if the instance is a client.

Remarks

The set operation does nothing if the connection has already been established or it is closing.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The value specified for a set operation is zero or less.

Methods

Accept()

Accepts the WebSocket handshake request.

Declaration

public void Accept()

Remarks

This method is not available in a client.

AcceptAsync()

Accepts the WebSocket handshake request asynchronously.

Declaration

public void AcceptAsync()

Remarks

This method does not wait for the accept to be complete.

This method is not available in a client.

Close()

Closes the connection.

Declaration

public void Close()

Remarks

This method does nothing if the current state of the connection is Closing or Closed.

Close(CloseStatusCode, String)

Closes the connection with the specified code and reason.

Declaration

public void Close(CloseStatusCode code, string reason)

Parameters

Type	Name	Description
CloseStatusCode	code	One of the CloseStatusCode enum values. It represents the status code indicating the reason for the close.
System.String	reason	A System.String that represents the reason for the close. The size must be 123 bytes or less in UTF-8.

Remarks

This method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentException	code is ServerError. It cannot be used by clients. -or- code is MandatoryExtension. It cannot be used by servers. -or- code is NoStatus and there is reason. -or- reason could not be UTF-8-encoded.
System.ArgumentOutOfRangeException	The size of reason is greater than 123 bytes.

Close(CloseStatusCode)

Closes the connection with the specified code.

Declaration

public void Close(CloseStatusCode code)

Parameters

Type	Name	Description
CloseStatusCode	code	One of the CloseStatusCode enum values. It represents the status code indicating the reason for the close.

Remarks

This method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentException	code is ServerError. It cannot be used by clients. -or- code is MandatoryExtension. It cannot be used by servers.

Close(UInt16, String)

Closes the connection with the specified code and reason.

Declaration

public void Close(ushort code, string reason)

Parameters

Type	Name	Description
System.UInt16	code	A System.UInt16 that represents the status code indicating the reason for the close. The status codes are defined in Section 7.4 of RFC 6455.
System.String	reason	A System.String that represents the reason for the close. The size must be 123 bytes or less in UTF-8.

Remarks

This method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	code is less than 1000 or greater than 4999. -or- The size of reason is greater than 123 bytes.
System.ArgumentException	code is 1011 (server error). It cannot be used by clients. -or- code is 1010 (mandatory extension). It cannot be used by servers. -or- code is 1005 (no status) and there is reason. -or- reason could not be UTF-8-encoded.

Close(UInt16)

Closes the connection with the specified code.

Declaration

public void Close(ushort code)

Parameters

Type	Name	Description
System.UInt16	code	A System.UInt16 that represents the status code indicating the reason for the close. The status codes are defined in Section 7.4 of RFC 6455.

Remarks

This method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	code is less than 1000 or greater than 4999.
System.ArgumentException	code is 1011 (server error). It cannot be used by clients. -or- code is 1010 (mandatory extension). It cannot be used by servers.

CloseAsync()

Closes the connection asynchronously.

Declaration

public void CloseAsync()

Remarks

This method does not wait for the close to be complete.

And this method does nothing if the current state of the connection is Closing or Closed.

CloseAsync(CloseStatusCode, String)

Closes the connection asynchronously with the specified code and reason.

Declaration

public void CloseAsync(CloseStatusCode code, string reason)

Parameters

Type	Name	Description
CloseStatusCode	code	One of the CloseStatusCode enum values. It represents the status code indicating the reason for the close.
System.String	reason	A System.String that represents the reason for the close. The size must be 123 bytes or less in UTF-8.

Remarks

This method does not wait for the close to be complete.

And this method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentException	code is ServerError. It cannot be used by clients. -or- code is MandatoryExtension. It cannot be used by servers. -or- code is NoStatus and there is reason. -or- reason could not be UTF-8-encoded.
System.ArgumentOutOfRangeException	The size of reason is greater than 123 bytes.

CloseAsync(CloseStatusCode)

Closes the connection asynchronously with the specified code.

Declaration

public void CloseAsync(CloseStatusCode code)

Parameters

Type	Name	Description
CloseStatusCode	code	One of the CloseStatusCode enum values. It represents the status code indicating the reason for the close.

Remarks

This method does not wait for the close to be complete.

And this method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentException	code is ServerError. It cannot be used by clients. -or- code is MandatoryExtension. It cannot be used by servers.

CloseAsync(UInt16, String)

Closes the connection asynchronously with the specified code and reason.

Declaration

public void CloseAsync(ushort code, string reason)

Parameters

Type	Name	Description
System.UInt16	code	A System.UInt16 that represents the status code indicating the reason for the close. The status codes are defined in Section 7.4 of RFC 6455.
System.String	reason	A System.String that represents the reason for the close. The size must be 123 bytes or less in UTF-8.

Remarks

This method does not wait for the close to be complete.

And this method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	code is less than 1000 or greater than 4999. -or- The size of reason is greater than 123 bytes.
System.ArgumentException	code is 1011 (server error). It cannot be used by clients. -or- code is 1010 (mandatory extension). It cannot be used by servers. -or- code is 1005 (no status) and there is reason. -or- reason could not be UTF-8-encoded.

CloseAsync(UInt16)

Closes the connection asynchronously with the specified code.

Declaration

public void CloseAsync(ushort code)

Parameters

Type	Name	Description
System.UInt16	code	A System.UInt16 that represents the status code indicating the reason for the close. The status codes are defined in Section 7.4 of RFC 6455.

Remarks

This method does not wait for the close to be complete.

And this method does nothing if the current state of the connection is Closing or Closed.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	code is less than 1000 or greater than 4999.
System.ArgumentException	code is 1011 (server error). It cannot be used by clients. -or- code is 1010 (mandatory extension). It cannot be used by servers.

Connect()

Establishes a WebSocket connection.

Declaration

public void Connect()

Remarks

This method is not available in a server.

ConnectAsync()

Establishes a WebSocket connection asynchronously.

Declaration

public void ConnectAsync()

Remarks

This method does not wait for the connect to be complete.

This method is not available in a server.

Ping()

Sends a ping using the WebSocket connection.

Declaration

public bool Ping()

Returns

Type	Description
System.Boolean	true if the send has done with no error and a pong has been received within a time; otherwise, false.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Ping(String)

Sends a ping with message using the WebSocket connection.

Declaration

public bool Ping(string message)

Parameters

Type	Name	Description
System.String	message	A System.String that represents the message to send. The size must be 125 bytes or less in UTF-8.

Returns

Type	Description
System.Boolean	true if the send has done with no error and a pong has been received within a time; otherwise, false.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Exceptions

Type	Condition
System.ArgumentException	message could not be UTF-8-encoded.
System.ArgumentOutOfRangeException	The size of message is greater than 125 bytes.

Send(Byte[])

Sends data using the WebSocket connection.

Declaration

public void Send(byte[] data)

Parameters

Type	Name	Description
System.Byte[]	data	An array of System.Byte that represents the binary data to send.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	data is null.

Send(FileInfo)

Sends the specified file using the WebSocket connection.

Declaration

public void Send(FileInfo fileInfo)

Parameters

Type	Name	Description
System.IO.FileInfo	fileInfo	A System.IO.FileInfo that specifies the file to send.

Remarks

The file is sent as the binary data.

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	fileInfo is null.
System.ArgumentException	The file does not exist. -or- The file could not be opened.

Send(Stream, Int32)

Sends the data from stream using the WebSocket connection.

Declaration

public void Send(Stream stream, int length)

Parameters

Type	Name	Description
System.IO.Stream	stream	A System.IO.Stream instance from which to read the data to send.
System.Int32	length	An System.Int32 that specifies the number of bytes to send.

Remarks

The data is sent as the binary data.

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	stream is null.
System.ArgumentException	stream cannot be read. -or- length is less than 1. -or- No data could be read from stream.

Send(String)

Sends data using the WebSocket connection.

Declaration

public void Send(string data)

Parameters

Type	Name	Description
System.String	data	A System.String that represents the text data to send.

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	data is null.
System.ArgumentException	data could not be UTF-8-encoded.

SendAsync(Byte[], Action<Boolean>)

Sends data asynchronously using the WebSocket connection.

Declaration

public void SendAsync(byte[] data, Action<bool> completed)

Parameters

Type	Name	Description
System.Byte[]	data	An array of System.Byte that represents the binary data to send.
System.Action<System.Boolean>	completed	An Action<bool> delegate or null if not needed. The delegate invokes the method called when the send is complete. true is passed to the method if the send has done with no error; otherwise, false.

Remarks

This method does not wait for the send to be complete.

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	data is null.

SendAsync(FileInfo, Action<Boolean>)

Sends the specified file asynchronously using the WebSocket connection.

Declaration

public void SendAsync(FileInfo fileInfo, Action<bool> completed)

Parameters

Type	Name	Description
System.IO.FileInfo	fileInfo	A System.IO.FileInfo that specifies the file to send.
System.Action<System.Boolean>	completed	An Action<bool> delegate or null if not needed. The delegate invokes the method called when the send is complete. true is passed to the method if the send has done with no error; otherwise, false.

Remarks

The file is sent as the binary data.

This method does not wait for the send to be complete.

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	fileInfo is null.
System.ArgumentException	The file does not exist. -or- The file could not be opened.

SendAsync(Stream, Int32, Action<Boolean>)

Sends the data from stream asynchronously using the WebSocket connection.

Declaration

public void SendAsync(Stream stream, int length, Action<bool> completed)

Parameters

Type	Name	Description
System.IO.Stream	stream	A System.IO.Stream instance from which to read the data to send.
System.Int32	length	An System.Int32 that specifies the number of bytes to send.
System.Action<System.Boolean>	completed	An Action<bool> delegate or null if not needed. The delegate invokes the method called when the send is complete. true is passed to the method if the send has done with no error; otherwise, false.

Remarks

The data is sent as the binary data.

This method does not wait for the send to be complete.

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	stream is null.
System.ArgumentException	stream cannot be read. -or- length is less than 1. -or- No data could be read from stream.

SendAsync(String, Action<Boolean>)

Sends data asynchronously using the WebSocket connection.

Declaration

public void SendAsync(string data, Action<bool> completed)

Parameters

Type	Name	Description
System.String	data	A System.String that represents the text data to send.
System.Action<System.Boolean>	completed	An Action<bool> delegate or null if not needed. The delegate invokes the method called when the send is complete. true is passed to the method if the send has done with no error; otherwise, false.

Remarks

This method does not wait for the send to be complete.

Exceptions

Type	Condition
System.InvalidOperationException	The current state of the connection is not Open.
System.ArgumentNullException	data is null.
System.ArgumentException	data could not be UTF-8-encoded.

Events

OnClose

Occurs when the WebSocket connection has been closed.

Declaration

public event EventHandler<CloseEventArgs> OnClose

Event Type

Type	Description
System.EventHandler<CloseEventArgs>

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

OnError

Occurs when the WebSocket gets an error.

Declaration

public event EventHandler<ErrorEventArgs> OnError

Event Type

Type	Description
System.EventHandler<ErrorEventArgs>

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

OnMessage

Occurs when the WebSocket receives a message.

Declaration

public event EventHandler<MessageEventArgs> OnMessage

Event Type

Type	Description
System.EventHandler<MessageEventArgs>

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

OnOpen

Occurs when the WebSocket connection has been established.

Declaration

public event EventHandler OnOpen

Event Type

Type	Description
System.EventHandler

Remarks

The WebSocket class provides a set of methods and properties for two-way communication using the WebSocket protocol (RFC 6455).

Explicit Interface Implementations

IDisposable.Dispose()

Closes the connection and releases all associated resources.

Declaration

void IDisposable.Dispose()

Remarks

This method closes the connection with close status 1001 (going away).

And this method does nothing if the current state of the connection is Closing or Closed.

Implements

System.IDisposable

Extension Methods

Serializer.Save<T>(T, out Byte[], SerializerCompression)

Serializer.Save<T>(T, Stream, SerializerCompression)

Serializer.Save<T>(T, BinaryFormatter, Stream, SerializerCompression)

Serializer.Save<T>(T, String, SerializerCompression)

Serializer.Save<T>(T, String)

Matrix.Concatenate<T>(T, T[])

Matrix.Replace<T>(T, Object, Object)

DomainDataImporter.Import(Object, InputConfiguration)

ObjectSerialize.Serialize(Object)

Matrix.IsEqual(Object, Object, Decimal, Decimal)