SOAPClient Component

Properties   Methods   Events   Config Settings   Errors  

The SOAPClient component sends SOAP messages.

Syntax

nsoftware.SecureBlackbox.SOAPClient

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

• C#
• VB.NET

public byte[] AttachmentBytes { get; set; }

Public Property AttachmentBytes As Byte()

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

• C#
• VB.NET

public string AttachmentFile { get; set; }

Public Property AttachmentFile As String

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.

AttachmentStream Property (SOAPClient Component)

A stream containing an attachment to be sent.

Syntax

• C#
• VB.NET

public System.IO.Stream AttachmentStream { get; set; }

Public Property AttachmentStream As System.IO.Stream

Default Value

null

Remarks

Use this property to provide an attachment to the component in a stream.

This property is not available at design time.

AuthTypes Property (SOAPClient Component)

Defines allowed HTTP authentication types.

Syntax

• C#
• VB.NET

public int AuthTypes { get; set; }

Public Property AuthTypes As Integer

Default Value

0

Remarks

Use this property to define which authentication types the component should support or attempt to use by enabling the relevant bitmask flags:

BlockedCertificates Property (SOAPClient 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.

ConnectionInfo Property (SOAPClient Component)

Returns the details of the underlying network connection.

Syntax

• C#
• VB.NET

public TLSConnectionInfo ConnectionInfo { get; }

Public ReadOnly Property ConnectionInfo As TLSConnectionInfo

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.

Encoding Property (SOAPClient Component)

Specifies SOAP message encoding.

Syntax

• C#
• VB.NET

public string Encoding { get; set; }

Public Property Encoding As String

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

• 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 the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

FaultActor Property (SOAPClient Component)

Specifies the entity that caused the fault.

Syntax

• C#
• VB.NET

public string FaultActor { get; }

Public ReadOnly Property FaultActor As String

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

• C#
• VB.NET

public string FaultCode { get; }

Public ReadOnly Property FaultCode As String

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

• C#
• VB.NET

public string FaultDetail { get; }

Public ReadOnly Property FaultDetail As String

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

• C#
• VB.NET

public string FaultString { get; }

Public ReadOnly Property FaultString As String

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

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

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 byte array form.

Syntax

• C#
• VB.NET

public byte[] InputBytes { get; set; }

Public Property InputBytes As Byte()

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

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

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

InputStream Property (SOAPClient Component)

A stream containing the SOAP message to be sent.

Syntax

• C#
• VB.NET

public System.IO.Stream InputStream { get; set; }

Public Property InputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to provide the SOAP message in a stream.

This property is not available at design time.

KeepAlivePolicy Property (SOAPClient Component)

Defines the keep-alive handling policy.

Syntax

• C#
• VB.NET

public SOAPClientKeepAlivePolicies KeepAlivePolicy { get; set; }

enum SOAPClientKeepAlivePolicies {
  ckapStandardDefined,
  ckapPreferKeepAlive,
  ckapRelyOnServer,
  ckapKeepAlivesDisabled
}

Public Property KeepAlivePolicy As SoapclientKeepAlivePolicies

Enum SOAPClientKeepAlivePolicies
  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 (SOAPClient 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 the certificates to be added to this collection is roughly equivalent to that of the 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 (SOAPClient 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 (SOAPClient 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.

MimeType Property (SOAPClient Component)

Specifies the SOAP message MIME type.

Syntax

• C#
• VB.NET

public string MimeType { get; set; }

Public Property MimeType As String

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

• C#
• VB.NET

public string OperationName { get; set; }

Public Property OperationName As String

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

• C#
• VB.NET

public string OperationNamespaceURI { get; set; }

Public Property OperationNamespaceURI As String

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

• C#
• VB.NET

public string OperationResponseName { get; }

Public ReadOnly Property OperationResponseName As String

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

• C#
• VB.NET

public string OperationResponseNamespaceURI { get; }

Public ReadOnly Property OperationResponseNamespaceURI As String

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

• C#
• VB.NET

public string OperationResponseTextContent { get; }

Public ReadOnly Property OperationResponseTextContent As String

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

• C#
• VB.NET

public string OperationResponseXML { get; }

Public ReadOnly Property OperationResponseXML As String

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

• C#
• VB.NET

public byte[] OutputAttachmentBytes { get; }

Public ReadOnly Property OutputAttachmentBytes As Byte()

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

• C#
• VB.NET

public string OutputAttachmentFile { get; set; }

Public Property OutputAttachmentFile As String

Default Value

""

Remarks

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

OutputAttachmentStream Property (SOAPClient Component)

A stream to write the attachment data to.

Syntax

• C#
• VB.NET

public System.IO.Stream OutputAttachmentStream { get; set; }

Public Property OutputAttachmentStream As System.IO.Stream

Default Value

null

Remarks

Use this property to pass the stream object to save the attachment data to.

This property is not available at design time.

OutputBytes Property (SOAPClient Component)

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

Syntax

• C#
• VB.NET

public byte[] OutputBytes { get; }

Public ReadOnly Property OutputBytes As Byte()

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the 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

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

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

OutputStream Property (SOAPClient Component)

A stream to write the response to.

Syntax

• C#
• VB.NET

public System.IO.Stream OutputStream { get; set; }

Public Property OutputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to pass the stream object to save the response content to.

This property is not available at design time.

Proxy Property (SOAPClient 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 (SOAPClient 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 (SOAPClient 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 (SOAPClient 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 (SOAPClient 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 (SOAPClient 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.

SOAPAction Property (SOAPClient Component)

Specifies the SOAP action.

Syntax

• C#
• VB.NET

public string SOAPAction { get; set; }

Public Property SOAPAction As String

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

• C#
• VB.NET

public SOAPClientSOAPResponseTypes SOAPResponseType { get; }

enum SOAPClientSOAPResponseTypes {
  srtUnknown,
  srtBinary,
  srtXMLDocument,
  srtSOAPMessage
}

Public ReadOnly Property SOAPResponseType As SoapclientSOAPResponseTypes

Enum SOAPClientSOAPResponseTypes
  srtUnknown
  srtBinary
  srtXMLDocument
  srtSOAPMessage
End Enum

Default Value

0

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

• C#
• VB.NET

public SOAPClientSOAPVersions SOAPVersion { get; set; }

enum SOAPClientSOAPVersions {
  spvAuto,
  spv11,
  spv12
}

Public Property SOAPVersion As SoapclientSOAPVersions

Enum SOAPClientSOAPVersions
  spvAuto
  spv11
  spv12
End Enum

Default Value

0

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

• 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 (SOAPClient 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.

TLSClientChain Property (SOAPClient Component)

The TLS client certificate chain.

Syntax

• C#
• VB.NET

public CertificateList TLSClientChain { get; }

Public Property TLSClientChain 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 the CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

TLSServerChain Property (SOAPClient Component)

The TLS server's certificate chain.

Syntax

• C#
• VB.NET

public CertificateList TLSServerChain { get; }

Public ReadOnly Property TLSServerChain As CertificateList

Remarks

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

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

TLSSettings Property (SOAPClient 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 (SOAPClient 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 as that of the 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.

Config Method (SOAPClient 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.

DoAction Method (SOAPClient 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 insensitive) 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;....

Common ActionIDs:

Reset Method (SOAPClient Component)

Resets the component settings.

Syntax

• C#
• VB.NET

public void Reset();

Public Sub Reset()

Remarks

Reset is a generic method available in every component.

SendMessage Method (SOAPClient Component)

Sends a SOAP message to the server.

Syntax

• C#
• VB.NET

public void SendMessage(string url);

Public Sub SendMessage(ByVal Url As 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

• C#
• VB.NET

public void SendMessageWithAttachments(string url, string primaryMessageId);

Public Sub SendMessageWithAttachments(ByVal Url As String, ByVal PrimaryMessageId As 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

• C#
• VB.NET

public event OnBeforeReceiveAttachmentHandler OnBeforeReceiveAttachment;

public delegate void OnBeforeReceiveAttachmentHandler(object sender, SOAPClientBeforeReceiveAttachmentEventArgs e);

public class SOAPClientBeforeReceiveAttachmentEventArgs : EventArgs {
}

Public Event OnBeforeReceiveAttachment As OnBeforeReceiveAttachmentHandler

Public Delegate Sub OnBeforeReceiveAttachmentHandler(sender As Object, e As SOAPClientBeforeReceiveAttachmentEventArgs)

Public Class SOAPClientBeforeReceiveAttachmentEventArgs Inherits EventArgs
End Class

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

• C#
• VB.NET

public event OnBeforeSendAttachmentHandler OnBeforeSendAttachment;

public delegate void OnBeforeSendAttachmentHandler(object sender, SOAPClientBeforeSendAttachmentEventArgs e);

public class SOAPClientBeforeSendAttachmentEventArgs : EventArgs {
  public bool LastAttachment { get; set; }
}

Public Event OnBeforeSendAttachment As OnBeforeSendAttachmentHandler

Public Delegate Sub OnBeforeSendAttachmentHandler(sender As Object, e As SOAPClientBeforeSendAttachmentEventArgs)

Public Class SOAPClientBeforeSendAttachmentEventArgs Inherits EventArgs
  Public Property LastAttachment As Boolean
End Class

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

• C#
• VB.NET

public event OnCookieHandler OnCookie;

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

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

Public Event OnCookie As OnCookieHandler

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

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

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

• C#
• VB.NET

public event OnDocumentBeginHandler OnDocumentBegin;

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

public class SOAPClientDocumentBeginEventArgs : EventArgs {
}

Public Event OnDocumentBegin As OnDocumentBeginHandler

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

Public Class SOAPClientDocumentBeginEventArgs 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 (SOAPClient 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, SOAPClientDocumentEndEventArgs e);

public class SOAPClientDocumentEndEventArgs : EventArgs {
}

Public Event OnDocumentEnd As OnDocumentEndHandler

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

Public Class SOAPClientDocumentEndEventArgs Inherits EventArgs
End Class

Remarks

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

Error Event (SOAPClient Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

Public Class SOAPClientErrorEventArgs 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 (SOAPClient 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, SOAPClientExternalSignEventArgs e);

public class SOAPClientExternalSignEventArgs : 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 SOAPClientExternalSignEventArgs)

Public Class SOAPClientExternalSignEventArgs 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 the 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 contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the 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 the .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

• C#
• VB.NET

public event OnHeadersPreparedHandler OnHeadersPrepared;

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

public class SOAPClientHeadersPreparedEventArgs : EventArgs {
}

Public Event OnHeadersPrepared As OnHeadersPreparedHandler

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

Public Class SOAPClientHeadersPreparedEventArgs 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 (SOAPClient 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, SOAPClientHeadersReceivedEventArgs e);

public class SOAPClientHeadersReceivedEventArgs : EventArgs {
}

Public Event OnHeadersReceived As OnHeadersReceivedHandler

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

Public Class SOAPClientHeadersReceivedEventArgs Inherits EventArgs
End Class

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

• C#
• VB.NET

public event OnNotificationHandler OnNotification;

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

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

Public Event OnNotification As OnNotificationHandler

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

Public Class SOAPClientNotificationEventArgs 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 the 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.

This component can fire this event with the following EventID values:

Progress Event (SOAPClient Component)

Fires periodically during the data transfer.

Syntax

• C#
• VB.NET

public event OnProgressHandler OnProgress;

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

public class SOAPClientProgressEventArgs : 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 SOAPClientProgressEventArgs)

Public Class SOAPClientProgressEventArgs 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 (SOAPClient Component)

Fires when the server suggests a redirect.

Syntax

• C#
• VB.NET

public event OnRedirectionHandler OnRedirection;

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

public class SOAPClientRedirectionEventArgs : 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 SOAPClientRedirectionEventArgs)

Public Class SOAPClientRedirectionEventArgs 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 (SOAPClient 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, SOAPClientTLSCertNeededEventArgs e);

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

Public Event OnTLSCertNeeded As OnTLSCertNeededHandler

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

Public Class SOAPClientTLSCertNeededEventArgs 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 parameter (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

• C#
• VB.NET

public event OnTLSCertValidateHandler OnTLSCertValidate;

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

public class SOAPClientTLSCertValidateEventArgs : 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 SOAPClientTLSCertValidateEventArgs)

Public Class SOAPClientTLSCertValidateEventArgs 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 the TLSServerChain property to access the certificate chain. In general, 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

• C#
• VB.NET

public event OnTLSEstablishedHandler OnTLSEstablished;

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

public class SOAPClientTLSEstablishedEventArgs : 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 SOAPClientTLSEstablishedEventArgs)

Public Class SOAPClientTLSEstablishedEventArgs 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 a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the 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

• C#
• VB.NET

public event OnTLSHandshakeHandler OnTLSHandshake;

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

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

Public Event OnTLSHandshake As OnTLSHandshakeHandler

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

Public Class SOAPClientTLSHandshakeEventArgs 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 by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSPSK Event (SOAPClient Component)

Notifies the application about the PSK key exchange.

Syntax

• C#
• VB.NET

public event OnTLSPSKHandler OnTLSPSK;

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

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

Public Event OnTLSPSK As OnTLSPSKHandler

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

Public Class SOAPClientTLSPSKEventArgs 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 (SOAPClient Component)

Reports the graceful closure of a TLS connection.

Syntax

• C#
• VB.NET

public event OnTLSShutdownHandler OnTLSShutdown;

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

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

Public Event OnTLSShutdown As OnTLSShutdownHandler

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

Public Class SOAPClientTLSShutdownEventArgs 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

Encapsulates an individual X.509 certificate.

Remarks

This type keeps and 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)

• 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)

• 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)

• C#
• VB.NET

public Certificate(string path, string password);

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

• 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)

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

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

• C#
• VB.NET

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

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

• 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)

• C#
• VB.NET

public Certificate();

Public Certificate()

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)

• C#
• VB.NET

public CRL(string location);

Public CRL(ByVal Location As String)

• C#
• VB.NET

public CRL(System.IO.Stream stream);

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

• C#
• VB.NET

public CRL();

Public CRL()

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

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

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

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 (CRLs).

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)

• C#
• VB.NET

public OCSPResponse(string location);

Public OCSPResponse(ByVal Location As String)

• C#
• VB.NET

public OCSPResponse(System.IO.Stream stream);

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

• C#
• VB.NET

public OCSPResponse();

Public OCSPResponse()

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

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

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)

• C#
• VB.NET

public StringNameValuePair();

Public StringNameValuePair()

TLSConnectionInfo 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