TsgcWebSocketClient

TsgcWebSocketClient implements Client WebSocket Component and can connect to a WebSocket Server. Follow the next steps to configure this component:

 

1. Drop a TsgcWebSocketClient component onto the form

 

2. Set Host and Port (default is 80) to connect to an available WebSocket Server. You can set URL property and Host, Port, Parameters... will be updated from URL. Example: wss://127.0.0.1:8080/ws/ will result:

oClient := TsgcWebSocketClient.Create(nil);
oClient.Host := '127.0.0.1';
oClient.Port := 80;
oClient.TLS := True;
oClient.Options.Parameters := '/ws/';

3. You can select if you require TLS (secure connection) or not, by default is not Activated.

 

4. You can connect through an HTTP Proxy Server, you need to define proxy properties:

 

    Host: hostname of the proxy server.

    Port: port number of the proxy server.

    Username: user to authenticate, blank if anonymous.

    Password: password to authenticate, blank if anonymous.

 

5. If the server supports compression, you can enable compression to compress messages sent.

 

6. Set Specifications allowed, by default all specifications are allowed.

 

    RFC6455: is standard and recommended WebSocket specification.

 

    HIxie76: always is false

 

7. If you want, you can handle events

 

    OnConnect: when a WebSocket connection is established, this event is fired

 

    OnDisconnect: when a WebSocket connection is dropped, this event is fired

 

    OnError: every time there is a WebSocket error (like mal-formed handshake), this event is fired

 

    OnMessage: every time the server sends a text message, this event is fired

 

    OnBinary: every time the server sends a binary message, this event is fired

 

    OnFragmented: when receives a fragment from a message (only fired when Options.FragmentedMessages = frgAll or frgOnlyFragmented).

 

    OnHandhake: this event is fired when handshake is evaluated on the client side.

 

    OnException: every time an exception occurs, this event is fired.

 

    OnSSLVerifyPeer: if verify certificate is enabled, in this event you can verify if server certificate is valid and accept or not.

 

    OnBeforeHeartBeat: if HeartBeat is enabled, allows to implement a custom HeartBeat setting Handled parameter to True (this means, standard websocket ping won't be sent).

 

    OnBeforeConnect: before the client tries to connect to server, this event is called.

 

    OnBeforeWatchDog: if WatchDog is enabled, allows to implement a custom WatchDog setting Handled parameter to True (this means, won't try to connect to server). You can change the Server Connection properties too before try to reconnect, example: connect to a fallback server if first fails.

 

 

8. Set property Active = true to start a new websocket connection

 

 

Most common uses

• Connection
  • How Connect WebSocket Server
  • Open a Client Connection
  • Close a Client Connection
  • Keep Connection active
  • Dropped Disconnections
  • Connect TCP Server
  • WebSocket Redirections

 

• Secure Servers
  • Connect Secure Server
  • Certificates OpenSSL
  • Certificates SChannel
  • SChannel Get Connection Info

 

• Send Messages
  • Send Text Message
  • Send Binary Message

 

• Receive Messages
  • Receive Text Messages
  • Receive Binary Messages

 

• Authentication
  • Client Authentication

 

• Other
  • Client Exceptions
  • Client WebSocket HandShake
  • Client Register Protocol
  • Client Proxies

 

Methods

 

    WriteData: sends a message to a WebSocket Server. Could be a String or MemoryStream. If "size" is set, the packet will be split if the size of the message is greater of size.

 

    Ping: sends a ping to a Server. If a time-out is specified, it waits for a response until a time-out is exceeded, if no response, then closes the connection.

 

    Start: uses a secondary thread to connect to the server, this prevents your application freezes while trying to connect.

 

    Stop: uses a secondary thread to disconnect from the server, this prevents your application freezes while trying to disconnect.

 

    Connect: try to connect to the server and wait till the connection is successful or there is an error.

 

    Disconnect: try to disconnect from the server and wait till disconnection is successful or there is an error.

 

 

Properties

    Authentication: if enabled, WebSocket connection will try to authenticate passing a username and password.

      

       Implements 4 types of WebSocket Authentication / Authorization methods

 

• Session: client needs to do a HTTP GET passing username and password, and if authenticated, server response a Session ID. With this Session ID, client open WebSocket connection passing as a parameter.
• URL: client open WebSocket connection passing username and password as a parameter.
• Basic: uses basic authentication where user and password as sent as HTTP Header.
• Token: sends a token as HTTP Header. Usually used for bearer tokens where token must be set in AuthToken property.
  • OAuth: if a OAuth2 component is attached, before client connects to server, it requests a new Access Token to Authorization server. OAuth2 Component.

 

     Host: IP or DNS name of the server.

     Port: the listening port of the server.

     BoundIP: (optional) only use this property if you want to set the LOCAL IP Address of the TsgcWebSocketClient.

     BoundPort: (optional) only use this property if you want to set the LOCAL Port of the TsgcWebSocketClient.

 

     HeartBeat: if enabled try to keeps alive WebSocket connection sending a ping every x seconds.

 

Interval: number of seconds between each ping.

 

Timeout: max number of seconds between a ping and pong.

 

HeartBeatType: allows to customize how the HeartBeat works

 

• hbtAlways: sends a ping every x seconds defined in the Interval.
• hbtOnlyIfNoMsgRcvInterval: sends a ping every x seconds only if no messages has been received during the latest x seconds defined in the Interval property.

 

     TCPKeepAlive: if enabled, uses keep-alive at TCP socket level, in Windows will enable SIO_KEEPALIVE_VALS if supported and if not will use keepalive. By default is disabled. Read about Dropped Disconnections.

 

Time: if after X time socket doesn't sends anything, it will send a packet to keep-alive connection (value in milliseconds).

 

Interval: after sends a keep-alive packet, if not received a response after interval, it will send another packet (value in milliseconds).

 

    ConnectTimeout: max time in milliseconds before a connection is ready.

 

  LoadBalancer: it's a client which connects to Load Balancer Server to broadcast messages and get information about servers.

 

Enabled: if enabled, it will connect to Load Balancer Server.

 

Host: Load Balancer Server Host.

 

Port: Load Balancer Server Port.

 

      Servers: here you can set manual WebSocket Servers to connect (if you don't make use of Load Balancer Server get server connection methods), example:

 

http://127.0.0.1:80

http://127.0.0.2:8888

 

    Connected: returns true if the connection is active. Use this property carefully, because uses internal "connected" Indy method, and this method may lock the thread and/or increment the use of cpu. If you want to know if the client is connected, just use the Active property, which is safer.

 

    ReadTimeout: max time in milliseconds to read messages.

 

    WriteTimeOut: max time in milliseconds sending data to other peer, 0 by default (only works under Windows OS).

 

    BoundPortMin: minimum local port used by client, by default zero (means there aren't limits).

 

    BoundPortMax: max local port used by client, by default zero (means there aren't limits).

 

    Port: Port used to connect to the host.

 

     LogFile: if enabled save socket messages to a specified log file, useful for debugging. The access to log file is not thread safe if it's accessed from several threads.

 

Enabled: if enabled every time a message is received and sent by socket it will be saved on a file.

 

FileName: full path to the filename.

 

UnMaskFrames: by default True, means that saves the websocket messages sent unmasked.

 

Raw: by default False, if enabled it will save the messages in hex format.

 

    NotifyEvents: defines which mode to notify WebSocket events.

 

neAsynchronous: this is the default mode, notify threaded events on asynchronous mode, adds events to a queue that are synchronized with the main thread asynchronously.

 

neSynchronous: if this mode is selected, notify threaded events on synchronous mode, needs to synchronize with the main thread to notify these events.

 

neNoSync: there is no synchronization with the main thread, if you need to access to controls that are not thread-safe, you need to implement your own synchronization methods.

 

    Options: allows customizing headers sent on the handshake.

 

FragmentedMessages: allows handling Fragmented Messages

 

           frgOnlyBuffer: the message is buffered until all data is received, it raises OnBinary or OnMessage event (option by default)

           frgOnlyFragmented: every time a new fragment is received, it raises OnFragmented Event.

           frgAll: every time a new fragment is received, it raises OnFragmented Event with All data received from the first packet. When all data is received, it raises OnBinary or OnMessage event.

 

Parameters: define parameters used on GET.

 

Origin: customize connection origin.

 

RaiseDisconnectExceptions: enabled by default, raises an exception every time there is a disconnection by protocol error.

 

ValidateUTF8: if enabled, validates if the message contains UTF8 valid characters, by default is disabled.

 

CleanDisconnect: if enabled, every time client disconnects from server, first sends a message to inform server connection will be closed.

 

    QueueOptions: this property allows to queue the messages in an internal queue (instead of send directly) and send the messages in the context of the connection thread, this prevents locks when several threads try to send a message. For every message type: Text, Binary or Ping a queue can be configured, by default the value set is qmNone which means the messages are not queued. The other types, means different queue levels and the difference between them are just the order where are processed (first are processed qmLevel1, then qmLevel2 and finally qmLevel3).

Example: if Text and Binary messages have the property set to qmLevel2 and Ping to qmLevel1. The client will process first the Ping messages (so the ping message is sent first than Text or Binary if they are queued at the same time), and then process the Text and Binary messages in the same queue.

 

    Extensions: you can enable compression on messages sent.

 

    Protocol: if exists, shows the current protocol used

 

    Proxy: here you can define if you want to connect through a Proxy Server, you can connect to the following proxy servers:

pxyHTTP: HTTP Proxy Server.

pxySocks4: SOCKS4 Proxy Server.

pxySocks4A: SOCKS4A Proxy Server.

pxySocks5: SOCKS5 Proxy Server.

 

    WatchDog: if enabled, when an unexpected disconnection is detected, tries to reconnect to the server automatically.

 

Interval: seconds before reconnects.

 

Attempts: max number of reconnects, if zero, then unlimited.

 

    Throttle: used to limit the number of bits per second sent/received.

 

    TLS: enables a secure connection.

 

    TLSOptions: if TLS enabled, here you can customize some TLS properties.

 

ALPNProtocols: list of the ALPN protocols which will be sent to server.

RootCertFile: path to root certificate file.

CertFile: path to certificate file.

KeyFile: path to certificate key file.

Password: if certificate is secured with a password, set here.

VerifyCertificate: if certificate must be verified, enable this property.

VerifyDepth: is an Integer property that represents the maximum number of links permitted when verification is performed for the X.509 certificate.

Version: by default negotiates all possible TLS versions from newer to lower. A specific TLS version can be selected.

tlsUndefined: this is the default value, the client will try to negotiate all possible TLS versions (starting from newest to oldest), till connects successfully.

tls1_0: implements TLS 1.0

tls1_1:implements TLS 1.1

tls1_2: implements TLS 1.2

tls1_3: implements TLS 1.3

IOHandler: select which library you will use to connection using TLS.

iohOpenSSL: uses OpenSSL library and is the default for Indy components. Requires to deploy openssl libraries (can be download from the private account of registered customers).

iohSChannel: uses Secure Channel which is a security protocol implemented by Microsoft for Windows, doesn't require to deploy openssl libraries. Only works in Windows 32/64 bits.

OpenSSL_Options: configuration of the openSSL libraries.

APIVersion: allows to define which OpenSSL API will be used.

oslAPI_1_0: uses API 1.0 OpenSSL, it's latest supported by Indy

oslAPI_1_1: uses API 1.1 OpenSSL, requires our custom Indy library and allows to use OpenSSL 1.1.1 libraries (with TLS 1.3 support).

oslAPI_3_0: uses API 3.0 OpenSSL, requires our custom Indy library and allows to use OpenSSL 3.0.0 libraries (with TLS 1.3 support).

LibPath: here you can configure where are located the openSSL libraries

oslpNone: this is the default, the openSSL libraries should be in the same folder where is the binary or in a known path.

oslpDefaultFolder: sets automatically the openSSL path where the libraries should be located for all IDE personalities.

oslpCustomFolder: if this is the option selected, define the full path in the property LibPathCustom.

LibPathCustom: when LibPath = oslpCustomFolder define here the full path where are located the openSSL libraries.

UnixSymLinks: enable or disable the loading of SymLinks under Unix systems (by default is enabled, except under OSX64):

oslsSymLinksDefault: by default are enabled except under OSX64 (after MacOS Monterey fails trying to load the library without version.).

oslsSymLinksLoadFirst: Load SymLinks and do before trying to load the version libraries.

oslsSymLinksLoad: Load SymLinks after trying to load the version libraries.

oslsSymLinksDontLoad: don't load the SymLinks.

MinVersion: set here the minimum version that will use the client to connect to a secure server. By default, the value is tlsUndefined which means the minimum version is the same which has been set in the Version property. Example: if you want to set the Client to only connect using TLS 1.2 or TLS 1.3 set the following values.

 

    SSLOptions.Version := tls1_3;

    SSLOptions.OpenSSL_Options.MinVersion := tls1_2;

 

SChannel_Options: allows to use a certificate from Windows Certificate Store.

CertHash: is the certificate Hash. You can find the certificate Hash running a dir command in powershell.

CipherList: here you can set which Ciphers will be used (separated by ":"). Example: CALG_AES_256:CALG_AES_128

CertStoreName: the store name where is stored the certificate. Select one of below:

scsnMY (the default)

scsnCA

scsnRoot

scsnTrust

CertStorePath: the store path where is stored the certificate. Select one of below:

scspStoreCurrentUser (the default)

scspStoreLocalMachine