Tcp.NET

Tcp.NET provides a robust, performant, easy-to-use, and extendible Tcp server and Tcp client with included authorization / authentication to identify clients connected to your server. All Tcp.NET packages referenced in this documentation are available on the NuGet package manager as separate packages (Tcp.NET.Client or Tcp.NET.Server) or in 1 aggregate package (Tcp.NET). It has a sister-package called WebsocketsSimple which follows the same patterns but for Websocket Clients and Servers.

Table of Contents<!-- omit in toc -->

• TcpNETClient
  • Parameters
  • Token
  • Events
  • SSL
  • Connect to a Tcp Server
  • Send a Message to the Server
  • Ping
  • Disconnect from the Server
  • Disposal
• TcpNETServer
  • Parameters
  • Events
  • SSL
  • Start the Server
  • Send a Message
  • Ping
  • Disconnect a Connection
  • Stop the Server
  • Disposal
• TcpNETServerAuth<T>
  • Parameters
  • IUserService<T>
  • Events
  • SSL
  • Start the Server
  • Send a Message
  • Ping
  • Disconnect a Connection
  • Stop the Server
  • Disposal
• Additional Information

---

Client

TcpNETClient

First install Tcp.NET.Client NuGet package using the NuGet package manager:

install-package Tcp.NET.Client

This will add the most-recent version of Tcp.NET.Client package to your specified project.

Create a variable of type ITcpNETClient with the included implementation TcpNETClient.

Signature:

• TcpNETClient(ParamsTcpClient parameters) : ITcpNETClient

ParamsTcpClientByes can be used instead to specify EndOfLineCharacters, PingCharacters, and PongCharacters as byte arrays:

• TcpNETClient(ParamsTcpClientBytes parameters) : ITcpNETClient

Example ParamsTcpClient:

    ITcpNETClient client = new TcpNETClient(new ParamsTcpClient("connect.tcp.net", 8989, "\r\n", isSSL: false);

Example ParamsTcpClientBytes:

    var eol = System.Encoding.UTF8.GetBytes("\r\n");
    ITcpNETClient client = new TcpNETClient(new ParamsTcpClientBytes("connect.tcp.net", 8989, eol, isSSL: false);

Parameters

• ParamsTcpClient - Required - Contains the following connection detail data:
  • Host - int - Required - The host or URI of the Tcp server instance to connect (e.g. connect.tcp.net, localhost, 127.0.0.1, etc).
  • Port - int - Required - The port of the Tcp server instance to connect (e.g. 6660, 7210, 6483).
  • EndOfLineCharacters - string - Required - The Tcp protocol does not automatically include line termination symbols, but it has become common practice in many applications that the end-of-line symbol is \r\n which represents an Enter key for many operating systems. It is recommended you use \r\n as the line termination symbol.
  • Token - string - Optional - Optional parameter used by TcpNETServerAuth for authenticating a user. Defaults to null.
    • Generating and validating a token is outside the scope of this document, but for more information, check out OAuthServer.NET or IdentityServer4 for robust, easy-to-implemnt, and easy-to-use .NET identity servers.
    • A token can be any string. If wanting to use certificates, load the certs as a byte array, base64 encode them, and pass them as a string.
  • IsSSL - bool - Optional - Flag specifying if the connection should be made using SSL encryption when connecting to the server. Defaults to true.
  • OnlyEmitBytes - bool - Optional - Flag specifying if TcpNETClient should decode messages (Encoding.UTF8.GetString()) and return a string in MessageEvent or return only the raw byte array received. Defaults to false.
  • UsePingPong - bool - Optional - Flag specifying if the connection will listen for PingCharacters and return PongCharacters. If using TcpNETServer or TcpNETServerAuth<T>, ping/pong is enabled by default. If UsePingPong is set to false, the connection will be servered after the server's next ping cycle. Defaults to true.
  • PingCharacters - string - Optional - String specifying what string TcpNETClient will be listening for from the server to verify the connection is still alive. When this string is received, PongCharacters will immediately be returned. An overload is included where PingCharacters and PongCharacters are byte arrays and called PingBytes and PongBytes. Defaults to "ping".
  • PongCharacters - string - Optional - String specifying what string TcpNETClient will send to the server immediately after PingCharacters is received. An overload is included where PingCharacters and PongCharacters are byte arrays and called PingBytes and PongBytes. Defaults to "pong".
  • UseDisconnectBytes - bool - Optional - When TcpNETClient gracefully disconnects from the server (DisconnectAsync()), this flag specifies if the DisconnectBytes should be first sent to the server to signal a disconnect event. Defaults to true.
  • DisconnectBytes - byte[] - Optional - If UseDisconnectBytes is true, this byte array allows a custom byte array to be sent to the server to signal a client invoked disconnect. This is the default behaviour for TcpNETServer and TcpNETServerAuth<T>. If UseDisconnectBytes is true and DisconnectBytes is either null or an empty byte array, defaults to byte[] { 3 }.
• ParamsTcpClientByes can be used instead to specify EndOfLineCharacters, PingCharacters, and PongCharacters as byte arrays:
  • EndOfLineBytes - byte[] - Required - Defaults to byte[] { 13, 10 }.
  • PingBytes - byte[] - Optional - Defaults to byte[] { 112, 105, 110, 103 }.
  • PongBytes - byte[] - Optional - Defaults to byte[] { 112, 111, 110, 103 }.

Token

An optional parameter called Token is included in the constructor for ParamsTcpClient to authorize your client with TcpNETServerAuth<T> or a custom Tcp server. Upon a successful connection to the server, the Token you specify and the EndOfLineCharacters or **EndOfLineBytes**will immediately and automatically be sent to the server.

If you are creating a manual Tcp connection to an instance of TcpNETServerAuth<T>, the first message you must send to the server is your Token followed by EndOfLineCharacters or EndOfLineBytes. This could look similar to the following:

Example:

    yourOAuthTokenGoesHere\r\n

Events

3 events are exposed on the ITcpNETClient interface: MessageEvent, ConnectionEvent, and **ErrorEvent*. These event signatures are below:

Signatures:

• void MessageEvent(object sender, TcpMessageClientEventArgs args);
  • Invoked when a message is sent or received.
• void ConnectionEvent(object sender, TcpConnectionClientEventArgs args);
  • Invoked when TcpNETClient connects or disconnects from a server.
• void ErrorEvent(object sender, TcpErrorClientEventArgs args);
  • Wraps all logic in TcpNETClient with try catch statements and outputs the specific error(s).

Example:

    client.MessageEvent += OMessageEvent;
    client.ConnectionEvent += OnConnectionEvent;
    client.ErrorEvent += OnErrorEvent

SSL

SSL is enabled by default for TcpNETClient, but if you would like to disable SSL, set the IsSSL flag in ParamsTcpClient to true. In order to connect successfully to an SSL server, the server must have a valid, non-expired SSL certificate where the certificate's issued hostname matches the host specified in ParamsTcpClient.

Please note that a self-signed certificate or one from a non-trusted Certified Authority (CA) is not considered a valid SSL certificate.

**Connect to a T