This project is read-only.

IServer

This document explains the intent, thinking and code in the IServer interface

NetworkingLibrary-InitialRelease-IServer.png
(Above: Code overview of IServer)

IServer interface is to be implemented by all server classes. It provides a standard base from which all server classes can derive will allow easier and consistent use of the library.

IServer offers the very basic level of information that all servers should provide:

Properties:
  • AllClients : Returns how many connections the server currently holds (connections being taken to imply clients)
  • BufferSize : The size of the read/write buffers the server is using. This will allow configuration for different server's and machine's memory capacities. It does not actually affect the amount of data written/read with each message sent, only the maximum amount of data to handle for any one receive operation. Note: multiple receive operations may occur simultaneously. Default value is 1,000,000 meaning 1,000,000 bytes maximum.
  • Initialised : Whether the server has been initialised. Some server implementations may also wish to add a 'Running' or 'Started' property to track if the server is currently listening to requests or not.
  • MaxConnections : Determines the maximum number of connections (clients) a server will accept at any given time. If a client disconnects and AllClients.Count drops below maximum then new clients may be accepted. Different uses of servers require different maximum numbers of connections, therefore, no server implementation should specify a fixed MaxConenctions value, though defaults may vary. Exception to this is when the server type by it's very nature has to have a fixed number of connections, though I cannot think of an example myself.
  • Terminating : Whether the server is terminating or not. Once a server is terminating it cannot be stopped. If a server has terminated it cannot be restarted, it must be recreated. This gives better reliability and simplicity. (Also the reason a 'Started' property is not insisted upon because current running state should be determinable from Initialised and Terminated combined.)

Methods:
  • Initialise : Initialises the server but does not (necessarily) start the server. Should be called by the Start method before actually starting to ensure proper initialisation has occurred. This also means that Initialise does not need to be called externally.
  • _Send (+ 3 overloads) : Send at the most basic level send byte array data to clients. There are four variations described below:
    • Send(bye[] TheBuffer) : Should send data (to all clients) wrapped in a DataMessage object. Should call Send(MessageObject TheMessage) to actaully send the data.
    • Send(byte[] TheBuffer, Guid ExcludeId) : As above except message not sent to the excluded client (determined by ID) and use SendMessage(MessageObject TheMessage, Guid ExcludeID) to send.
    • _Send(MessageObject TheMessage) : Actually sends the message down to clients via relevant implementation. Use Utilities.Utilities.ToBytes(object TheObj) to convert MessageObject to byte array.
    • _Send(MessageObject TheMessage, Guid ExcludeID) : Same as above buts excludes the relevant client.
(NB: For examples of above see Servers.TCP.TCPSever implementation.)
(NB: For above it is advised (as seen in Servers.TCP.TCPSever) that one method accepting the MessageObject and a List<Clients.IClient>is used to send data so that code is not repeated. This means easier changes later and easier/more obvious/readable for later developers)
  • Start : Starts the server listening for data/connections.
  • Stop : Stops the server listening for connections and closes existing connections. Expected to set Terminating to true and to clean up existing connections abruptly without further correspondence except for sending a required DisconnectMessage just before closing the connection. This allows (especially in the case of TCP) more reliable and manageable clean up at the client end of the connection when it is terminated.

Events:
  • OnClientConnect : Fired when a connection is accepted by the server.
  • OnClientDisconnect : Fired when a connection is lost/ended.
  • OnError : Fired when any error, anywhere in the tree of methods, occurs. This is helpful for developers and can do no harm, however, intelligent try/catch blocks to handle exceptions are also necessary to stop things falling over completely.
  • OnMaxConnections : Fired whenever number of connections reaches equal to or more than (more than is possible due to async operations) MaxConnections. Do not fire when number of connections drops below MaxConnections.
  • OnMessageReceieved : Fired whenever a message is received. The event should be fired before any action is taken to process the message. Before processing the message, the MessageReceievedEventArgs should be checked fro PreventDefault. If set to false, continue with any processing,if set to true, all processing must be skipped. This allows easy overriding of default functionality by external code.
(NB: All events must be passed up down the chain - all must be fired - even when the server is anticipated to be the last inheriting class. You can never tell what another programmer might want to do.)

Last edited Dec 15, 2011 at 2:16 PM by EdwardNutting, version 5

Comments

No comments yet.