dxsock.pas

Well known and usefull component for delphi 7

// 
// Returns
// The result is true if successful or false if there was a
// error.
// 
// See Also
// Accept, Connect                                         
// ========================================================
function Listen (Parameters:PNewListen) :Boolean; dynamic;
      // =======================================================================
      // This routine attempts to a set a new connection from the
      // socket layer queue. This is normally managed by the
      // TDXServerCore.
      // 
      // Parameters
      // NewSock :   Will be the instance of TDXSock for the new connected
      //             client if accept returns true. If NewSock has not been
      //             instanciated coming into this routine it will be if accept
      //             \returns true. However, if NewSock was already instanciated
      //             it will not be destroryed internally if accept returns
      //             false. This provides you with complete control over the
      //             NewSock object.
      // 
      // See Also
      // Listen, Connect
      // 
      // Returns
      // true if there was a pending client connection request,
      // \otherwise false.                                                      
      // =======================================================================
function Accept (var NewSock:TDXSock) :Boolean; virtual;
      // =============================================================
      // This routine closes the connection with the current clients.
      // It is designed to wait for any pending outbound data to be
      // received by the client before actually destroying the current
      // socket handle. This is normally managed by the TDXServerCore.
      // 
      // See Also
      // CloseNow, Disconnect, Connect                                
      // =============================================================
procedure CloseGracefully; dynamic;
      // ===========================================================
      // This routine is provided to make your transition from using
      // the Borland socket implementation to DXSock much easier. It
      // functions identically to the CloseGracefully routine.
      // 
      // See Also
      // Connect, Connected, CloseGracefully, CloseNow              
      // ===========================================================
procedure Disconnect; dynamic;
      // ============================================================
      // This routine closes the connection with the current clients.
      // It is designed to destroy the current socket handle without
      // waiting for any pending outbound data to be received by the
      // client. This is normally managed by the TDXServerCore.
      // 
      // See Also
      // CloseGracefully, Disconnect, Connect                        
      // ============================================================
procedure CloseNow; dynamic;
      // =============================================================================
      // This routine is provided to make your transition from using
      // the Borland socket implementation to DXSock much easier.
      // 
      // Note
      // A common mistake is the assumption that you can pass a
      // pointer to a structure or objects that contains pointers or
      // structures to other objects that are not dereferenced
      // internally. If you are planning to transmit these types of
      // structures, you must integrate a way to encapsulate the
      // \internal pointers has inline data. It functions exactly like
      // the write() routine
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is the number of bytes
      // successfully transmitted.</COLOR>                                            
      // =============================================================================
function SendBuf (const Buf;Count:Integer) :Integer; virtual;
{$IFDEF VER100}
      function BlockWrite (buf:Pointer;len:Integer) :Integer; virtual;
      function WriteCh (c:Char) :Integer; dynamic;
      function Write (const s:string) :Integer; virtual;
{$ELSE}
      // ============================================================
      // This routine provides you with a mechanism to send a single
      // character to the socket layer.
      // 
      // Note
      // This is an example of when Nagle should be disabled, as you
      // should only be sending a single character to and from a
      // client when youre developing a protocol similar to TELNET.
      // The problem in doing this is excess network traffic - as the
      // smallest packet size is 256 bytes even for a single
      // character.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is one if successful or 0 if
      // there was a error.</COLOR>                                  
      // ============================================================
function Write (c:Char) :Integer;overload; dynamic;
      // =======================================================================
      // This routine provides you with the mechanism to send a
      // complete string of characters to the socket layer.
      // 
      // Note
      // A common mistake is the assumption that the client
      // application will simply do a read to receive the complete
      // string. For example, if you are sending two strings to the
      // client, the client may read the data as one string or as
      // multiple strings that are not separated as you originally
      // expected. This mechanism should normally be used to send an
      // already delimited string - which will optimize the
      // performance of the client application.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is the number of bytes
      // successfully transmitted.</COLOR>                                      
      // =======================================================================
function Write (const s:string) :Integer;overload; virtual;
      // ============================================================
      // This routine provides you with the mechanism to send
      // practically any form of data to the socket layer. Internally
      // all routines that send data to the socket layer will call
      // this particular method.
      // 
      // Note
      // A common mistake is the assumption that you can pass a
      // pointer to a structure or objects that contains pointers or
      // structures to other objects that are not dereferenced
      // internally. If you are planning to transmit these types of
      // structures, you must integrate a way to encapsulate the
      // \internal pointers as inline data.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is the number of bytes
      // successfully transmitted.</COLOR>                           
      // ============================================================
function Write (buf:Pointer;len:Integer) :Integer;overload; virtual;
{$ENDIF}
      // ===============================================================
      // This routine provides you with a mechanism most commonly used
      // for sending data to the socket layer. Internally it adds a
      // carriage return line feed to the string, which is used to
      // mark the data with a delimiter that can easily be parsed by
      // the client application.
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is the number of bytes
      // successfully transmitted (including the two byte CRLF).</COLOR>
      // ===============================================================
function WriteLn (const s:string) :Integer; virtual;
      // ============================================================
      // This routine provides a mechanism to simplify your
      // development for protocols that return a result code number
      // followed by a verbal string. E.g. E-mail 220 Hello I am an
      // email server. It was introduced to provide an easy way to
      // localize your server software.
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is the number of bytes
      // successfully transmitted (including the length of
      // IntToStr(Code) plus 1 for the space between the code and the
      // verbal string).</COLOR>                                     
      // ============================================================
function WriteResultCode (const Code:Integer;const Rslt:string) :Integer; dynamic;
      // =============================================================
      // This routine provides a mechanism that incorporates a length
      // header to a variable length string of data. WriteWithSize
      // allows the client application to use a similar mechanism that
      // parses the 4-byte header to retrieve the correct number of
      // bytes to read from the socket layer.
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is true if successfully, or
      // false if there was an error</COLOR>                          
      // =============================================================
function WriteWithSize (S:string) :Boolean; dynamic;
      // =============================================================
      // This routine provides you with a mechanism for transmitting
      // 32-bit numbers as a 4-byte piece of data. Internally it swaps
      // the high and low order of the bytes - to be compatible with
      // \older operating systems.
      // 
      // Note
      // This is an example of when Nagle should be disabled, as you
      // should only be sending a small number of characters to and
      // from a client when youre developing a protocol similar to
      // TELNET. The problem in doing this is excess network traffic -
      // as the smallest packet size is 256 bytes. Internally this is
      // used by the routines which present this number as a form of
      // length header - in DXSock and DXInternet: WriteWithSize and
      // SendFromStreamWithSize, ReadWithSize and
      // SaveToStreamWithSize.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is four if successful, or 0
      // if there was a error.</COLOR>                                
      // =============================================================
function WriteInteger (const n:integer) :integer; dynamic;
{$IFDEF VER100}
      function SendFromStreamRange (Stream:TStream;Range:Integer) :Boolean; dynamic;
      function SendFromStream (Stream:TStream) :Boolean; dynamic;
      function SendFromWindowsFile (var Handle:Integer) :boolean; dynamic;
      function SendFromBorlandFile (var Handle:file) :boolean; dynamic;
{$ELSE}
      function SendFrom (Stream:TStream;Range:Integer) :Boolean; overload; virtual;
      // ============================================================
      // This routine provides a mechanism to simplify transmitting a
      // stream of data to the socket layer.
      // 
      // Note
      // It starts sending from the current positions in the stream
      // and continues until it has sent the remainder of the stream.
      // A common mistake would be to use this method without some
      // form of delimiter, as the client application would have know
      // means of knowing when it has received the complete stream.
      // This can be overcome by prefixing some form of header before
      // the stream is sent, or suffixing the stream with a unique
      // terminator. E-mail for example sends the message body as a
      // stream but terminates it with "carriage return line feed"
      // period "carriage return line feed".
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is true if successfully, or
      // false if there was an error.</COLOR>                        
      // ============================================================
function SendFrom (Stream:TStream) :Boolean;overload; virtual;
      // =============================================================
      // This routine provides a mechanism to transmit a file opened
      // using the operating systems fileopen() command via the socket
      // layer.
      // 
      // Note
      // It starts sending from the current positions in the file and
      // continues until it has sent the remainder of the file. A
      // common mistake would be to use this method without some form
      // \of delimiter, as the client application would have know
      // means of knowing when it has received the complete file. This
      // can be overcome by prefixing some form of header before the
      // file is sent, or suffixing the file with a unique terminator.
      // 
      // 
      // 
      // Returns
      // <COLOR BORLAND GREEN>The result is true if successfully, or
      // false if there was an error.</COLOR>                         
      // =============================================================
function SendFrom (var Handle:Integer) :boolean;overload; dynamic;
      
// =======================================================================
// This routine provides a mechanism to transmit a file that is
// using the PASCAL file handle via the socket layer.
// 
// Note
// It starts sending from the current positions in the file and
// continues until it has sent the remainder of the file. A
// common mistake would be to use this method without some form
// \of delimiter, as the client application would have know