TBPDXSock

Free Pascal Events

   TBPDXSockOnCommand = procedure(Sender:Pointer) of object;
   TBPDXSockOnSuccess = function(Sender:Pointer):Boolean of Object;
   TBPDXStatusCodeRecord = Record;

Delphi Events

   TBPDXSockOnCommand = TNotifyEvent;
   TBPDXSockOnSuccess = function(Sender:TObject):Boolean of Object;
   TBPDXStatusCodeRecord = Record;

Free Pascal Object

   TBPDXSock = Object(TBPDXComponent)

Delphi Object

   TBPDXSock = Class(TBPDXComponent)

Compile-time Constants

TBPDXHugeSize = 262142;

This is the largest size that is common across all operating systems for the socket layer read and write buffer size. Earlier versions of our product used to set this to 65535. This constant is used by the OutputBufferSize property, when set to bsfHuge.

TBPDXXferTimeout = 5000;

Is used as a global setting at the socket layer itself -- for how many milliseconds a command can take before it should timeout and return WSAEWOULDBLOCK.

TBPDXMaxSocketBuffer = Cardinal(TBPDXHugeSize);

Is used as a global setting as the socket layer itself -- for how many bytes to allocate as the in buffer and out buffer in the socket layer.

PeekBufferSize = Word(4096);

ConstClientConnectTimeout = 250000

Is used to set the default value for TBPDXNewConnect.ConnectTimeoutUSEC value. 250000 is 1/4 second, so 32 means 8 seconds is the longest you want the socket layer to wait on establishing a connection before returning WSAETIMEOUT. NOTE Some versions of Windows this can only be controlled by setting a registry value and rebooting.

Public

TagComp : Comp;

TagComp allows your to track DXUtil_Environment.TimeCounter() values per instance. Originally implemented for a Winshock project, and found to be useful for projects which we wanted to track the life of the socket object.

SockAddr : TSockAddrIn;

Provided for advanced programmers. This public variable contains low-level socket information after a successful connection or after starting the listener.

SocketHandle : TSocketHandle;

This is an advanced feature for the rare occasion you need access to the socket handle itself. It is useful if you are using the DXAddon Suite DXUnicastDataQueue component for background broadcasting that is handled in an external thread.

fpSessionData : Pointer;

fpSessionData is a pointer so it can track ANY type of information for unique to this instance. We use it in cache buffers for things like DXSOCK 6.0 SysLog Sever.

Constructor

Destructor

TBPDXSock Methods

      function Connect(Parameters: TBPDXNewConnect): Boolean;

This routine provides a way to create a connection to a server (listener). If the connection is successful this function returns true, otherwise, if false you can look at TBPDXSocket.LastCommandStatus and TBPDXSock.GetErrorDesc() or TBPDXSock.GetErrStr.

To implement this call you must create a TBPDXNewConnect object, and set the ipAddress, Port and Network protocol.

NOTE A common mistake is to use this call from within an already active client instances. Meaning you must create a new instance of TBPDXSock before you can establish a connection to another server.

See also: TBPDXNewConnect

      function ConnectTo(Const Host:ShortString;Const Port:Word): Boolean;

This routine provides a way to create a connection to a server (listener). If the connection is successful this function returns true, otherwise, if false you can look at TBPDXSocket.LastCommandStatus and TBPDXSock.GetErrorDesc() or TBPDXSock.GetErrStr. This routine assumes TCP, Nagle Enabled and Blocking Sockets. If you need more control, use TBPDXSock.Connect.

NOTE A common mistake is to use this call from within an already active client instances. Meaning you must create a new instance of TBPDXSock before you can establish a connection to another server.

See also: TBPDXNewConnect

      function Listen(Parameters: TBPDXNewListen): Boolean;

This routine provides a way to create a server (listener), normally managed by TBPDX

Server unit. If the command is successful this function returns true, otherwise, if false you can look at TBPDXSocket.LastCommandStatus and TBPDXSock.GetErrorDesc() or TBPDXSock.GetErrStr.

To implement this call you must create a TBPDXNewListen object, and set the ipAddress, Port and Network protocol.

See also: TBPDXNewConnect, TBPDXGenericServer

      function Accept($IFDEF FPC
Var$ENDIF NewSock: TBPDXSock): Boolean;

This routine provides your server (listener) the way to acknowledge and interact with a new connection request from a client. If the connection is waiting for your server to handle the result code will be true and the NewSock will be an instance of TBPDXSock with the socket handle of the connection.

NOTE In Delphi only, if NewSock is Nil this routine will create a new instance of TBPDXSock if there was a new connection pending. Free Pascal does not support doing this.

See also: TBPDXNewConnect, TBPDXGenericServer

      procedure CloseGracefully;

This routine provides a way to end a connection, for either a client connection or an accepted client session. The difference between this routine and CloseNow, is a Graceful disconnect tells the client socket to wait until all data has been received before acknowledging the close request.

      procedure Disconnect;

This routine calls CloseGracefully. It was implemented for those who like to connect and disconnect, not close.

      procedure CloseNow;

This routine provides a way to end a connection, for either a client connection or an accepted client session. The difference between this routine and CloseGracefully, is this disconnect tells the client socket to ignore pending data and acknowledge the close request.

NOTE This has the potential to lose data over slower networks, or networks with multiple routers. As the packet to request a close has a higher priority than a packet with data. So, the close could reach the other end before all of the data that is being sent to them.

      function SendBuf(const Buf;Const Count: Integer): Integer;

This routine is implemented to make migrating from Borland sockets to ours easier. You should get familiar with our Write routines instead.

      function Write(Const c: Char): Integer; overload;

This routine provides you with the ability to send a single character to the socket layer.

NOTE Common mistakes are to send a long piece of data at a single character at a time. Or trying to send a single character and having a noticeable delay because you did not disable Nagle.

      function Write(const s: AnsiString): Integer; overload;

This routine provides you with the ability to send a complete string of characters to the socket layer.

NOTE A common mistake for chat or short message applications is sending a string and having a noticeable delay because you did not disable Nagle.

      function Write(buf: Pointer;Const len: Integer): Integer; overload;

This routine provides you with the ability to send any size or type of data to the socket layer.

NOTE A common mistake for sending smaller bursts of data is a noticeable delay because you did not disable Nagle. Another mistake is to assume the client will read the data in the same fashion you wrote it. Meaning, if you sent 1024 bytes in a single write, you might assume you could do a single read and get 1024 bytes. This is not true due to different networking algorithms. This is why people implement different data formats and delimiters.

      function WriteLn(const s: AnsiString): Integer;

      function WriteResultByCode(const Code: Integer;
         const Rslt: Array of TBPDXStatusCodeRecord): Integer;

This routine provides many of our protocol implementations with an easy way to return a result code from an memory collection (Array) of our TBPDXStatusCodeRecord, by simply calling this routine with a status code number and passing the built-in Status Code collection.

      function WriteResultCode(const Code: Integer;
         const Rslt: AnsiString): Integer;

This routine provides many of our protocol implementations with a way to return a abnormal result code and Status Code message. There are times in certain protocols where the default message is not accurate for your current situation. Or the message needs values to be applied, like fsFileName+' not found.'.

      function WriteWithSize(Const S:AnsiString): Boolean;

This routine sends a 4 Byte header (Integer 32bit) in reverse Endian (to be compatible with Unix(s)). This is one way of formatting your data, making sure then other end has implemented a similar ReadWithSize() routine.

      function WriteInteger(const n: integer): integer;

This routine sends a 4 Byte Integer (32bit) in reverse Endian (to be compatible with Unix(s)).

      function WriteIntegerNoEndian(const n: integer): integer;

This routine sends a 4 Byte Integer (32bit) in without reversing the Endian.

      function ReceiveBuf(var Buf;Const Count: Integer): Integer;

This routine is provided to make your transition from using the Borland socket implementation to DXSock much easier. It functions exactly like the DXSock read() routine (which you should migrate to using).

      function Read(buf: Pointer;Const len: Integer): Integer; overload;

This routine is our low-level read from the socket call. It is pointer based, handles slow reads, encrypted sessions, etc. The return value contains the actual number of bytes read into the buf:pointer.

See also LastReadTimeout, LastCommandStatus and Connected.

      function read: char; overload;

This routine is used internally, however, exposed to you incase you need to read a single character from the socket layer.

      function ReadInteger: integer;

This routine read a single 32bit Integer from the socket buffer, doing a reverse Endian from Unix(es) to Windows.

      function ReadIntegerNoEndian: integer;

This routine read a single 32bit Integer from the socket buffer, does not reverse Endian.

      function ReadStr(Const MaxLength: Integer): AnsiString;

This routine provides you with a mechanism to interact with the socket layer as a string instead of using a pointer. It is a wrapper around the standard read routine, thus it also works without a timeout parameter.

      function ReadString(Const MaxLength: Integer;
         Const Timeout: Longword): AnsiString;

This routine provides you with the mechanism to interact with the socket layer as a string. The primary differences between this routine and ReadStr are MaxLength should be the sizes of the expected packet content (250 bytes is the maximum), and it does not try to receive anything from the socket until the first packet in the socket buffer is equal to or longer than the specified MaxLength. This routine does implement the timeout parameter. This routine was implemented per a customer request, and normally should not be used unless you really understand how this routine works.

      function ReadLn(Const Timeout: Longword): AnsiString;

This routine provides you with a mechanism to retrieve data from the socket layer where the line delimiter is either a carriage return, or a line feed, or a combination of carriage return and line feed, or line feed and carriage return. Thus supporting the standard carriage return and line feed delimiter, plus combinations normally associated with UNIX-based clients or Macintosh based clients. This routine does implement the timeout parameter and contains logic to avoid hacker-overrun attacks.

      function ReadCRLF(Const Timeout: Longword): AnsiString;

This routine provides you with a mechanism to retrieve data from the socket layer where the line delimiter is carriage return and line feed. There are occasions where this routine is more useful than trying to use the Readln routine, normally when you know the client will only send the carriage return followed by a line feed. This routine does implement the timeout parameter and incorporates logic to avoid hacker-overrun attacks.

      function ReadToAnyDelimiter(Const Timeout: Longword;
         Const Delimiter: ShortString): AnsiString;

This routine provides you with a mechanism to retrieve data from the socket layer and specify what the line delimiter is.

Note The line delimiter can be any combination of characters. A common mistake is to specify a delimiter that may also be found within the normal data. This routine does implement the timeout parameter and incorporates logic to avoid hacker-overrun attacks.

      function ReadNull(Const Timeout: Longword): AnsiString;

This routine provides you with a mechanism to retrieve data from the socket layer where the delimiter is a Null. This routine does implement the timeout parameter and incorporates logic to avoid hacker-overrun attacks.

      function ReadSpace(Const Timeout: Longword): AnsiString;

This routine provides you with a mechanism to retrieve data from the socket layer where the delimiter is a Space (#32). This routine does implement the timeout parameter and incorporates logic to avoid hacker-overrun attacks.

      function ReadWithSize: AnsiString;

This procedure provides you with a mechanism to retrieve a string of data that has been prefixed with a 4-byte header. It was introduced per a customer request.

      function getchar: str1;

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.

      function getbyte: byte;

This routine works much like the read routine that returns a character except it was designed to return a zero if there was no data or an error.

Note Anytime you interact with a socket buffer byte-by-byte, you will see a severe performance drop. Doing so causes the socket layer to lock its internal buffer to retrieve a single byte then release the lock, which means no packet can be handled during these couple of milliseconds, thus producing the severe performance drop.

      function PeekString: AnsiString;

This routine provides a mechanism that allows you to see the next unread packet of up to 250 characters in the socket layer.

      function PeekChar: Char;

This routine provides a mechanism that allows you to see the next unread character of the next packet in the socket layer.

      function GetErrorStr: ShortString;

This routine provides you with a mechanism to access the socket layer for a verbal description of the command status. Since TBPDXSock encapsulates the procedural design of the socket layer, it is better to use the GetErrorDesc method with LastCommandStatus.

      function GetErrorDesc(Const errorCode: Integer): ShortString;

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 DXSOCK6.PAS file.

      procedure SetNagle(Const TurnOn: Boolean);

This routine provides a mechanism for toggling the Nagel algorithm on or off for the socket layer.

      procedure SetBlocking(Const TurnOn: Boolean);

This routine provides a mechanism for toggling blocking for non-blocking socket calls. Blocking mode waits until the socket layer has processed your command/request before returning control back to DXSock and you.

      procedure SocketVersion(var SocketInfo: PBPDXSocketInfo);

      procedure SockClientSetGlobal(Const I: ShortString;
         Const P: Word);

Routine is public for use by client mode developers who wish to push socket handles from one application to another.

      procedure SetTimeoutAndBuffer(Const SockHandle: Integer);

This routine is called internally every time a socket is created, it sets the largest buffer size possible for reads and writes at the socket layer, and adjusts the timeout for calls to fast as possible for DXSock code can handle the situation better.

      function DroppedConnection: Boolean;

This routine is a wrapper around Connected, some people like to have their code like if DroppedConnection then... instead of if connected then.

      function WaitForData(Const timeout: Longint): Boolean;

This is a simple routine for those who do not like to use my example of while connected and is readable checking. You simply call WaitForData and tell DXSock how long to wait before timeout occurs if no data is received.

      procedure RestartCharactersPerSecondTimer;

      function CharactersPerSecondWritten: Integer;

      function CharactersPerSecondReceived: Integer;

      function CharactersPerSecondWrittenBytes: Cardinal;

      function CharactersPerSecondReceivedBytes: Cardinal;

      function GetSessionCommand(Const Commands:Array of AnsiString;
         Var Params:AnsiString):Integer;

TBPDXSock Properties

      property BindTo: ShortString;

property Connected: Boolean;

Read-Only

property CharactersToRead: Integer;

Read-Only

property ReceiveLength: Integer;

Read-Only

property ValidSocket: Boolean;

Read-Only

property LastReadTimeout: Boolean;

Read-Only

      property LastCommandStatus: Integer;

      property OutputBufferSize: TBPDXBlockSizeFlags;

      property TooManyCharacters: Integer;

      property IsUDPMode: Boolean;

      property IsKeepAliveMode: Boolean;

      property PeerIPAddress: ShortString;

      property PeerPort: Integer;

      property PeerPortAsString: ShortString;

      property LocalIPAddress: ShortString;

      property LocalPort: Integer;

      property Readable: Boolean;

      property UsingOpenSSL:Boolean;

Public Methods (Outside of an Object)

      function GetAddressCountByHost(Const Host: AnsiString): Integer;

      function GetIPAddressByHost(Const Host: AnsiString;
         Const Which: Integer): ShortString;

      function CreateSocket(const sin_family, socket_type, protocol: integer;
         var ErrorCode: Integer): TSocket;

Related Keyword:

October 16, 2010

Testing

width 0 cellspacing 0 cellpadding 0 CELL 1 Description of a product image images Thumb SN850940...

September 01, 2010

DXSock Version 6.0

TBPDXSock

Free Pascal Events

Delphi Events

Free Pascal Object

Delphi Object

Compile-time Constants

Public

TBPDXSock Methods

TBPDXSock Properties

Public Methods (Outside of an Object)