TsgcHTTP2Client implements Client HTTP/2 Component and can connect to a HTTP/2 Servers. Follow the next steps to configure this component:
1. Create a new instance of TsgcHTTP2Client component.
2. Send the request to server and process the response using OnHTTP2Response event. example:
oClient := TsgcHTTP2Client.Create(nil);
oClient.OnHTTP2Response := OnHTTP2ResponseEvent;
oClient.Get('https://www.google.com');
procedure OnHTTP2ResponseEvent(Sender: TObject; const
Connection: TsgcHTTP2ConnectionClient; const Request:
TsgcHTTP2RequestProperty; const Response: TsgcHTTP2ResponseProperty);
begin
ShowMessage(Response.DataString);
end;
The following HTTP methods are supported:
GET: The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.
HEAD: The HEAD method asks for a response identical to that of a GET request, but without the response body.
POST: The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server.
PUT: The PUT method replaces all current representations of the target resource with the request payload.
DELETE: The HEAD method asks for a response identical to that of a GET request, but without the response body.
CONNECT: The CONNECT method establishes a tunnel to the server identified by the target resource.
OPTIONS: The OPTIONS method is used to describe the communication options for the target resource.
TRACE: The TRACE method performs a message loop-back test along the path to the target resource.
PATCH: The PATCH method is used to apply partial modifications to a resource.
HTTP/2 client component also implement the following methods:
Ping: sends a ping to a Server.
Close: sends a message to server about connection will be closed.
Disconnect: disconnects the socket connection.
Authentication: allows to authenticate against OAuth2 before send an HTTP/2 request.
Token
OAuth: assign here a TsgcHTTP_OAuth_Client component to get OAuth2 credentials. Read more about OAuth2.
JWT: assign here a TsgcHTTP_JWT_Client component to get JWT credentials. Read more about JWT.
Request: Specifies the header values to send to the HTTP/2 server.
Settings: Specifies the header values to send to the HTTP/2 server.
EnablePush: by default enabled, this setting can be used to avoid server push content to client.
HeaderTableSize: Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is 4,096 octets.
InitialWindowSize: Indicates the sender’s initial window size (in octets) for stream-level flow control. The initial value is 65,535 octets. This setting affects the window size of all streams.
MaxConcurrentStreams: Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value.
MaxFrameSize: Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is 16,384 octets.
MaxHeaderListSize: This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field.
FragmentedData: this property allows to configure how handle the fragments received.
h2fdOnlyBuffer: it's the default option, the response is dispatched only when has been received the latest packet.
h2fdAll: the response is dispatched for every packet received (one or more) on the event OnHTTP2ResponseFragment and on the event OnHTTP2Response when the latest packet has been received.
h2fdOnlyFragmented:: the response is only dispatched in the event OnHTTP2ResponseFragment for every packet received (one response can be compound of 1 or multiple packets).
Host: IP or DNS name of the server.
HeartBeat: if enabled try to keeps alive HTTP/2 connection sending a ping every x seconds.
Interval: number of seconds between each ping.
HeartBeatType: allows to customize how the HeartBeat works
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.
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).
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.
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.
Proxy: here you can define if you want to connect through a HTTP Proxy Server. If you need to connect to SOCKS proxies, just enable SOCKS.Enable property too.
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 uses TLS 1.0, if server requires a higher TLS version, here can be selected.
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 for win32/win64.
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.
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
UseLegacyCredentials: force the use of SCHANNEL_CRED.
OnHTTP2Response
This event is called when client receives a Response from Server. Access to Response object to get full information about Server Response.
Response.Headers: HTTP/2 headers
Response.Data: Raw body response.
Response.DataString: body response as string.
Response.DataUTF8: body response as UTF-8 string.
procedure OnHTTP2ResponseEvent(Sender: TObject; const Connection: TsgcHTTP2ConnectionClient;
const Request: TsgcHTTP2RequestProperty; const Response: TsgcHTTP2ResponseProperty);
begin
ShowMessage(Response.Headers.Text + #13#10 + Response.DataString);
end;
OnHTTP2ResponseFragment
This event is called when client receives a fragment response from Server, so means that this stream will receive more updates.
OnHTTP2Authorization
In this event you can set the UserName and Password when Authentication is Basic, or the Token for OAuth2 Authentications.
OnHTTP2BeforeRequest
This event is called before client sends Headers Request to server. You can add or modify the headers before are sent to HTTP/2 server.
OnHTTP2Connect
This event is called just after client connects successfully to server.
OnHTTP2Disconnect
This event is called when connection is closed.
OnHTTP2Exception
If there is any exception while client is connected to server, here you can catch the Exception.
OnHTTP2GoAway
This event is raised when client receives a GoAway message from server.
OnHTTP2PendingRequests
After a disconnection, if there are pending requests to be sent or received, here you can set if you want reconnect and/or clear pending requests.
OnHTTP2PushPromise
When server sends a PushPromise to client, client can accept or not the PushPromise packets.
OnHTTP2RSTStream
When server resets a stream, this event is called.