July 17, 1995

DWINSOCK V1.3
-------------

A Windows Socket interface component for use with Borland Delphi.

By  Ulf Sderberg,  ulfs@sysinno.se
    Marc Palmer,    marc@landscap.demon.co.uk
    Keith Hawes,    khawes@ccmail.com

This is a short description of the DWinSock component for Borland Delphi
that is contained in the file DWSOCK13.ZIP.

We would like to create a Delphi installable help file sometime soon.
(Perhaps some one at ForeHelp will send us a copy)
For now, you have to rely on this description and on the contents of the
source files.

FILE CONTENTS
-------------
Files that originally came from PASOCK10.ZIP that has been changed by me:
WINSOCK.INC Part of the old WINSOCK.PAS (included in DWINSOCK.PAS)
WINSOCK.IF  Part of the old WINSOCK.PAS (included in DWINSOCK.PAS)
WINSOCK.IMP Part of the old WINSOCK.PAS (included in DWINSOCK.PAS)
ERROR.INC   Part of the old WINSOCK.PAS (included in DWINSOCK.PAS)

Original work by myself:
DWINSOCK.DCR Contains two component palette bitmaps.
DWINSOCK.PAS The source code of the component.
DWINSOCK.DCU The compiled unit.

THE COMPONENTS IN DWINSOCK
--------------------------
DWinSock contains two components which are named TClientSocket and
TServerSocket. As the names implies, they are to be used in client or
server applications.

TClientSocket Properties
  --------       Design Time
  Address        address of remote host, a string like '127.0.0.1'
  Host           name of remote host, a string
  Options        defines the actions the socket will respond to
    csoRead      Respond to Reading
    csoWrite     Respond to Writing
    csoOOB       Respond to Out Of Band data
  Name           Standard TComponent property
  Port           port number, an integer
  Service        name of port, a string
  Tag            Standard TComponent property
  TimeOut        Time out value in seconds (0 for no time out)
  --------       Run Time & read only
  Conn           current TSocket
  Handle         current window handle, used to receive messages from WinSock
  Description    name of underlying WinSock

TClientSocket Events
  OnConnect      Connection is successful
  OnDisconnect   Host disconnected
  OnInfo         Progress notification
  OnRead         Incoming Data
  OnWrite        Write completed

TClientSocket Methods
  Close          Disconnect form the host
  Connected      True when the socket is connected to the host
  Info           Notify of Progress (Causes an OnInfo event)
  LocalHost      Name of yourself
  LookupName     Gets the address of a host in WinSock format
  LookupNameStr  Gets the address of a host in a string like '127.0.0.1'
  LookupService  Get the Port number of a service
  Open           Attempt to connect to the Host
  Reverse        Reverse lookup an address (returns the host name)

TServerSocket Properties
  --------       Design Time
  Address        Address of the clients to connect with, '0.0.0.0' for all
  ClientOptions  Defines the actions the socket will respond to
    csoRead      Respond to Reading
    csoWrite     Respond to Writing
    csoOOB       Respond to Out Of Band data
  MaxConnections Maximum allowable number of connections
  Name           Standard TComponent property
  Port           Port number, an integer
  Service        Name of port, a string
  Tag            Standard TComponent property
  --------       Run Time & read only
  Conn           The Server's TSocket
  Conns          TList of client sockets
  Handle         Current window handle, used to receive messages from WinSock
  Description    Name of underlying WinSock

TServerSocket Events
  OnAccept       Incoming connection accepted
  OnDisconnect   Connection disconnected
  OnInfo         Progress notification
  OnRead         Incoming Data
  OnWrite        Write completed

TServerSocket Methods
  Client         Returns the TSocket of a client in the Conns list
  ClientCount    The number of Clients in the Conns list
  Close          Disconnect form the host
  CloseDown      Close all Connections and server
  Info           Notify of Progress (Causes an OnInfo event)
  Listen         Listen for incoming connections
  LocalHost      Name of yourself
  LookupName     Gets the address of a host in WinSock format
  LookupNameStr  Gets the address of a host in a string like '127.0.0.1'
  LookupService  Get the Port number of a service
  Reverse        Reverse lookup an address (returns the host name)


OTHER OBJECTS
-------------
Both TClientSocket and TServerSocket are derived from the class TSoskCtrl.
TSockCtrl uses an object called TSocket which contains the connection status
like IP address and port number. TSocket has several methods that you may call
via the Conn property, they are:

  --------       Information
  BytesSent      The number of bytes send from the last Send or Text := string
  InCount        Return amount of data that can be currently read from the port
  LocalAddress   Return your address
  LocalPort      Return your port number for a connection.
  RemoteHost     Return the remote host name.
  RemoteAddress  Return the remote IP address.
  RemotePort     Return the remote port number.
  --------       I/O
  Recv           Receive a buffer
  Send           Send a buffer
  Text           Property: Send and receive text from the port:
                 Send: Text := 'Send this';
                 Recv: Receved_This := Text;

EXCEPTIONS
----------
If anything goes wrong inside you will get an exception of type ESockError with
a message indicating what kind of error that cause the exception.

SUMMARY
-------
This was a very brief description of DWINSOCK. As you can see from the source
files it does not at all use all functions of Windows Sockets but it provides
a quick solution to get into WinSock programming with Delphi. And covers enough
of the basics to handle most applications.

A sample application called NETTIME that is a time client has been included as
an example of using dWinSock It gets the current time of day from a time 
server.

You may use DWINSOCK any way you like but don't blame us.

Suggestions may be emailed to any of the folks listed at the beginning of this
document.

------------------------------------------------------------------------------
Revision History
Helpful hints on converting from one version to the next indicated by **
------------------------------------------------------------------------------
  V1.3  950717 The Socket Version.
        . Added bitmaps to components, added CloseDown procedure to server,
        . Stopped Server from accepting  >MAXCONN connections.
        . Replaced TClientEvent and TServerEvent with TSocketEvent which passes
          a TSocket reference instead of connection id.
          ** A Change in the parameters replace "cid : integer" with
             "Socket : TSocket".  Delphi will complain of loading of the form
             until you make this change to all of your On* handlers except
             onInfo
          ** This is a big change from the previous versions. Before you needed 
              code like "ServerSocket.Client[cid].method" now you can just use 
             "Socket.Method". 
        . Also changed TClientSocket.Open and TServerSocket.Listen to take 
          one more argument which is of type TSocketClass. The creation of 
          FConn for TClientSocket and FConns array for TServerSocket is now 
          done in the Open and Listen procedures when you know what kind of 
          socket you want.
          ** Add TSocket to the parameter list in your calls
        . Moved the common properties (On from Client & Server into TSockCtrl.
        . Numerous changes to make Info notifications work better and added a
          few new ones.
        . Introduced time out handling. Set the TimeOut property of the socket
          classes at design time to set how many seconds it will take before a
          time out is declared. The OnTimeOut event is called when this 
          happens. 
          ** In the handler you should call Close. Not sure about Server 
             handling yet.
        . Replaced TServerSocket.FConns array with a TSocketList
          (derived from TList). Incoming connections are no longer limited by
          MAXCONN. There is a MaxConnections property for limiting incoming
          connections.
        . Added TClientSocket.Options and TServerSocket.ClientOptions
          properties. These determine the mask used for the WSAAsyncSelect
          calls to the corresponding sockets.
        . TSockCtrl now inherits from TComponent. (Yea!, less overhead)
        . TSockets are deleted from server.FConns on close.
        . Correct nl not being set bugs in several methods.
        . Moved LookupName and LookupService from TSocket to TSockCtrl
          ** Remove reference to Conn "ASocket.Conn.LookupName" becomes
             "ASocke.LookupName".
        . Added LookupNameStr to return the address as a string.
        . Moved RecvText and SendText to TSocket's Private section.
          ** Use the Text property.

  V1.2  950410  Added Address property to server.
  V1.1  950407  Corrected TServerSocket bug.
  V1.0  950404  First release.


