dxsock.pas

Well known and usefull component for delphi 7

      // specified timeout. A common mistake is the assumption that
      // the timeout counter resets when any data is received. Instead
      // \of the timeout parameter is the maximum time this routine
      // should execute.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is true if any data was
      // received. Test the LastReadTimeout and LastCommandStatus
      // properties discussed in the next section of this chapter.</COLOR>
      //                                                                  
      // =================================================================
function SaveTo (var Handle:Integer;Timeout:Longword) :boolean;overload; dynamic;
      // =================================================================
      // This routine provides a mechanism to simplify receiving data
      // from the socket layer and storing it in the specified PASCAL
      // file handle.
      // 
      // Note
      // It starts appending at the current position in the file and
      // continues until no more data can be received within a
      // specified timeout. A common mistake is the assumption that
      // the timeout counter resets when any data is received. Instead
      // \of the timeout parameter is the maximum time this routine
      // should execute.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is true if any data was
      // received. Test the LastReadTimeout and LastCommandStatus
      // properties discussed in the next section of this chapter.</COLOR>
      // =================================================================
function SaveTo (var Handle:file;Timeout:Longword) :boolean;overload; dynamic;
{$ENDIF}
      // ================================================================================
      // This procedure provides you with a mechanism to retrieve a
      // stream of data that has been prefixed with a 4-byte header.
      // 
      // Note
      // It starts appending at the current position in the stream and
      // continues until the specified time out occurs or there was an
      // error.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is true if all of the data
      // was received. Test the LastReadTimeout and LastCommandStatus
      // properties discussed in the next section of this chapter.</COLOR>               
      // ================================================================================
function SaveToStreamWithSize (Stream:TStream;Timeout:Longword) :Boolean; dynamic;
      // =============================================================
      // This routine works much like the read routine that returns a
      // character except it was designed to return a blank if there
      // was no data or an error instead of #0.
      // 
      // Note
      // Anytime you interact with a socket buffer
      // character-by-character, you will see a severe performance
      // drop. Doing so causes the socket layer to lock its internal
      // buffer to retrieve a single character then release the lock,
      // which means no packet can be handled during these couple of
      // milliseconds, thus producing the severe performance drop.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is character was received, or
      // "" if an error occurred. Test the LastReadTimeout and
      // LastCommandStatus properties discussed in the next section of
      // this chapter.</COLOR>
      //                                                              
      // =============================================================
function GetChar:Str1; virtual;
      // =============================================================
      // This routine works much like the read routine that returns a
      // character except it returns the ordinal of the character.
      // 
      // 
      // 
      // Note
      // Anytime you interact with a socket buffer character-by-
      // character, you will see a severe performance drop. Doing so
      // causes the socket layer to lock its internal buffer to
      // retrieve a single character then release the lock, which
      // means no packet can be handled during these couple of
      // milliseconds, thus producing a severe performance drop.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is ordinal of the character
      // that was received or zero if an error occurred. Test the
      // LastReadTimeout and LastCommandStatus properties discussed in
      // the next section of this chapter, as zero is an acceptable
      // character value some times.</COLOR>                          
      // =============================================================
function GetByte:Byte; virtual;
      // =============================================================
      // This routine provides a mechanism for on-the-fly compression
      // \or basic encryption. Provided for manual call after your
      // read calls, due to the fact some of the read routines in the
      // suite accept pointers as parameters - thus it would create a
      // memory leak. FilterRead allows you to modify the inbound data
      // and return it as outbound data. Then should be called after
      // decoding the read data so you can destroy the temporary
      // pointer used for the outbound data.                          
      // =============================================================
function FilterRead (const InBuf:Pointer;var OutBuf:Pointer;InSize:Integer;xClientThread:TThread) :Integer;
      // =============================================================
      // This routine provides a mechanism that allows you to see the
      // contents of the next packet in the socket layer that is
      // available to be read.<B>
      // 
      // </B>
      // 
      // Note
      // Due to way Microsoft has implemented the socket layer you
      // should avoid peeking. A common mistake is the assumption that
      // a peek string will return all pending data in the socket
      // layer buffer. It will only return up to 250 characters from
      // the packet.                                                  
      // =============================================================
function PeekString:string;
      // =============================================================
      // This routine provides a mechanism that allows you to see the
      // next unread character of the next packet in the socket layer.
      // <B>
      // 
      // </B>
      // 
      // Note
      // Due to way Microsoft has implemented the socket layer you
      // should avoid peeking.                                        
      // =============================================================
function PeekChar:Char;
      // ============================================================
      // This routine provides you with a mechanism to access the
      // socket layer for a verbal description of the command status.
      // Since TDXSock encapsulates the procedural design of the
      // socket layer, it is better to use the GetErrorDesc method
      // with LastCommandStatus.
      // 
      // See Also
      // GetErrorDesc, LastCommandStatus                             
      // ============================================================
function GetErrorStr:string;
      // =============================================================
      // This routine provides you with the mechanism to access the
      // verbal description of the specified error code. The
      // verbalized string contains the localized text associated with
      // the specified error code. Localization is controlled by a
      // compiler definition in the DXSOCK.DEF file.
      // 
      // See Also
      // GetErrorStr, LastCommandStatus                               
      // =============================================================
function GetErrorDesc (errorCode:Integer) :string;
      // ========================================================
      // This routine provides a mechanism for toggling the Nagel
      // algorithm on or off for the socket layer.<B>
      // 
      // </B>
      // 
      // Note
      // By default it is enabled in the DXSock suite.           
      // ========================================================
procedure SetNagle (TurnOn:Boolean) ;
      // ===========================================================
      // This routine provides a mechanism for toggling blocking for
      // non-blocking socket calls.<B>
      // 
      // </B>
      // 
      // Note
      // By default it is enabled in the DXSock suite.              
      // ===========================================================
procedure SetBlocking (TurnOn:Boolean) ;
procedure WinsockVersion (var WinsockInfo:PWinsockInfo) ;
    // ==================================
    // Made public for new TDXSockClient:
    // ==================================
      procedure SockClientSetGlobal (I:string;P:Integer) ;
      procedure SetTimeoutAndBuffer (SocketHandle:Integer) ;
// =============================================================
// DroppedConnection checks to see if the socket handle is still
// valid, do we have a pending SYN_DISCONNECT packet.
// 
// See Also
// Connected
// 
// Returns
// true if the current client session has been terminated,
// \otherwise false.                                            
// =============================================================
      function DroppedConnection:Boolean; virtual;
      // ============================================================
      // This method provides you with a mechanism to sleep for
      // 'timeout' milliseconds for any data to be available. This is
      // not the most optimal way to design your primary
      // communications loop. However, it is provided to help those
      // who are not after high-performance but more after easy code
      // to read.                                                    
      // ============================================================
function WaitForData (timeout:Longint) :Boolean; virtual;
// ============================================================
// Use this method to set the internal "CPS" (Characters Per
// Second) timers to zero. All internal communications for each
// instance of TDXSock track the number of bytes sent and
// received. This allows for your application to implement
// bandwidth throttles.                                        
// ============================================================
      procedure RestartCharactersPerSecondTimer;
      // ============================================================
      // To provide your application with the information required to
      // produce a bandwidth throttle, this method returns the number
      // \of characters being sent per second at the TDXSock layer.
      // 
      // Returns
      // The number of bytes start to accumulate since the connection
      // was established or the last time
      // RestartCharactersPerSecondTimer was called.                 
      // ============================================================
function CharactersPerSecondWritten:Integer;
      // ============================================================
      // To provide your application with the information required to
      // produce a bandwidth throttle, this method returns the number
      // \of characters being received per second at the TDXSock
      // layer.
      // 
      // Returns
      // The number of bytes start to accumulate since the connection
      // was established or the last time
      // RestartCharactersPerSecondTimer was called.                 
      // ============================================================
function CharactersPerSecondReceived:Integer;
   published
      property TLSActive:Boolean read FTLS write FTLS;
      property TLSClientThread:TThread read FClientThread write FClientThread;
      // =============================================================
      // This property provides a mechanism that allows you to specify
      // a specific IP for this instance of TDXSock to accept
      // connections on.<B>
      // 
      // </B>
      // 
      // 
      // 
      // Note
      // The default is blank, which allows the server to listen to
      // all IP addresses found to the current NIC.                   
      // =============================================================
property BindTo:string read fsBindTo
         write fsBindTo;
      // =======================================================================================
      // This property provides you with a mechanism that tests if the
      // socket handle is still valid, if there was an error, if it
      // was a non-critical error, and if it was a critical error, it
      // will still returned true if data still exists in the socket
      // layer buffer.
      // 
      // 
      // <CODE>
      // While connected do begin
      //    if <LINK TDXSock.Readable, readable> then begin
      //       if <LINK TDXSock.CharactersToRead, CharactersToRead>=0 then Exit; // disconnected
      //       {.. do your read here ..}
      //    end