//******************************************************************************************************//  IServer.cs - Gbtc////  Copyright © 2010, Grid Protection Alliance.  All Rights Reserved.////  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See//  the NOTICE file distributed with this work for additional information regarding copyright ownership.//  The GPA licenses this file to you under the Eclipse Public License -v 1.0 (the "License"); you may//  not use this file except in compliance with the License. You may obtain a copy of the License at:////      http://www.opensource.org/licenses/eclipse-1.0.php////  Unless agreed to in writing, the subject software distributed under the License is distributed on an//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the//  License for the specific language governing permissions and limitations.////  Code Modification History://  ----------------------------------------------------------------------------------------------------//  07/26/2006 - Pinal C. Patel//       Original version of source code generated.//  09/06/2006 - J. Ritchie Carroll//       Added ReceiveRawDataFunction delegate to allow bypass optimizations for high-speed data access.//  09/29/2008 - J. Ritchie Carroll//       Converted to C#.//  11/07/2008 - Pinal C. Patel//       Edited code comments.//  09/14/2009 - Stephen C. Wills//       Added new header and license agreement.//  10/8/2012 - Danyelle Gilliam//        Modified Header////******************************************************************************************************     using GSF.Units;using System;using System.Text;using System.Threading; namespace GSF.Communication{    #region [ Enumerations ]     /// <summary>    /// Indicates the current state of the server.    /// </summary>    public enum ServerState    {        /// <summary>        /// Server is running.        /// </summary>        Running,        /// <summary>        /// Server is not running.        /// </summary>        NotRunning    }     #endregion     /// <summary>    /// Defines a server involved in server-client communication.    /// </summary>    public interface IServer : ISupportLifecycle, IProvideStatus    {        #region [ Members ]         // Events         /// <summary>        /// Occurs when the server is started.        /// </summary>        event EventHandler ServerStarted;         /// <summary>        /// Occurs when the server is stopped.        /// </summary>        event EventHandler ServerStopped;         /// <summary>        /// Occurs when a client connects to the server.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T}.Argument"/> is the ID of the client that connected to the server.        /// </remarks>        event EventHandler<EventArgs<Guid>> ClientConnected;         /// <summary>        /// Occurs when a client disconnects from the server.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T}.Argument"/> is the ID of the client that disconnected from the server.        /// </remarks>        event EventHandler<EventArgs<Guid>> ClientDisconnected;         /// <summary>        /// Occurs when data is being sent to a client.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T}.Argument"/> is the ID of the client to which the data is being sent.        /// </remarks>        event EventHandler<EventArgs<Guid>> SendClientDataStart;         /// <summary>        /// Occurs when data has been sent to a client.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T}.Argument"/> is the ID of the client to which the data has been sent.        /// </remarks>        event EventHandler<EventArgs<Guid>> SendClientDataComplete;         /// <summary>        /// Occurs when an <see cref="Exception"/> is encountered when sending data to a client.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T1,T2}.Argument1"/> is the ID of the client to which the data was being sent.<br/>        /// <see cref="EventArgs{T1,T2}.Argument2"/> is the <see cref="Exception"/> encountered when sending data to a client.        /// </remarks>        event EventHandler<EventArgs<Guid, Exception>> SendClientDataException;         /// <summary>        /// Occurs when unprocessed data has been received from a client.        /// </summary>        /// <remarks>        /// <para>        /// This event can be used to receive a notification that client data has arrived. The <see cref="Read"/> method can then be used        /// to copy data to an existing buffer. In many cases it will be optimal to use an existing buffer instead of subscribing to the        /// <see cref="ReceiveClientDataComplete"/> event, however, the data that is available after calling the <see cref="Read"/> method        /// will be the original unprocessed data received by the client, i.e., not optionally decrypted or decompressed data.        /// </para>        /// <para>        /// <see cref="EventArgs{T1,T2}.Argument1"/> is the ID of the client from which data is received.<br/>        /// <see cref="EventArgs{T1,T2}.Argument2"/> is the number of bytes received in the buffer from the client.        /// </para>        /// </remarks>        event EventHandler<EventArgs<Guid, int>> ReceiveClientData;         /// <summary>        /// Occurs when data received from a client has been processed and is ready for consumption.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T1,T2,T3}.Argument1"/> is the ID of the client from which data is received.<br/>        /// <see cref="EventArgs{T1,T2,T3}.Argument2"/> is a new buffer containing post-processed data received from the client starting at index zero.<br/>        /// <see cref="EventArgs{T1,T2,T3}.Argument3"/> is the number of post-processed bytes received in the buffer from the client.        /// </remarks>        event EventHandler<EventArgs<Guid, byte[], int>> ReceiveClientDataComplete;         /// <summary>        /// Occurs when an <see cref="Exception"/> is encountered when receiving data from a client.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T1,T2}.Argument1"/> is the ID of the client from which the data was being received.<br/>        /// <see cref="EventArgs{T1,T2}.Argument2"/> is the <see cref="Exception"/> encountered when receiving data from a client.        /// </remarks>        event EventHandler<EventArgs<Guid, Exception>> ReceiveClientDataException;         /// <summary>        /// Occurs when an <see cref="Exception"/> is encountered in a user-defined function via an event dispatch.        /// </summary>        /// <remarks>        /// <see cref="EventArgs{T}.Argument"/> is the <see cref="Exception"/> thrown by the user-defined function.        /// </remarks>        event EventHandler<EventArgs<Exception>> UnhandledUserException;         #endregion         #region [ Properties ]         /// <summary>        /// Gets or sets the data required by the server to initialize.        /// </summary>        string ConfigurationString        {            get;            set;        }         /// <summary>        /// Gets or sets the maximum number of clients that can connect to the server.        /// </summary>        int MaxClientConnections        {            get;            set;        }         /// <summary>        /// Gets or sets the size of the buffer used by the client for receiving data from the server.        /// </summary>        int SendBufferSize        {            get;            set;        }         /// <summary>        /// Gets or sets the size of the buffer used by the server for receiving data from the clients.        /// </summary>        int ReceiveBufferSize        {            get;            set;        }         /// <summary>        /// Gets or sets the <see cref="Encoding"/> to be used for the text sent to the connected clients.        /// </summary>        Encoding TextEncoding        {            get;            set;        }         /// <summary>        /// Gets the current <see cref="ServerState"/>.        /// </summary>        ServerState CurrentState        {            get;        }         /// <summary>        /// Gets the <see cref="TransportProtocol"/> used by the server for the transportation of data with the clients.        /// </summary>        TransportProtocol TransportProtocol        {            get;        }         /// <summary>        /// Gets the server's ID.        /// </summary>        Guid ServerID        {            get;        }         /// <summary>        /// Gets the IDs of clients connected to the server.        /// </summary>        Guid[] ClientIDs        {            get;        }         /// <summary>        /// Gets the <see cref="Time"/> for which the server has been running.        /// </summary>        Time RunTime        {            get;        }         #endregion         #region [ Methods ]         /// <summary>        /// Starts the server.        /// </summary>        void Start();         /// <summary>        /// Stops the server.        /// </summary>        void Stop();         /// <summary>        /// Disconnects all of the connected clients.        /// </summary>        void DisconnectAll();         /// <summary>        /// Disconnects a connected client.        /// </summary>        /// <param name="clientID">ID of the client to be disconnected.</param>        void DisconnectOne(Guid clientID);         /// <summary>        /// Sends data to the specified client synchronously.        /// </summary>        /// <param name="clientID">ID of the client to which the data is to be sent.</param>        /// <param name="data">The buffer that contains the binary data to be sent.</param>        /// <param name="offset">The zero-based position in the <paramref name="data"/> at which to begin sending data.</param>        /// <param name="length">The number of bytes to be sent from <paramref name="data"/> starting at the <paramref name="offset"/>.</param>        void SendTo(Guid clientID, byte[] data, int offset, int length);         /// <summary>        /// Sends data to all of the connected clients synchronously.        /// </summary>        /// <param name="data">The buffer that contains the binary data to be sent.</param>        /// <param name="offset">The zero-based position in the <paramref name="data"/> at which to begin sending data.</param>        /// <param name="length">The number of bytes to be sent from <paramref name="data"/> starting at the <paramref name="offset"/>.</param>        void Multicast(byte[] data, int offset, int length);         /// <summary>        /// Sends data to the specified client asynchronously.        /// </summary>        /// <param name="clientID">ID of the client to which the data is to be sent.</param>        /// <param name="data">The buffer that contains the binary data to be sent.</param>        /// <param name="offset">The zero-based position in the <paramref name="data"/> at which to begin sending data.</param>        /// <param name="length">The number of bytes to be sent from <paramref name="data"/> starting at the <paramref name="offset"/>.</param>        /// <returns><see cref="WaitHandle"/> for the asynchronous operation.</returns>        WaitHandle SendToAsync(Guid clientID, byte[] data, int offset, int length);         /// <summary>        /// Sends data to all of the connected clients asynchronously.        /// </summary>        /// <param name="data">The buffer that contains the binary data to be sent.</param>        /// <param name="offset">The zero-based position in the <paramref name="data"/> at which to begin sending data.</param>        /// <param name="length">The number of bytes to be sent from <paramref name="data"/> starting at the <paramref name="offset"/>.</param>        /// <returns>Array of <see cref="WaitHandle"/> for the asynchronous operation.</returns>        WaitHandle[] MulticastAsync(byte[] data, int offset, int length);         /// <summary>        /// Reads a number of bytes from the current received data buffer and writes those bytes into a byte array at the specified offset.        /// </summary>        /// <param name="clientID">ID of the client from which data buffer should be read.</param>        /// <param name="buffer">Destination buffer used to hold copied bytes.</param>        /// <param name="startIndex">0-based starting index into destination <paramref name="buffer"/> to begin writing data.</param>        /// <param name="length">The number of bytes to read from current received data buffer and write into <paramref name="buffer"/>.</param>        /// <returns>The number of bytes read.</returns>        /// <remarks>        /// This function should only be called from within the <see cref="ReceiveClientData"/> event handler. Calling this method outside this        /// event will have unexpected results.        /// </remarks>        int Read(Guid clientID, byte[] buffer, int startIndex, int length);         #endregion    }}