Sock.pas
TSock Component Class
Version 1.0 ßeta 2
Written By Tom Bradford
© Copyright 1996 By Beach Dog Software
® All Rights Reserved

Contents

Introduction
ßeta Release Notes
Features
Properties
Events
Methods
Support Routines
Examples


Introduction

As this is a ßeta release of the component, it should be noted that not every aspect of normal operation has been thoroughly tested. Asynchronous client I/O should work perfectly. Blocking communications should work fairly well. Server functionality has been thoroughly tested. Users may want to fool around with Datagram socket functionality because it hasn't been fully tested yet.


Table Of Contents


ßeta Release Notes


Table Of Contents


Features


Table Of Contents


Properties

Property Name Type Scope Description
SocketType TSocketType Design Type of socket. This value can either be stStream or stDatagram. If Listen is set to TRUE, this property will automatically be set to stStream because datagram sockets do not support listening mode. Likewise, if the socket type is set to stDatagram, the Listen property will be set to False (in design mode).
HostName String Design Host Name or IP Address. The Socket Component will automatically distinguish a Host Name (ex: www.cinteractive.com) from an IP Address (ex: 127.0.0.1).
PortName String Design Port Number or Service Name. Port Numbers are well known ports such as 80 for HTTP or 7 for Echo. Service Names perform a database lookup into the SERVICES file.
Blocking Boolean Design Blocking Socket I/O. TRUE causes a socket to block while connecting, waiting for incoming data and writing to the socket. FALSE causes an asynchronous window message to be sent when a connection is made, data is available to be read and written.
AutoAccept Boolean Design Auto-Accept Incoming Connections. TRUE causes a Listening socket (Listen = TRUE) to automatically accept an incoming connection and call OnAutoAccept as a new thread. If no OnAutoAccept is defined, OnAccept is called. If No OnAccept is defined, the incoming connection will linger.
Listen Boolean Design Listen For Incoming Connections. If TRUE, creates a thread that loops, listening for incoming sockets and handling them based on the AutoAccept, OnAccept, and OnAutoAccept properties.
Connected Boolean RunTime Connect Socket Or Check Connection. If set to TRUE, the component attempts to open a socket connection. If set to FALSE, the component closes a current connection. If the value returned is TRUE, the socket is connected, otherwise, it is not.
Socket TSocket RunTime Returns Socket Value. Returns the value of a connected socket. Returns INVALID_SOCKET (-1) if the socket isn't currently connected. This property also allows the user to set the value of the socket, but this is inadvisable.
Text String RunTime Sends And Receives Text. If being assigned to, the value being assigned will be sent to the socket. If being read from, any incoming data from the socket will be returned.
LineBreak TLineBreak Design Sets the method of scanning incoming data for possible line breaks. This property is used in cooperation with the ReceiveLine method for reading an incoming data stream 1 text line at a time. The possible values for this property are lbCR, lbLF, lbCRLF and lbSmart. lbSmart will make guesses as to the form of the incoming data stream based upon content and break the lines accordingly.


Table Of Contents


Events

Event Name Event Description
OnConnect
(TObject)
Occurs when a client socket connects to a remote host.
OnDisconnect
(TObject)
Occurs when a client socket disconnects from a remote host or when the connection is unexpectedly terminated.
OnInfo
(TObject, TSocketInfo, String)
Occurs when the component produces a state message. This event sends a TSocketInfo parameter as well as a string with information specific to the task that is being reported on.
OnRead
(TObject, Integer)
Occurs when data is available to be read from the socket.
OnWrite
(TObject)
Occurs when the socket will allow data to be written.
OnAccept
(TObject)
Occurs when a socket is in queue to be accepted. This event can be used in cooperation with the Accept method to perform multi-client server operations.
OnAutoAccept
(TObject, TSock)
Occurs when AutoAccept is TRUE. Creates a new client socket and invokes OnAutoAccept as a thread separate from the main application. It is the implementer's responsibility to Free the TSock component that is passed.


Table Of Contents


Methods

Method Name Method Description
Open : Boolean Opens a connection to the remote HostName using PortName. Returns TRUE if successful. Returns FALSE if the connection could not be established.
Close : Boolean Closes any existing remote connection.
Send(String) : Boolean Sends a string to the remote connection. Returns TRUE if successful.
Receive : String Returns any incoming data from the socket. Will block while waiting for data if Blocking is set to TRUE and no data is available in the queue.
SendDatagram(String, String) : Boolean Sends the text in the first String parameter as a Datagram to the HostName address defined in the second String parameter. Because UDP is by-definition unreliable, this method always returns TRUE.
ReceiveDatagram(Var String) : String Returns a string with the Datagram content received from any address through the bound UDP PortName. ReceiveDatagram will set the String parameter to the IP address of the Datagram's originator.
ReceiveLine : String Returns the next input line from the input stream for a socket with SocketType set to stStream. This method uses the LineBreak property to determine how to scan the input stream. If the SocketType is set to stDatagram, this method returns the next incoming Datagram in its entirety. Because the entire Input Stream isn't returned by this method, the socket may have already determined that the connection has been closed. In this case, it is the user's responsibility to check for incoming data even if the socket is no longer connected.
Accept(TSock) : Boolean Accepts the next available incoming socket from the listening loop. Accept return TRUE if successful. This method also assigned the TSock parameter to a valid TSock connection component. It is the implementer's responsibility to Free this component when it is no longer needed. Also, the new component is created with no Event handlers, so the implementer is responsible for assigning them if the socket is non-blocking. This event will only be triggered if Listen is TRUE.
HostLookup(String) : TInAddr Looks up a remote host using the String parameter. The parameter can either be an IP address (ex: 111.111.111.111) or a domain name (ex: www.cinteractive.com). The value that is returned is a TInAddr structure that can be used when building a TSockAddrIn for binding a socket to an address.
PortLookup(String) : Word Looks up a service port using the String parameter. The parameter can either be a textual service name (ex: echo or Finger) or a port number (ex: 80). The value that is returned is a unsigned short in network byte order.
StartListen : Boolean Sets the socket component into listening mode. The result is TRUE if successful and FALSE otherwise. This method is the same as setting Listen=TRUE and then checking the value of Listen.
StopListen : Boolean Turns listening mode off.


Table Of Contents


Support Routines

Routine Name Routine Description
WSDescription : String Returns a vendor-defined string that describes the presently running WinSock implementation. This information is obtained while performing an initial WSAStartup WinSock call.
WSASystemStatus : String Returns a vendor-defined string containing system status.
SocketInfoText(TSocketInfo) : String Given the TSocketInfo parameter, returns a string that describes the parameter. This function can be used in conjunction with an OnInfo event.
ErrToStr(Integer) : String Given the Integer parameter, returns the WinSock defined string associated with a particular error code. TSock uses this support routine internally for translating asynchronous errors to TSockException exceptions.
Base64Encode(String) : String Converts the String parameter to a MIME-standard Base-64 encoded block and returns the conversion as the String result.
Base64Decode(String) : String Converts the String parameter from a MIME-standard Base-64 encoded block and returns the conversion as the String result.
URLEncode(String) : String Converts the String parameter to a URLEncoding scheme and returns the conversion as the String result.
URLDecode(String) : String Converts the String parameter from a URLEncoding scheme and returns the conversion as the String result.


Table Of Contents


Examples

There are a few sample applications and more on the way:


Table Of Contents