SNF's Connection(s)

Table of Contents

• Instantiate a new Connection object
  • In case of a Single Connection
  • In case of multiple Connections
• Set Event CallBacks
  • OnConnection
  • OnException
  • OnSNFFail
  • OnSocketFail
  • OnTimeout
• Connect
• Wait for the Connection
• Send Requests
  • In case of a non-Global Instance
  • In case of a Global Instance
• Practical Example

◄ Previous: SNF's OPCodes

This shows you how to handle anything related to connections You can jump to Practical Example to see how it can be used and sat up.

---

To properly setup the connection instance(s) you have to go through 5 steps:

• Instantiate a new Connection object
• Set Event CallBacks
• Connect
• Wait for the Connection Mandatory if you're waiting for the instance to connect
• Send Requests

Instantiate a new Connection object

Never call new Connection() to get a new object instance, instead you are advised to use either one of the following methods depending on your use case

In case of a Single Connection

If you only need one connection to one server then preferably use the global instantiator, and always use the methods made for the global instance for sending/receiving requests.

The Global instantiator method is SNFClient::Connection::Instantiate() which require no arguments and shall return a SNFClient::Connection 'The Global Instance Connection Instance'

Note

You must set the Global Instance's Host and port before continuing any further.
The method returns the instance so you can set them like the following example

SNFClient.Connection.Instantiate()
                    .SetHost("<URL>")
                    .SetPort(<PORT>);

In case of multiple Connections

To create multiple Connections ( or Connection Instances ) you must use the SNFClient::Connection::Instantiate(string,int) Method like in this example

SNFClient.Connection cnx = SNFClient.Connection.Instantiate(
        /// SNF Host's URL
        "<URL>",
        /// SNF Host's port
        <PORT>
    );

Set Event CallBacks

SNF Connections currenty has 5 Event Callbacks each serving a purpose

Warning

Never Set any Event Callback after(if it connected) and/or while Connecting

• OnConnection
• OnException
• OnSNFFail
• OnSocketFail
• OnTimeout

OnConnection

When is it Called?: This Event will raised when a connection was established and SNF's Protocol has finished the initial handshake
Type of CallBack: SimpleCB
How to Set: SetOnConnection(SimpleCB)
Method 1:

• Define the callback
  

  void OnConnectCallBack() {
      ...
      /// The Callback Content
      ...
  }

• Set the CallBack

  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
  ...
   
  cnx.SetOnConnection(OnConnectCallBack);
   
  ...

Method 2:

• Define the callback and Set it directly

  ...
   
  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
   
  cnx.SetOnConnection(
      () => {
          ...
          /// The Callback Content
          ...
      }
  );
   
  ...

OnException

When is it Called?: This Event is raised when a certain(and possibly unknown) exception was called and wasn't handled properly by SNFClient
Type of CallBack: ExceptionCB
How to Set: SetOnException(ExceptionCB)
Method 1:

• Define the callback
  

  void OnExceptionCallBack(Exception ex) {
      ...
      /// The Callback Content
      ...
  }

• Set the CallBack

  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
  ...
   
  cnx.SetOnException(OnExceptionCallBack);
   
  ...

Method 2:

• Define the callback and Set it directly

  ...
   
  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
   
  cnx.SetOnException(
      (Exception ex) => {
          ...
          /// The Callback Content
          ...
      }
  );
   
  ...

OnSNFFail

When is it Called?: This Event is raised when SNF's Protocol has failed the initial handshake
Type of CallBack: SimpleCB
How to Set: SetOnSNFFail(SimpleCB)
Method 1:

• Define the callback
  

  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
  void OnSNFFailCallBack() {
      ...
      /// The Callback Content
      ...
  }

• Set the CallBack

  ...
  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
   
  cnx.SetOnSNFFail(OnSNFFailCallBack);
   
  ...

Method 2:

• Define the callback and Set it directly

  ...
  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
   
  cnx.SetOnSNFFail(
      () => {
          ...
          /// The Callback Content
          ...
      }
  );
   
  ...

OnSocketFail

When is it Called?: This Event is raised when the Socket Connection between the client and the Server has raised a SocketException
Type of CallBack: SocketExceptionCB
How to Set: SetOnSocketFail(SocketExceptionCB)
Method 1:

• Define the callback
  

  void OnSocketFailCallBack(SocketException ex) {
      ...
      /// The Callback Content
      ...
  }

• Set the CallBack

  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
  ...
   
  cnx.SetOnSocketFail(OnSocketFailCallBack);
   
  ...

Method 2:

• Define the callback and Set it directly

  ...
   
  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
   
  cnx.SetOnSNFFail(
      (SocketException ex) => {
          ...
          /// The Callback Content
          ...
      }
  );
   
  ...

OnTimeout

When is it Called?: This Event is raised when the Connection attempt has exceeded the timeout limit set by AwaitConnection(..)
Type of CallBack: SimpleCB
How to Set: SetOnTimeout(SimpleCB)
Method 1:

• Define the callback
  

  void OnSocketFailCallBack(SocketException ex) {
      ...
      /// The Callback Content
      ...
  }

• Set the CallBack

  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
  ...
   
  cnx.SetOnSocketFail(OnSocketFailCallBack);
   
  ...

Method 2:

• Define the callback and Set it directly

  ...
   
  /// Assume this is the isntantiated `Connection` object
  /// TIP: 
  /// If it a Globaly Instantiated Object,
  /// 'cnx' 's value equals Connection.get()
  /// or use Connection.get() directly
  Connection cnx;
   
  cnx.SetOnSNFFail(
      (SocketException ex) => {
          ...
          /// The Callback Content
          ...
      }
  );
   
  ...

Connect

To Connect is pretty Simple you, just call Connect

Note

Always configure the Connection and the event Callback before calling Connect

Warning

Connect May Return null so be Aware

...
 
/// Assume this is the isntantiated `Connection` object
/// TIP: 
/// If it a Globaly Instantiated Object,
/// 'cnx' 's value equals Connection.get()
/// or use Connection.get() directly
Connection cnx;
 
 
cnx.Connect();
 
...

Wait for the Connection

There are 2 Methods made to Await util the Connection is made,

1. AwaitConnection(int) Which Counts in Miliseconds
2. AwaitConnection(TimeSpan) that uses TimeSpan .

I will only give an example of the former

Warning

Always wait for the connection after calling Connect

...
 
/// Timeout of 5 Seconds
cnx.AwaitConenction(5000);
 
...

Send Requests

Remarks

Follow SNF's Request(s) tutorial to know how to generate your Request object

Assuming you have instantiated a new Request Object and Set it properly, we can send it according to your use case

Note

Preferably Always Send after the Connection Instance has Connected (eg isConnected returns true )

In case of a non-Global Instance

For this case (Assuming cnx is your Connection Instance and that Rqst is your Request instance that you want to send ) you can use Send(Request)

...
cnx.Send(Rqst);
...

In case of a Global Instance

For this case you can use the same Method as the In case of a non-Global Instance which is pecefic to Global Instances (Method 1) or the Function ( Method 2 )

Note

We'll assume that Rqst is your Request instance that you want to Send

Method 1 Using InstanceSend(Request)

...
 
Connection.InstanceSend(Rqst);
 
...

Method 2 Using Send(Request)

...
Connection cnx = Connection.get();
 
cnx.Send(Rqst)
 
/// Or
 
Connection.get().Send(Rqst);
...

Practical Example

In this Example I'm gonna create a Console Client that creates a globally instantiated Connection that connects into a SNF Server hosted in the same machine on port 9114

using SNFClient;
 
namespace Example
{
    public class Program
    {
        public static void Main(string[] args)
        {
            /// Always Initialize OPCode.Base before anything
            OPCode.Base.Initialize();
 
            /// Instanstiate a Global instance
            Connection.Instantiate()
                /// Set the Host
                .SetHost("127.0.0.1")
                /// Set the Port
                .SetPort(9114)
                /// Set the OnConnection Event Callback
                .SetOnConnection(
                    () => {
                        Console.WriteLine("Connected");
                    }
                )
                /// Set the OnSocketFail Event Callback
                .SetOnSocketFail(
                    (ex) => { 
                        Console.WriteLine("SocketFailed: " + ex.ToString()); 
                    }
                )
                /// Set the OnSNFFail Event Callback
                .SetOnSNFFail(
                    () => {
                        Console.WriteLine("SNF HandShake Failed");
                    }
                )
                /// Set the OnException Event Callback
                .SetOnException(
                    (ex) =>
                    {
                        Console.WriteLine("Unknown Exception" + ex.ToString());
                    }
                )
                /// Attempt To Connect
                .Connect()?
                /// if Connect Returned the Connection Instance
                /// Properly It will wait until it Connects or 10s Passes
                .AwaitConnection(10000);
 
            ...
        }
    }
}

---

Next: SNF's Request(s) ►