RESTClient Component

Properties   Methods   Events   Config Settings   Errors  

The RESTClient component implements client-side functionality for the REST protocol.

Syntax

nsoftware.SecureBlackbox.Restclient

Remarks

RESTClient allows you to send requests to a REST server and receive server responses. It supports both plain (HTTP) and secure (HTTPS) modes.

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.

BlockedCertificates Property (RESTClient Component)

The certificates that must be rejected as trust anchors.

Syntax

• C#
• VB.NET

public CertificateList BlockedCertificates { get; }

Public Property BlockedCertificates As CertificateList

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.

ClientChain Property (RESTClient Component)

The TLS client certificate chain.

Syntax

• C#
• VB.NET

public CertificateList ClientChain { get; }

Public Property ClientChain As CertificateList

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.

ConnectionInfo Property (RESTClient Component)

Returns the details of the underlying network connection.

Syntax

• C#
• VB.NET

public ConnectionInfo ConnectionInfo { get; }

Public ReadOnly Property ConnectionInfo As 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.

CustomRequest Property (RESTClient Component)

Specifies a custom request verb.

Syntax

• C#
• VB.NET

public string CustomRequest { get; set; }

Public Property CustomRequest As String

Default Value

""

Remarks

Use this property to specify a custom HTTP method verb to use instead of the original method. PATCH is one of the commonly used custom verbs.

This property is not available at design time.

DynamicData Property (RESTClient Component)

Takes a piece of data to be sent to the server within a dynamic POST or PUT request.

Syntax

• C#
• VB.NET

public byte[] DynamicData { get; set; }

Public Property DynamicData As Byte()

Remarks

Assign the next chunk of data to this property from your DynamicDataNeeded event handler to pass it to the server. Leave it empty to tell the component that no more data is available.

This property is not available at design time.

ExternalCrypto Property (RESTClient Component)

Provides access to external signing and DC parameters.

Syntax

• C#
• VB.NET

public ExternalCrypto ExternalCrypto { get; }

Public ReadOnly Property ExternalCrypto As 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.

FIPSMode Property (RESTClient Component)

Reserved.

Syntax

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

Default Value

False

Remarks

This property is reserved for future use.

KeepAlivePolicy Property (RESTClient Component)

Defines the keep-alive handling policy.

Syntax

• C#
• VB.NET

public RestclientKeepAlivePolicies KeepAlivePolicy { get; set; }

enum RestclientKeepAlivePolicies {
  ckapStandardDefined,
  ckapPreferKeepAlive,
  ckapRelyOnServer,
  ckapKeepAlivesDisabled
}

Public Property KeepAlivePolicy As RestclientKeepAlivePolicies

Enum RestclientKeepAlivePolicies
  ckapStandardDefined
  ckapPreferKeepAlive
  ckapRelyOnServer
  ckapKeepAlivesDisabled
End Enum

Default Value

0

Remarks

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

KnownCertificates Property (RESTClient Component)

Additional certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList KnownCertificates { get; }

Public Property KnownCertificates As CertificateList

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.

KnownCRLs Property (RESTClient Component)

Additional CRLs for chain validation.

Syntax

• C#
• VB.NET

public CRLList KnownCRLs { get; }

Public Property KnownCRLs As CRLList

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.

KnownOCSPs Property (RESTClient Component)

Additional OCSP responses for chain validation.

Syntax

• C#
• VB.NET

public OCSPResponseList KnownOCSPs { get; }

Public Property KnownOCSPs As OCSPResponseList

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.

OutputBytes Property (RESTClient Component)

Contains the response content.

Syntax

• C#
• VB.NET

public byte[] OutputBytes { get; }

Public ReadOnly Property OutputBytes As Byte()

Remarks

Use this property to access the content received from the server in response to a prior request.

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

OutputString Property (RESTClient Component)

Contains the response content.

Syntax

• C#
• VB.NET

public string OutputString { get; }

Public ReadOnly Property OutputString As String

Default Value

""

Remarks

Use this property to access the content received from the server in response to a prior request, as a string.

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

Proxy Property (RESTClient Component)

The proxy server settings.

Syntax

• C#
• VB.NET

public ProxySettings Proxy { get; }

Public ReadOnly Property Proxy As ProxySettings

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

ReasonPhrase Property (RESTClient Component)

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

Syntax

• C#
• VB.NET

public string ReasonPhrase { get; }

Public ReadOnly Property ReasonPhrase As String

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 (RESTClient Component)

Contains HTTP request headers.

Syntax

• C#
• VB.NET

public StringNameValuePairList RequestHeaders { get; }

Public ReadOnly Property RequestHeaders As StringNameValuePairList

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.

RequestParameters Property (RESTClient Component)

Provides access to common HTTP request properties.

Syntax

• C#
• VB.NET

public HTTPRequestParameters RequestParameters { get; set; }

Public Property RequestParameters As HTTPRequestParameters

Remarks

Use this property to configure the HTTP request properties.

This property is not available at design time.

ResponseHeaders Property (RESTClient Component)

Contains the HTTP server's response headers.

Syntax

• C#
• VB.NET

public StringNameValuePairList ResponseHeaders { get; }

Public ReadOnly Property ResponseHeaders As StringNameValuePairList

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.

ResponseParameters Property (RESTClient Component)

Contains the HTTP server's response parameters.

Syntax

• C#
• VB.NET

public HTTPResponseParameters ResponseParameters { get; }

Public ReadOnly Property ResponseParameters As HTTPResponseParameters

Remarks

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

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

ServerChain Property (RESTClient Component)

The TLS server's certificate chain.

Syntax

• C#
• VB.NET

public CertificateList ServerChain { get; }

Public ReadOnly Property ServerChain As CertificateList

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.

SocketSettings Property (RESTClient Component)

Manages network connection settings.

Syntax

• C#
• VB.NET

public SocketSettings SocketSettings { get; }

Public ReadOnly Property SocketSettings As SocketSettings

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

StatusCode Property (RESTClient Component)

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

Syntax

• C#
• VB.NET

public int StatusCode { get; }

Public ReadOnly Property StatusCode As Integer

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 (RESTClient Component)

Manages TLS layer settings.

Syntax

• C#
• VB.NET

public TLSSettings TLSSettings { get; }

Public ReadOnly Property TLSSettings As TLSSettings

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

TrustedCertificates Property (RESTClient Component)

A list of trusted certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList TrustedCertificates { get; }

Public Property TrustedCertificates As CertificateList

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.

UseDigestAuth Property (RESTClient Component)

Enables or disables the HTTP Digest authentication.

Syntax

• C#
• VB.NET

public bool UseDigestAuth { get; set; }

Public Property UseDigestAuth As Boolean

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.

UseNTLMAuth Property (RESTClient Component)

Enables or disables NTLM authentication.

Syntax

• C#
• VB.NET

public bool UseNTLMAuth { get; set; }

Public Property UseNTLMAuth As Boolean

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 (RESTClient Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As 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.

Delete Method (RESTClient Component)

Sends a DELETE request to the server.

Syntax

• C#
• VB.NET

public void Delete(string url);

Public Sub Delete(ByVal Url As String)

Remarks

Use this method to send a DELETE request to server. In response to this request, the server may (without any guarantees) delete the resource specified in Url. Most of the servers disable DELETE requests.

If this request fails, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

DoAction Method (RESTClient Component)

Performs an additional action.

Syntax

• C#
• VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As 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;....

Get Method (RESTClient Component)

Sends a GET request to the server.

Syntax

• C#
• VB.NET

public void Get(string url);

Public Sub Get(ByVal Url As String)

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the received content will be available in OutputBytes and OutputString properties. Otherwise an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

GetBytes Method (RESTClient Component)

Sends a GET request to the server and returns the output.

Syntax

• C#
• VB.NET

public byte[] GetBytes(string url);

Public Function GetBytes(ByVal Url As String) As Byte()

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the method returns the received content. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

GetFile Method (RESTClient Component)

Sends a GET request to the server and saves the output to a file.

Syntax

• C#
• VB.NET

public void GetFile(string url, string filename);

Public Sub GetFile(ByVal Url As String, ByVal Filename As String)

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the received content will be saved to Filename. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

GetStream Method (RESTClient Component)

Sends a GET request to the server and saves the output in a stream.

Syntax

• C#
• VB.NET

public void GetStream(string url, System.IO.Stream outputStream);

Public Sub GetStream(ByVal Url As String, ByVal OutputStream As System.IO.Stream)

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the method saves the received content to OutputStream. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Head Method (RESTClient Component)

Sends a HEAD request to the server.

Syntax

• C#
• VB.NET

public void Head(string url);

Public Sub Head(ByVal Url As String)

Remarks

HEAD is very similar to GET, with the only difference being that only the headers (but not the content) is returned.

HEAD is often use to retrieve the parameters of the resource, such as its size and modification date. If the request is successful, those details will be available via ResponseParameters and ResponseHeaders properties. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Options Method (RESTClient Component)

Sends an OPTIONS request to the server.

Syntax

• C#
• VB.NET

public void Options(string url);

Public Sub Options(ByVal Url As String)

Remarks

This request gets various information about the server such as supported HTTP methods. No content is included in the response.

Post Method (RESTClient Component)

Sends a POST request to the server.

Syntax

• C#
• VB.NET

public void Post(string url, string content);

Public Sub Post(ByVal Url As String, ByVal Content As String)

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the data you need to send via the Content parameter. If Content is omitted, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event.

To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostBytes Method (RESTClient Component)

Sends a POST request to the server.

Syntax

• C#
• VB.NET

public void PostBytes(string url, byte[] contentBytes);

Public Sub PostBytes(ByVal Url As String, ByVal ContentBytes As Byte())

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the data you need to send via the ContentBytes parameter. If content is omitted, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event.

To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostFile Method (RESTClient Component)

Sends a file to the server using a POST request.

Syntax

• C#
• VB.NET

public void PostFile(string url, string filename);

Public Sub PostFile(ByVal Url As String, ByVal Filename As String)

Remarks

POST is used to send data to the remote HTTP endpoint/script. The content to send will be taken from Filename.

To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostJSON Method (RESTClient Component)

Sends a JSON POST request to the server.

Syntax

• C#
• VB.NET

public void PostJSON(string url, string content);

Public Sub PostJSON(ByVal Url As String, ByVal Content As String)

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the JSON data you need to send via the Content parameter. If Content is omitted, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event.

To post a regular (non-JSON) data, use Post method. To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostStream Method (RESTClient Component)

Sends a POST request to the server.

Syntax

• C#
• VB.NET

public void PostStream(string url, System.IO.Stream inputStream);

Public Sub PostStream(ByVal Url As String, ByVal InputStream As System.IO.Stream)

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the data you need to send via the InputStream parameter.

To post a web form data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostWebForm Method (RESTClient Component)

Posts a web form data to the server.

Syntax

• C#
• VB.NET

public void PostWebForm(string url, string fields, string fileField, string fileName, string contentType);

Public Sub PostWebForm(ByVal Url As String, ByVal Fields As String, ByVal FileField As String, ByVal FileName As String, ByVal ContentType As String)

Remarks

This variant of the POST method provides means to submit a form (as in a web browser) with an optional file attachment. Fields are expected to contain a list of field names and values in "Name=Value" format separated with EOLs. This list can be empty.

If including a file with your request, use the FileField and FileName properties to specify the file field name and the local filename for the uploaded file. Use ContentType to override the default content type chosen by the client, e.g., "application/x-www-form-urlencoded".

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostXML Method (RESTClient Component)

Posts an XML request to the server.

Syntax

• C#
• VB.NET

public void PostXML(string url, string content);

Public Sub PostXML(ByVal Url As String, ByVal Content As String)

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the XML data you need to send via the Content parameter. If Content is omitted, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event.

To post a regular (non-XML) data, use Post method. To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Put Method (RESTClient Component)

Sends a PUT request to the server.

Syntax

• C#
• VB.NET

public void Put(string url, string content);

Public Sub Put(ByVal Url As String, ByVal Content As String)

Remarks

PUT method is used to write data to the server. This method is optional to support and is disabled on most of HTTP servers.

If Content is not present, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event. Note that some servers do not support streaming.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutBytes Method (RESTClient Component)

Sends a PUT request to the server.

Syntax

• C#
• VB.NET

public void PutBytes(string url, byte[] contentBytes);

Public Sub PutBytes(ByVal Url As String, ByVal ContentBytes As Byte())

Remarks

PUT method is used to write data to the server. This method is optional to support and is disabled on most of HTTP servers.

If ContentBytes is not present, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event. Note that some servers do not support streaming.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutFile Method (RESTClient Component)

Sends a file to the server using a PUT request.

Syntax

• C#
• VB.NET

public void PutFile(string url, string filename);

Public Sub PutFile(ByVal Url As String, ByVal Filename As String)

Remarks

PUT is an alternative to POST and is used to send data to the remote HTTP endpoint/script. Many servers have this method switched off. The content to send will be taken from Filename.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutJSON Method (RESTClient Component)

PUTs a JSON to the server.

Syntax

• C#
• VB.NET

public void PutJSON(string url, string content);

Public Sub PutJSON(ByVal Url As String, ByVal Content As String)

Remarks

PUT method is used to write data to the server.

If Content is not present, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event. Note that some servers do not support streaming.

To PUT a regular (non-JSON) data, use Put method. To post JSON data, use PostJSON method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutStream Method (RESTClient Component)

Sends a PUT request to the server.

Syntax

• C#
• VB.NET

public void PutStream(string url, System.IO.Stream inputStream);

Public Sub PutStream(ByVal Url As String, ByVal InputStream As System.IO.Stream)

Remarks

PUT is an alternative to POST, and is used to send data to the remote HTTP endpoint/script. Many servers have this method switched off.

Provide the data you need to send via the InputStream parameter.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutXML Method (RESTClient Component)

PUTs an XML to the server.

Syntax

• C#
• VB.NET

public void PutXML(string url, string content);

Public Sub PutXML(ByVal Url As String, ByVal Content As String)

Remarks

PUT method is used to write data to the server.

If Content is not present, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event. Note that some servers do not support streaming.

To PUT a regular (non-XML) data, use Put method. To post XML data, use PostXML method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Trace Method (RESTClient Component)

Sends a TRACE request to the server.

Syntax

• C#
• VB.NET

public void Trace(string url);

Public Sub Trace(ByVal Url As String)

Remarks

TRACE is a debug command and is typically switched off and/or not supported by web servers.

Cookie Event (RESTClient Component)

Fired to report a received cookie.

Syntax

• C#
• VB.NET

public event OnCookieHandler OnCookie;

public delegate void OnCookieHandler(object sender, RestclientCookieEventArgs e);

public class RestclientCookieEventArgs : EventArgs {
  public string CookieText { get; }
}

Public Event OnCookie As OnCookieHandler

Public Delegate Sub OnCookieHandler(sender As Object, e As RestclientCookieEventArgs)

Public Class RestclientCookieEventArgs Inherits EventArgs
  Public ReadOnly Property CookieText As String
End Class

Remarks

The CookieText parameter contains the text of the cookie.

DocumentBegin Event (RESTClient Component)

Marks the start of the incoming HTML document or file.

Syntax

• C#
• VB.NET

public event OnDocumentBeginHandler OnDocumentBegin;

public delegate void OnDocumentBeginHandler(object sender, RestclientDocumentBeginEventArgs e);

public class RestclientDocumentBeginEventArgs : EventArgs {
}

Public Event OnDocumentBegin As OnDocumentBeginHandler

Public Delegate Sub OnDocumentBeginHandler(sender As Object, e As RestclientDocumentBeginEventArgs)

Public Class RestclientDocumentBeginEventArgs Inherits EventArgs
End Class

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 (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnDocumentEndHandler OnDocumentEnd;

public delegate void OnDocumentEndHandler(object sender, RestclientDocumentEndEventArgs e);

public class RestclientDocumentEndEventArgs : EventArgs {
}

Public Event OnDocumentEnd As OnDocumentEndHandler

Public Delegate Sub OnDocumentEndHandler(sender As Object, e As RestclientDocumentEndEventArgs)

Public Class RestclientDocumentEndEventArgs Inherits EventArgs
End Class

Remarks

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

DynamicDataNeeded Event (RESTClient Component)

Requests a portion of data to be uploaded from the application.

Syntax

• C#
• VB.NET

public event OnDynamicDataNeededHandler OnDynamicDataNeeded;

public delegate void OnDynamicDataNeededHandler(object sender, RestclientDynamicDataNeededEventArgs e);

public class RestclientDynamicDataNeededEventArgs : EventArgs {
  public int BytesNeeded { get; }
}

Public Event OnDynamicDataNeeded As OnDynamicDataNeededHandler

Public Delegate Sub OnDynamicDataNeededHandler(sender As Object, e As RestclientDynamicDataNeededEventArgs)

Public Class RestclientDynamicDataNeededEventArgs Inherits EventArgs
  Public ReadOnly Property BytesNeeded As Integer
End Class

Remarks

If dynamic ('streaming') variants of PUT or POST methods are used, this event is fired periodically to request portions of data to be sent to the server.

When handling this event, assign the next portion of data of BytesNeeded length (or less) to DynamicData. If no more data is available to upload (the whole document has been sent), leave DynamicData empty.

Error Event (RESTClient Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, RestclientErrorEventArgs e);

public class RestclientErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As RestclientErrorEventArgs)

Public Class RestclientErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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 (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnExternalSignHandler OnExternalSign;

public delegate void OnExternalSignHandler(object sender, RestclientExternalSignEventArgs e);

public class RestclientExternalSignEventArgs : EventArgs {
  public string OperationId { get; }
  public string HashAlgorithm { get; }
  public string Pars { get; }
  public string Data { get; }
  public string SignedData { get; set; }
}

Public Event OnExternalSign As OnExternalSignHandler

Public Delegate Sub OnExternalSignHandler(sender As Object, e As RestclientExternalSignEventArgs)

Public Class RestclientExternalSignEventArgs Inherits EventArgs
  Public ReadOnly Property OperationId As String
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property Data As String
  Public Property SignedData As String
End Class

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 (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnHeadersPreparedHandler OnHeadersPrepared;

public delegate void OnHeadersPreparedHandler(object sender, RestclientHeadersPreparedEventArgs e);

public class RestclientHeadersPreparedEventArgs : EventArgs {
}

Public Event OnHeadersPrepared As OnHeadersPreparedHandler

Public Delegate Sub OnHeadersPreparedHandler(sender As Object, e As RestclientHeadersPreparedEventArgs)

Public Class RestclientHeadersPreparedEventArgs Inherits EventArgs
End Class

Remarks

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

HeadersReceived Event (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnHeadersReceivedHandler OnHeadersReceived;

public delegate void OnHeadersReceivedHandler(object sender, RestclientHeadersReceivedEventArgs e);

public class RestclientHeadersReceivedEventArgs : EventArgs {
}

Public Event OnHeadersReceived As OnHeadersReceivedHandler

Public Delegate Sub OnHeadersReceivedHandler(sender As Object, e As RestclientHeadersReceivedEventArgs)

Public Class RestclientHeadersReceivedEventArgs Inherits EventArgs
End Class

Remarks

The received headers are available via the ResponseHeaders property.

Notification Event (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnNotificationHandler OnNotification;

public delegate void OnNotificationHandler(object sender, RestclientNotificationEventArgs e);

public class RestclientNotificationEventArgs : EventArgs {
  public string EventID { get; }
  public string EventParam { get; }
}

Public Event OnNotification As OnNotificationHandler

Public Delegate Sub OnNotificationHandler(sender As Object, e As RestclientNotificationEventArgs)

Public Class RestclientNotificationEventArgs Inherits EventArgs
  Public ReadOnly Property EventID As String
  Public ReadOnly Property EventParam As String
End Class

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 (RESTClient Component)

Fires periodically during the data transfer.

Syntax

• C#
• VB.NET

public event OnProgressHandler OnProgress;

public delegate void OnProgressHandler(object sender, RestclientProgressEventArgs e);

public class RestclientProgressEventArgs : EventArgs {
  public long Total { get; }
  public long Current { get; }
  public bool Cancel { get; set; }
}

Public Event OnProgress As OnProgressHandler

Public Delegate Sub OnProgressHandler(sender As Object, e As RestclientProgressEventArgs)

Public Class RestclientProgressEventArgs Inherits EventArgs
  Public ReadOnly Property Total As Long
  Public ReadOnly Property Current As Long
  Public Property Cancel As Boolean
End Class

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 (RESTClient Component)

Fires when the server suggests a redirect.

Syntax

• C#
• VB.NET

public event OnRedirectionHandler OnRedirection;

public delegate void OnRedirectionHandler(object sender, RestclientRedirectionEventArgs e);

public class RestclientRedirectionEventArgs : EventArgs {
  public string OldURL { get; }
  public string NewURL { get; set; }
  public bool AllowRedirection { get; set; }
}

Public Event OnRedirection As OnRedirectionHandler

Public Delegate Sub OnRedirectionHandler(sender As Object, e As RestclientRedirectionEventArgs)

Public Class RestclientRedirectionEventArgs Inherits EventArgs
  Public ReadOnly Property OldURL As String
  Public Property NewURL As String
  Public Property AllowRedirection As Boolean
End Class

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 (RESTClient Component)

Fires when a remote TLS party requests a client certificate.

Syntax

• C#
• VB.NET

public event OnTLSCertNeededHandler OnTLSCertNeeded;

public delegate void OnTLSCertNeededHandler(object sender, RestclientTLSCertNeededEventArgs e);

public class RestclientTLSCertNeededEventArgs : EventArgs {
  public string Host { get; }
  public string CANames { get; }
}

Public Event OnTLSCertNeeded As OnTLSCertNeededHandler

Public Delegate Sub OnTLSCertNeededHandler(sender As Object, e As RestclientTLSCertNeededEventArgs)

Public Class RestclientTLSCertNeededEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property CANames As String
End Class

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 (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnTLSCertValidateHandler OnTLSCertValidate;

public delegate void OnTLSCertValidateHandler(object sender, RestclientTLSCertValidateEventArgs e);

public class RestclientTLSCertValidateEventArgs : EventArgs {
  public string ServerHost { get; }
  public string ServerIP { get; }
  public bool Accept { get; set; }
}

Public Event OnTLSCertValidate As OnTLSCertValidateHandler

Public Delegate Sub OnTLSCertValidateHandler(sender As Object, e As RestclientTLSCertValidateEventArgs)

Public Class RestclientTLSCertValidateEventArgs Inherits EventArgs
  Public ReadOnly Property ServerHost As String
  Public ReadOnly Property ServerIP As String
  Public Property Accept As Boolean
End Class

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 (RESTClient Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

• C#
• VB.NET

public event OnTLSEstablishedHandler OnTLSEstablished;

public delegate void OnTLSEstablishedHandler(object sender, RestclientTLSEstablishedEventArgs e);

public class RestclientTLSEstablishedEventArgs : EventArgs {
  public string Host { get; }
  public string Version { get; }
  public string Ciphersuite { get; }
  public byte[] ConnectionId { get; }
  public bool Abort { get; set; }
}

Public Event OnTLSEstablished As OnTLSEstablishedHandler

Public Delegate Sub OnTLSEstablishedHandler(sender As Object, e As RestclientTLSEstablishedEventArgs)

Public Class RestclientTLSEstablishedEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property Version As String
  Public ReadOnly Property Ciphersuite As String
  Public ReadOnly Property ConnectionId As Byte()
  Public Property Abort As Boolean
End Class

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 (RESTClient Component)

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

Syntax

• C#
• VB.NET

public event OnTLSHandshakeHandler OnTLSHandshake;

public delegate void OnTLSHandshakeHandler(object sender, RestclientTLSHandshakeEventArgs e);

public class RestclientTLSHandshakeEventArgs : EventArgs {
  public string Host { get; }
  public bool Abort { get; set; }
}

Public Event OnTLSHandshake As OnTLSHandshakeHandler

Public Delegate Sub OnTLSHandshakeHandler(sender As Object, e As RestclientTLSHandshakeEventArgs)

Public Class RestclientTLSHandshakeEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public Property Abort As Boolean
End Class

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 (RESTClient Component)

Notifies the application about the PSK key exchange.

Syntax

• C#
• VB.NET

public event OnTLSPSKHandler OnTLSPSK;

public delegate void OnTLSPSKHandler(object sender, RestclientTLSPSKEventArgs e);

public class RestclientTLSPSKEventArgs : EventArgs {
  public string Host { get; }
  public string Hint { get; }
}

Public Event OnTLSPSK As OnTLSPSKHandler

Public Delegate Sub OnTLSPSKHandler(sender As Object, e As RestclientTLSPSKEventArgs)

Public Class RestclientTLSPSKEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property Hint As String
End Class

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 (RESTClient Component)

Reports the graceful closure of a TLS connection.

Syntax

• C#
• VB.NET

public event OnTLSShutdownHandler OnTLSShutdown;

public delegate void OnTLSShutdownHandler(object sender, RestclientTLSShutdownEventArgs e);

public class RestclientTLSShutdownEventArgs : EventArgs {
  public string Host { get; }
}

Public Event OnTLSShutdown As OnTLSShutdownHandler

Public Delegate Sub OnTLSShutdownHandler(sender As Object, e As RestclientTLSShutdownEventArgs)

Public Class RestclientTLSShutdownEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
End Class

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

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

• C#
• VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate();

Public Certificate()

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

• C#
• VB.NET

public ConnectionInfo();

Public ConnectionInfo()

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

• C#
• VB.NET

public CRL(byte[] bytes, int startIndex, int count);

Public CRL(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Creates a CRL object from a memory buffer. Bytes is a buffer containing raw (DER) CRL data, StartIndex and Count specify the starting position and the length of the CRL data in the buffer, respectively.

• C#
• VB.NET

public CRL(string location);

Public CRL(ByVal Location As String)

Creates a CRL object by downloading it from a remote location.

• C#
• VB.NET

public CRL(System.IO.Stream stream);

Public CRL(ByVal Stream As System.IO.Stream)

Creates a CRL object from data contained in a stream.

• C#
• VB.NET

public CRL();

Public CRL()

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

• C#
• VB.NET

public ExternalCrypto();

Public ExternalCrypto()

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

• C#
• VB.NET

public HTTPRequestParameters();

Public HTTPRequestParameters()

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

• C#
• VB.NET

public HTTPResponseParameters();

Public HTTPResponseParameters()

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

• C#
• VB.NET

public OCSPResponse(byte[] bytes, int startIndex, int count);

Public OCSPResponse(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Initializes the response from a memory buffer. Bytes is a buffer containing raw OCSP response data, StartIndex and Count specify the starting position and the number of bytes to be read from this buffer.

• C#
• VB.NET

public OCSPResponse(string location);

Public OCSPResponse(ByVal Location As String)

Downloads an OCSP response from a remote location.

• C#
• VB.NET

public OCSPResponse(System.IO.Stream stream);

Public OCSPResponse(ByVal Stream As System.IO.Stream)

Initializes the response with the data from a stream.

• C#
• VB.NET

public OCSPResponse();

Public OCSPResponse()

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

• C#
• VB.NET

public ProxySettings();

Public ProxySettings()

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

• C#
• VB.NET

public SocketSettings();

Public SocketSettings()

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

• C#
• VB.NET

public StringNameValuePair(string name, string value);

Public StringNameValuePair(ByVal Name As String, ByVal Value As String)

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

• C#
• VB.NET

public StringNameValuePair();

Public StringNameValuePair()

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