SOAPClient Component

Properties   Methods   Events   Config Settings   Errors  

The SOAPClient component sends SOAP messages.

Syntax

TsbxSOAPClient

Remarks

The SOAPClient component implements client-side functionality of the SOAP version 1.1 and 1.2 protocols over HTTP/HTTPS.

Property List

---

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AttachmentBytes Property (SOAPClient Component)

Use this property to pass an attachment to component in the byte array form.

Syntax

property AttachmentBytes: TBytes read get_AttachmentBytes write set_AttachmentBytes;

Remarks

Assign a byte array containing the data to be processed to this property.

This property is not available at design time.

AttachmentFile Property (SOAPClient Component)

Specifies the attachment file to be sent with the request.

Syntax

property AttachmentFile: String read get_AttachmentFile write set_AttachmentFile;

Default Value

''

Remarks

Provide a full path to the attachment file to be sent with the SOAP request. Use SendMessageWithAttachments method to send the request.

Subscribe to BeforeSendAttachment to pass more than one attachment.

BlockedCertificates Property (SOAPClient Component)

The certificates that must be rejected as trust anchors.

Syntax

property BlockedCertificates: TsbxCertificateList read get_BlockedCertificates write set_BlockedCertificates;

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ClientChain Property (SOAPClient Component)

The TLS client certificate chain.

Syntax

property ClientChain: TsbxCertificateList read get_ClientChain write set_ClientChain;

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the component. Note that the client's end-entity certificate should have a private key associated with it.

Use CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ConnectionInfo Property (SOAPClient Component)

Returns the details of the underlying network connection.

Syntax

property ConnectionInfo: TsbxConnectionInfo read get_ConnectionInfo;

Remarks

Use this property to learn about the connection setup, such as the protocol security details and amounts of data transferred each way.

This property is read-only and not available at design time.

Please refer to the ConnectionInfo type for a complete list of fields.

Encoding Property (SOAPClient Component)

Specifies SOAP message encoding.

Syntax

property Encoding: String read get_Encoding write set_Encoding;

Default Value

''

Remarks

Use this property to specify the encoding to apply to the SOAP message.

ExternalCrypto Property (SOAPClient Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on OnExternalSign event) and asynchronous (based on DC protocol and DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FaultActor Property (SOAPClient Component)

Specifies the entity that caused the fault.

Syntax

property FaultActor: String read get_FaultActor;

Default Value

''

Remarks

Use this property to get the URI associated with the actor (SOAP node) that caused the fault. In RPC-style messaging, the actor is the URI of the Web service.

This property is read-only and not available at design time.

FaultCode Property (SOAPClient Component)

Specifies the error code.

Syntax

property FaultCode: String read get_FaultCode;

Default Value

''

Remarks

Use this property to get the standard code that provides more information about the fault. A set of code values is predefined by the SOAP specification. This set of fault code values can be extended by the application.

This property is read-only and not available at design time.

FaultDetail Property (SOAPClient Component)

Contains application-specific error information.

Syntax

property FaultDetail: String read get_FaultDetail;

Default Value

''

Remarks

Use this property to get the application-specific information, such as the exception that was thrown. This element can be an XML structure or plain text.

This property is read-only and not available at design time.

FaultString Property (SOAPClient Component)

Specifies a human-readable description of the fault.

Syntax

property FaultString: String read get_FaultString;

Default Value

''

Remarks

Use this property to get the human-readable description of the error that happened.

This property is read-only and not available at design time.

FIPSMode Property (SOAPClient Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

InputBytes Property (SOAPClient Component)

Use this property to pass the input to component in the byte array form.

Syntax

property InputBytes: TBytes read get_InputBytes write set_InputBytes;

Remarks

Assign a byte array containing the data to be processed to this property.

This property is not available at design time.

InputFile Property (SOAPClient Component)

A path to the file containing the SOAP message to be sent.

Syntax

property InputFile: String read get_InputFile write set_InputFile;

Default Value

''

Remarks

Use this property to provide a full path to the file containing the SOAP message to be sent to the server.

KeepAlivePolicy Property (SOAPClient Component)

Defines the keep-alive handling policy.

Syntax

property KeepAlivePolicy: TsbxKeepAlivePolicyTypes read get_KeepAlivePolicy write set_KeepAlivePolicy;

TsbxKeepAlivePolicyTypes = (
  ckapStandardDefined,
  ckapPreferKeepAlive,
  ckapRelyOnServer,
  ckapKeepAlivesDisabled
);

Default Value

ckapStandardDefined

Remarks

Use this property to tune-up the keep-alive mechanism as per the needs of your application.

KnownCertificates Property (SOAPClient Component)

Additional certificates for chain validation.

Syntax

property KnownCertificates: TsbxCertificateList read get_KnownCertificates write set_KnownCertificates;

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of certificates to be added to this collection is roughly equivalent to that of Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

KnownCRLs Property (SOAPClient Component)

Additional CRLs for chain validation.

Syntax

property KnownCRLs: TsbxCRLList read get_KnownCRLs write set_KnownCRLs;

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the CRL type for a complete list of fields.

KnownOCSPs Property (SOAPClient Component)

Additional OCSP responses for chain validation.

Syntax

property KnownOCSPs: TsbxOCSPResponseList read get_KnownOCSPs write set_KnownOCSPs;

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

MimeType Property (SOAPClient Component)

Specifies the SOAP message MIME type.

Syntax

property MimeType: String read get_MimeType write set_MimeType;

Default Value

''

Remarks

Use this property to specify the MIME type attribute of the SOAP message.

OperationName Property (SOAPClient Component)

Specifies the SOAP operation name.

Syntax

property OperationName: String read get_OperationName write set_OperationName;

Default Value

''

Remarks

Use this property to specify the name of the operation that the SOAP message corresponds to.

Set this property if InputFile, InputBytes or InputStream only contains the parameters of the operation in XML format. In this case, a new SOAP message will be created and sent to the service.

If one of the Input properties contains a valid SOAP message or an operation request in XML format, this property can be left empty.

OperationNamespaceURI Property (SOAPClient Component)

Specifies the SOAP message operation namespace URI.

Syntax

property OperationNamespaceURI: String read get_OperationNamespaceURI write set_OperationNamespaceURI;

Default Value

''

Remarks

This property specifies the operation namespace URI of the SOAP message.

OperationResponseName Property (SOAPClient Component)

Specifies the operation name of the response message.

Syntax

property OperationResponseName: String read get_OperationResponseName;

Default Value

''

Remarks

Use this property to get the operation name from the response message received from the SOAP service.

This property is read-only and not available at design time.

OperationResponseNamespaceURI Property (SOAPClient Component)

Specifies the response SOAP message operation namespace URI.

Syntax

property OperationResponseNamespaceURI: String read get_OperationResponseNamespaceURI;

Default Value

''

Remarks

Use this property to get the operation namespace URI from the response SOAP message.

This property is read-only and not available at design time.

OperationResponseTextContent Property (SOAPClient Component)

Returns the text content of the response message.

Syntax

property OperationResponseTextContent: String read get_OperationResponseTextContent;

Default Value

''

Remarks

Use this property to get the text content of the operation of the response SOAP message.

This property is read-only and not available at design time.

OperationResponseXML Property (SOAPClient Component)

Returns the XML content of the response SOAP message.

Syntax

property OperationResponseXML: String read get_OperationResponseXML;

Default Value

''

Remarks

Use this property to get the XML content of the response message.

This property is read-only and not available at design time.

OutputAttachmentBytes Property (SOAPClient Component)

Use this property to read the attachment received from the service.

Syntax

property OutputAttachmentBytes: TBytes read get_OutputAttachmentBytes;

Remarks

Check the content of this property after the operation has completed to read the received attachment data.

This property will only be set if OutputAttachmentFile and OutputAttachmentStream properties had not been assigned.

This property is read-only and not available at design time.

OutputAttachmentFile Property (SOAPClient Component)

A path to a file where to save the attachment data.

Syntax

property OutputAttachmentFile: String read get_OutputAttachmentFile write set_OutputAttachmentFile;

Default Value

''

Remarks

Provide a full path to the file where the attachment should be saved.

OutputBytes Property (SOAPClient Component)

Use this property to read the output the component object has produced.

Syntax

property OutputBytes: TBytes read get_OutputBytes;

Remarks

Read the contents of this property after the operation is completed to read the produced output. This property will only be set if OutputFile and OutputStream properties had not been assigned.

This property is read-only and not available at design time.

OutputFile Property (SOAPClient Component)

A file where the response will be saved.

Syntax

property OutputFile: String read get_OutputFile write set_OutputFile;

Default Value

''

Remarks

Provide a full path to the file where the service response should be saved.

Proxy Property (SOAPClient Component)

The proxy server settings.

Syntax

property Proxy: TsbxProxySettings read get_Proxy;

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Please refer to the ProxySettings type for a complete list of fields.

ReasonPhrase Property (SOAPClient Component)

Contains the Reason Phrase element of the server's response.

Syntax

property ReasonPhrase: String read get_ReasonPhrase;

Default Value

''

Remarks

Use this property to access the reason phrase supplied by the server in its response (such as OK in HTTP 200 OK).

This property is read-only and not available at design time.

RequestHeaders Property (SOAPClient Component)

Contains HTTP request headers.

Syntax

property RequestHeaders: TsbxStringNameValuePairList read get_RequestHeaders;

Remarks

Use this property to check and/or adjust the HTTP request headers from your HeadersPrepared event handler.

This property is read-only and not available at design time.

Please refer to the StringNameValuePair type for a complete list of fields.

RequestParameters Property (SOAPClient Component)

Provides access to common HTTP request properties.

Syntax

property RequestParameters: TsbxHTTPRequestParameters read get_RequestParameters write set_RequestParameters;

Remarks

Use this property to configure the HTTP request properties.

This property is not available at design time.

Please refer to the HTTPRequestParameters type for a complete list of fields.

ResponseHeaders Property (SOAPClient Component)

Contains the HTTP server's response headers.

Syntax

property ResponseHeaders: TsbxStringNameValuePairList read get_ResponseHeaders;

Remarks

Use this property to check the headers of the HTTP response received from the server. The headers become available as soon as HeadersReceived event is fired.

This property is read-only and not available at design time.

Please refer to the StringNameValuePair type for a complete list of fields.

ResponseParameters Property (SOAPClient Component)

Contains the HTTP server's response parameters.

Syntax

property ResponseParameters: TsbxHTTPResponseParameters read get_ResponseParameters;

Remarks

Use this property to access the properties of the received HTTP response.

This property is read-only and not available at design time.

Please refer to the HTTPResponseParameters type for a complete list of fields.

ServerChain Property (SOAPClient Component)

The TLS server's certificate chain.

Syntax

property ServerChain: TsbxCertificateList read get_ServerChain;

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when OnCertificateValidate event is fired by the client component.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

SOAPAction Property (SOAPClient Component)

Specifies the SOAP action.

Syntax

property SOAPAction: String read get_SOAPAction write set_SOAPAction;

Default Value

''

Remarks

Use this property to specify the value for the SOAPAction/action HTTP request header field. This field is normally used to indicate the intent of the SOAP request.

SOAPResponseType Property (SOAPClient Component)

The type of the response.

Syntax

property SOAPResponseType: TsbxSOAPResponseTypes read get_SOAPResponseType;

TsbxSOAPResponseTypes = (
  srtUnknown,
  srtBinary,
  srtXMLDocument,
  srtSOAPMessage
);

Default Value

srtUnknown

Remarks

Use this property to learn about the type (format) of the response provided by the SOAP service.

This property is read-only.

SOAPVersion Property (SOAPClient Component)

Specifies SOAP version.

Syntax

property SOAPVersion: TsbxSOAPProtocolVersions read get_SOAPVersion write set_SOAPVersion;

TsbxSOAPProtocolVersions = (
  spvAuto,
  spv11,
  spv12
);

Default Value

spvAuto

Remarks

This property specifies the version of the SOAP protocol. This SOAP version will be used to create a SOAP message (if needed) and to communicate with the service.

SocketSettings Property (SOAPClient Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

StatusCode Property (SOAPClient Component)

Contains the Status Code element of the server's response.

Syntax

property StatusCode: Integer read get_StatusCode;

Default Value

0

Remarks

Use this property to access the status code supplied by the server in its response (such as 200 in HTTP 200 OK).

This property is read-only and not available at design time.

TLSSettings Property (SOAPClient Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

TrustedCertificates Property (SOAPClient Component)

A list of trusted certificates for chain validation.

Syntax

property TrustedCertificates: TsbxCertificateList read get_TrustedCertificates write set_TrustedCertificates;

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same than that of Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

UseDigestAuth Property (SOAPClient Component)

Enables or disables the HTTP Digest authentication.

Syntax

property UseDigestAuth: Boolean read get_UseDigestAuth write set_UseDigestAuth;

Default Value

false

Remarks

Digest authentication is more advanced than the Basic scheme, as it does not send the username and password in plain text and is immune to replay attacks.

Digest authentication is standardized in RFC 2617.

UseKerberosAuth Property (SOAPClient Component)

Enables Kerberos authentication mechanism.

Syntax

property UseKerberosAuth: Boolean read get_UseKerberosAuth write set_UseKerberosAuth;

Default Value

false

Remarks

Set this property to true to enable Kerberos (Negotiate) authentication mechanism.

UseNTLMAuth Property (SOAPClient Component)

Enables or disables NTLM authentication.

Syntax

property UseNTLMAuth: Boolean read get_UseNTLMAuth write set_UseNTLMAuth;

Default Value

false

Remarks

NT LAN Manager (NTLM) authentication relies on Windows credentials to authenticate the user, and requires multiple exchanges between the client and server. Generally it is considered more secure and SSO-friendly than the Digest authentication.

Config Method (SOAPClient Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (SOAPClient Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insencitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

SendMessage Method (SOAPClient Component)

Sends a SOAP message to the server.

Syntax

procedure SendMessage(Url: String);

Remarks

The SendMessage() does the following:

• Loads the data from InputBytes, InputFile or InputStream properties.

  If the data contains a SOAP message, no pre-send processing is performed.

  If the data contains XML content, then basing on OperationName, OperationNamespaceURI and SOAPVersion properties new SOAP envelope will be created. The XML content will be used either as either the operation itself or the operation parameters, depending on OperationName value.

• Sends the SOAP message to the service Url.

  Use SOAPAction, Encoding and MimeType properties to set SOAP HTTP request parameters.

• If the request is successful, the received content is saved in either OutputBytes, OutputFile or OutputStream.

  If the response contains attachment(s) then BeforeReceiveAttachment event will be fired for each attachment, following which the attachment will be saved to either OutputAttachmentBytes, OutputAttachmentFile or OutputAttachmentStream.

  Use SOAPResponseType to get the type of the received content. If the received content is recognized as a SOAP message, then OperationResponseName, OperationResponseNamespaceURI OperationResponseTextContent and OperationResponseXML properties will be populated.

• If an error happens during the request, an exception is thrown.

  Use SOAPResponseType to identify the received content. The type set to Unknown means that either a connection error has occurred or the service has returned an unexpected HTTP status code. In this case, the error details are published in StatusCode and ReasonPhrase properties.

  If SOAPResponseType set to a different value indicates that the service has returned HTTP status code in the range 500 - 599, indicating a service error.

  If the type of received content is SOAP message, then FaultActor, FaultCode, FaultDetail and FaultString properties will contain error details returned by the service.

  If the request has succeeded then the received content will also be available in either OutputBytes, OutputFile or OutputStream properties.

SendMessageWithAttachments Method (SOAPClient Component)

Sends a SOAP message with attachment(s) to the server.

Syntax

procedure SendMessageWithAttachments(Url: String; PrimaryMessageId: String);

Remarks

This method follows the general pattern used by SendMessage method. It also lets you pass a selection of attachments to the service.

Assign the attachment content to AttachmentBytes, AttachmentFile, or AttachmentStream property. Subscribe to BeforeSendAttachment to pass more than one attachment.

BeforeReceiveAttachment Event (SOAPClient Component)

Marks the start of receiving an attachment.

Syntax

type TBeforeReceiveAttachmentEvent = procedure (
  Sender: TObject
) of Object;

property OnBeforeReceiveAttachment: TBeforeReceiveAttachmentEvent read FOnBeforeReceiveAttachment write FOnBeforeReceiveAttachment;

Remarks

This event fires for every new attachment being received from the service.

Tune up OutputAttachmentBytes, OutputAttachmentFile or OutputAttachmentStream properties inside the event handler to indicate where the attachment content should be saved.

BeforeSendAttachment Event (SOAPClient Component)

Marks the start of sending an attachment.

Syntax

type TBeforeSendAttachmentEvent = procedure (
  Sender: TObject;
  var LastAttachment: Boolean
) of Object;

property OnBeforeSendAttachment: TBeforeSendAttachmentEvent read FOnBeforeSendAttachment write FOnBeforeSendAttachment;

Remarks

Use either AttachmentBytes, AttachmentFile or AttachmentStream properties to pass attachment to the component.

Set LastAttachment parameter to False to indicate that you have more than one attachment to pass.

Cookie Event (SOAPClient Component)

Fired to report a received cookie.

Syntax

type TCookieEvent = procedure (
  Sender: TObject;
  const CookieText: String
) of Object;

property OnCookie: TCookieEvent read FOnCookie write FOnCookie;

Remarks

The CookieText parameter contains the text of the cookie.

DocumentBegin Event (SOAPClient Component)

Marks the start of the incoming HTML document or file.

Syntax

type TDocumentBeginEvent = procedure (
  Sender: TObject
) of Object;

property OnDocumentBegin: TDocumentBeginEvent read FOnDocumentBegin write FOnDocumentBegin;

Remarks

This event is followed by one or more Progress calls. When the document has been received in full, the DocumentEnd event is fired.

DocumentEnd Event (SOAPClient Component)

Marks the successful receipt of the incoming HTML document or file.

Syntax

type TDocumentEndEvent = procedure (
  Sender: TObject
) of Object;

property OnDocumentEnd: TDocumentEndEvent read FOnDocumentEnd write FOnDocumentEnd;

Remarks

This event fires when the document has been received in full.

Error Event (SOAPClient Component)

Information about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the HTTPS section.

ExternalSign Event (SOAPClient Component)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

type TExternalSignEvent = procedure (
  Sender: TObject;
  const OperationId: String;
  const HashAlgorithm: String;
  const Pars: String;
  const Data: String;
  var SignedData: String
) of Object;

property OnExternalSign: TExternalSignEvent read FOnExternalSign write FOnExternalSign;

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses a .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

HeadersPrepared Event (SOAPClient Component)

Fires when the request headers have been formed and are about to be sent to the server.

Syntax

type THeadersPreparedEvent = procedure (
  Sender: TObject
) of Object;

property OnHeadersPrepared: THeadersPreparedEvent read FOnHeadersPrepared write FOnHeadersPrepared;

Remarks

The prepared headers are available in RequestHeaders property. This event provides you the last chance to review/alter them.

HeadersReceived Event (SOAPClient Component)

Fires when the HTTP response headers have just been received from the server.

Syntax

type THeadersReceivedEvent = procedure (
  Sender: TObject
) of Object;

property OnHeadersReceived: THeadersReceivedEvent read FOnHeadersReceived write FOnHeadersReceived;

Remarks

The received headers are available via the ResponseHeaders property.

Notification Event (SOAPClient Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

Progress Event (SOAPClient Component)

Fires periodically during the data transfer.

Syntax

type TProgressEvent = procedure (
  Sender: TObject;
  Total: Int64;
  Current: Int64;
  var Cancel: Boolean
) of Object;

property OnProgress: TProgressEvent read FOnProgress write FOnProgress;

Remarks

Use this event to check the progress of an upload or download operation. Total indicates the total number of bytes to be transferred; Current specifies how much data has been transferred so far, and Cancel gives you a chance to cancel the operation.

Redirection Event (SOAPClient Component)

Fires when the server suggests a redirect.

Syntax

type TRedirectionEvent = procedure (
  Sender: TObject;
  const OldURL: String;
  var NewURL: String;
  var AllowRedirection: Boolean
) of Object;

property OnRedirection: TRedirectionEvent read FOnRedirection write FOnRedirection;

Remarks

This event is fired when the server suggests a redirection request (typically via a 301 or 302 response). OldURL indicates the 'from' page, and NewURL indicates the 'to' one. The destination page can be altered by the application if needed. Use AllowRedirection to block undesirable redirects.

Generally, this is a notification event: the component handles redirections automatically. Use the MaxRedirections config property to limit the number of redirection hops.

TLSCertNeeded Event (SOAPClient Component)

Fires when a remote TLS party requests a client certificate.

Syntax

type TTLSCertNeededEvent = procedure (
  Sender: TObject;
  const Host: String;
  const CANames: String
) of Object;

property OnTLSCertNeeded: TTLSCertNeededEvent read FOnTLSCertNeeded write FOnTLSCertNeeded;

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (SOAPClient Component)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

type TTLSCertValidateEvent = procedure (
  Sender: TObject;
  const ServerHost: String;
  const ServerIP: String;
  var Accept: Boolean
) of Object;

property OnTLSCertValidate: TTLSCertValidateEvent read FOnTLSCertValidate write FOnTLSCertValidate;

Remarks

This event is fired during a TLS handshake. Use TLSServerChain property to access the certificate chain. In general case, components may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the component, and can be adjusted if needed.

TLSEstablished Event (SOAPClient Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

type TTLSEstablishedEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Version: String;
  const Ciphersuite: String;
  ConnectionId: TBytes;
  var Abort: Boolean
) of Object;

property OnTLSEstablished: TTLSEstablishedEvent read FOnTLSEstablished write FOnTLSEstablished;

Remarks

The component uses this event to notify the application about successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (SOAPClient Component)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

type TTLSHandshakeEvent = procedure (
  Sender: TObject;
  const Host: String;
  var Abort: Boolean
) of Object;

property OnTLSHandshake: TTLSHandshakeEvent read FOnTLSHandshake write FOnTLSHandshake;

Remarks

The component uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed with TLSEstablished event. If the server chooses to request a client certificate, TLSCertNeeded event will also be fired.

TLSPSK Event (SOAPClient Component)

Notifies the application about the PSK key exchange.

Syntax

type TTLSPSKEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Hint: String
) of Object;

property OnTLSPSK: TTLSPSKEvent read FOnTLSPSK write FOnTLSPSK;

Remarks

The component fires this event to notify the application about the beginning of TLS-PSK key exchange with Host. The Hint parameter may be used by the server to identify the key or service to use. Use the PreSharedKey field of TLSSettings to provide the pre-shared key to the component.

TLSShutdown Event (SOAPClient Component)

Reports the graceful closure of a TLS connection.

Syntax

type TTLSShutdownEvent = procedure (
  Sender: TObject;
  const Host: String
) of Object;

property OnTLSShutdown: TTLSShutdownEvent read FOnTLSShutdown write FOnTLSShutdown;

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

ConnectionInfo Type

Contains information about a network connection.

Remarks

Use this property to check various details of the network connection. These include the total amounts of data transferred, the availability of TLS, and its parameters.

Fields

Constructors

>

constructor Create();

Creates a new ConnectionInfo object.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

>

constructor Create();

Creates an empty CRL object.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

>

constructor Create();

Creates a new ExternalCrypto object with default field values.

HTTPRequestParameters Type

Represents the headers of the HTTP request to make.

Remarks

If a header is not assigned but required for a successful request (such as Connection or Host), it will be generated automatically by the component.

Fields

Constructors

>

constructor Create();

Creates a new HTTPRequestParameters object.

HTTPResponseParameters Type

This object is a container for HTTP server response details.

Remarks

An HTTP response is sent by the server when it has processed the client's request. The response consists of the status code (perhaps, the most annoying and widely known one is 404), the reason phrase, the response headers, and the body (the actual data) of the response.

Fields

Constructors

>

constructor Create();

Creates a new HTTPResponseParameters object.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRL).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

>

constructor Create();

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

>

constructor Create();

Creates a new ProxySettings object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

>

constructor Create();

Creates a new SocketSettings object.

StringNameValuePair Type

A simple name-value pair object.

Remarks

The component represents a name-value string pair used in a variety of network components.

Fields

Constructors

>

constructor Create(valName: String; valValue: String);

Creates a name-value pair from a name and a value.

>

constructor Create();

Creates an empty name-value object.

TLSSettings Type

A container for TLS connection settings.

Remarks

TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

>

constructor Create();

Creates a new TLSSettings object.

Config Settings (SOAPClient Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

HTTPClient Config Settings

Base Config Settings

Trappable Errors (SOAPClient Component)

SOAPClient Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) 
	19922945   Unsupported keep-alive policy (SB_ERROR_HTTP_UNSUPPORTED_KEEPALIVEPOLICY) 
	33554689   Unexpected HTTP status code (SB_ERROR_SOAP_CLIENT_UNEXPECTED_HTTP_STATUS_CODE)
	33554690   SOAP service failed (SB_ERROR_SOAP_CLIENT_SERVICE_FAILED)