SOAPClient Class

Properties   Methods   Events   Config Settings   Errors  

The SOAPClient class sends SOAP messages.

Syntax

secureblackbox.SOAPClient

Remarks

The SOAPClient class 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 class with short descriptions. Click on the links for further details.

Method List

---

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

Event List

---

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

Config Settings

---

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

AttachmentBytes Property (SOAPClient Class)

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

Syntax

public byte[] getAttachmentBytes();


public void setAttachmentBytes(byte[] attachmentBytes);

Remarks

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

This property is not available at design time.

AttachmentFile Property (SOAPClient Class)

Specifies the attachment file to be sent with the request.

Syntax

public String getAttachmentFile();


public void setAttachmentFile(String attachmentFile);

Default Value

""

Remarks

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

Subscribe to BeforeSendAttachment to pass more than one attachment.

AttachmentStream Property (SOAPClient Class)

A stream containing an attachment to be sent.

Syntax

public java.io.InputStream getAttachmentStream();


public void setAttachmentStream(java.io.InputStream attachmentStream);

Default Value

null

Remarks

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

This property is not available at design time.

AuthTypes Property (SOAPClient Class)

Defines allowed HTTP authentication types.

Syntax

public int getAuthTypes();


public void setAuthTypes(int authTypes);

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

The certificates that must be rejected as trust anchors.

Syntax

public CertificateList getBlockedCertificates();


public void setBlockedCertificates(CertificateList blockedCertificates);

Remarks

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

This property is not available at design time.

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

ConnectionInfo Property (SOAPClient Class)

Returns the details of the underlying network connection.

Syntax

public TLSConnectionInfo getConnectionInfo();

Remarks

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

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

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

Encoding Property (SOAPClient Class)

Specifies SOAP message encoding.

Syntax

public String getEncoding();


public void setEncoding(String encoding);

Default Value

""

Remarks

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

ExternalCrypto Property (SOAPClient Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

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.

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

FaultActor Property (SOAPClient Class)

Specifies the entity that caused the fault.

Syntax

public String getFaultActor();

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

Specifies the error code.

Syntax

public String getFaultCode();

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

Contains application-specific error information.

Syntax

public String getFaultDetail();

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

Specifies a human-readable description of the fault.

Syntax

public String getFaultString();

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

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (SOAPClient Class)

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

Syntax

public byte[] getInputBytes();


public void setInputBytes(byte[] inputBytes);

Remarks

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

This property is not available at design time.

InputFile Property (SOAPClient Class)

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

Syntax

public String getInputFile();


public void setInputFile(String inputFile);

Default Value

""

Remarks

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

InputStream Property (SOAPClient Class)

A stream containing the SOAP message to be sent.

Syntax

public java.io.InputStream getInputStream();


public void setInputStream(java.io.InputStream inputStream);

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

Defines the keep-alive handling policy.

Syntax

public int getKeepAlivePolicy();


public void setKeepAlivePolicy(int keepAlivePolicy);


Enumerated values:
  public final static int ckapStandardDefined = 0;
  public final static int ckapPreferKeepAlive = 1;
  public final static int ckapRelyOnServer = 2;
  public final static int ckapKeepAlivesDisabled = 3;

Default Value

0

Remarks

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

KnownCertificates Property (SOAPClient Class)

Additional certificates for chain validation.

Syntax

public CertificateList getKnownCertificates();


public void setKnownCertificates(CertificateList knownCertificates);

Remarks

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

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

KnownCRLs Property (SOAPClient Class)

Additional CRLs for chain validation.

Syntax

public CRLList getKnownCRLs();


public void setKnownCRLs(CRLList knownCRLs);

Remarks

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

This property is not available at design time.

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

KnownOCSPs Property (SOAPClient Class)

Additional OCSP responses for chain validation.

Syntax

public OCSPResponseList getKnownOCSPs();


public void setKnownOCSPs(OCSPResponseList knownOCSPs);

Remarks

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

This property is not available at design time.

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

MimeType Property (SOAPClient Class)

Specifies the SOAP message MIME type.

Syntax

public String getMimeType();


public void setMimeType(String mimeType);

Default Value

""

Remarks

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

OperationName Property (SOAPClient Class)

Specifies the SOAP operation name.

Syntax

public String getOperationName();


public void setOperationName(String operationName);

Default Value

""

Remarks

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

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

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

OperationNamespaceURI Property (SOAPClient Class)

Specifies the SOAP message operation namespace URI.

Syntax

public String getOperationNamespaceURI();


public void setOperationNamespaceURI(String operationNamespaceURI);

Default Value

""

Remarks

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

OperationResponseName Property (SOAPClient Class)

Specifies the operation name of the response message.

Syntax

public String getOperationResponseName();

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

Specifies the response SOAP message operation namespace URI.

Syntax

public String getOperationResponseNamespaceURI();

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

Returns the text content of the response message.

Syntax

public String getOperationResponseTextContent();

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

Returns the XML content of the response SOAP message.

Syntax

public String getOperationResponseXML();

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

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

Syntax

public byte[] getOutputAttachmentBytes();

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

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

Syntax

public String getOutputAttachmentFile();


public void setOutputAttachmentFile(String outputAttachmentFile);

Default Value

""

Remarks

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

OutputAttachmentStream Property (SOAPClient Class)

A stream to write the attachment data to.

Syntax

public java.io.OutputStream getOutputAttachmentStream();


public void setOutputAttachmentStream(java.io.OutputStream outputAttachmentStream);

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

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

Syntax

public byte[] getOutputBytes();

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

A file where the response will be saved.

Syntax

public String getOutputFile();


public void setOutputFile(String outputFile);

Default Value

""

Remarks

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

OutputStream Property (SOAPClient Class)

A stream to write the response to.

Syntax

public java.io.OutputStream getOutputStream();


public void setOutputStream(java.io.OutputStream outputStream);

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

The proxy server settings.

Syntax

public ProxySettings getProxy();

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

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

ReasonPhrase Property (SOAPClient Class)

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

Syntax

public String getReasonPhrase();

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

Contains HTTP request headers.

Syntax

public StringNameValuePairList getRequestHeaders();

Remarks

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

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

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

RequestParameters Property (SOAPClient Class)

Provides access to common HTTP request properties.

Syntax

public HTTPRequestParameters getRequestParameters();


public void setRequestParameters(HTTPRequestParameters requestParameters);

Remarks

Use this property to configure the HTTP request properties.

This property is not available at design time.

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

ResponseHeaders Property (SOAPClient Class)

Contains the HTTP server's response headers.

Syntax

public StringNameValuePairList getResponseHeaders();

Remarks

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

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

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

ResponseParameters Property (SOAPClient Class)

Contains the HTTP server's response parameters.

Syntax

public HTTPResponseParameters getResponseParameters();

Remarks

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

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

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

SOAPAction Property (SOAPClient Class)

Specifies the SOAP action.

Syntax

public String getSOAPAction();


public void setSOAPAction(String SOAPAction);

Default Value

""

Remarks

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

SOAPResponseType Property (SOAPClient Class)

The type of the response.

Syntax

public int getSOAPResponseType();



Enumerated values:
  public final static int srtUnknown = 0;
  public final static int srtBinary = 1;
  public final static int srtXMLDocument = 2;
  public final static int srtSOAPMessage = 3;

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

Specifies SOAP version.

Syntax

public int getSOAPVersion();


public void setSOAPVersion(int SOAPVersion);


Enumerated values:
  public final static int spvAuto = 0;
  public final static int spv11 = 1;
  public final static int spv12 = 2;

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

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

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

StatusCode Property (SOAPClient Class)

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

Syntax

public int getStatusCode();

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

The TLS client certificate chain.

Syntax

public CertificateList getTLSClientChain();


public void setTLSClientChain(CertificateList TLSClientChain);

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the class. 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.

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

TLSServerChain Property (SOAPClient Class)

The TLS server's certificate chain.

Syntax

public CertificateList getTLSServerChain();

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.

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

TLSSettings Property (SOAPClient Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

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

TrustedCertificates Property (SOAPClient Class)

A list of trusted certificates for chain validation.

Syntax

public CertificateList getTrustedCertificates();


public void setTrustedCertificates(CertificateList trustedCertificates);

Remarks

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

The purpose of this certificate collection is largely the same 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.

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

Config Method (SOAPClient Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. 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;....

Reset Method (SOAPClient Class)

Resets the class settings.

Syntax

public void reset();

Remarks

Reset is a generic method available in every class.

SendMessage Method (SOAPClient Class)

Sends a SOAP message to the server.

Syntax

public void sendMessage(String url);

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

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

Syntax

public void sendMessageWithAttachments(String url, String primaryMessageId);

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

Marks the start of receiving an attachment.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void beforeReceiveAttachment(SOAPClientBeforeReceiveAttachmentEvent e) {}
  ...
}

public class SOAPClientBeforeReceiveAttachmentEvent {
}

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

Marks the start of sending an attachment.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void beforeSendAttachment(SOAPClientBeforeSendAttachmentEvent e) {}
  ...
}

public class SOAPClientBeforeSendAttachmentEvent {
  public boolean lastAttachment; //read-write
}

Remarks

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

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

Cookie Event (SOAPClient Class)

Fired to report a received cookie.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void cookie(SOAPClientCookieEvent e) {}
  ...
}

public class SOAPClientCookieEvent {
  public String cookieText;
}

Remarks

The CookieText parameter contains the text of the cookie.

DocumentBegin Event (SOAPClient Class)

Marks the start of the incoming HTML document or file.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void documentBegin(SOAPClientDocumentBeginEvent e) {}
  ...
}

public class SOAPClientDocumentBeginEvent {
}

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

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void documentEnd(SOAPClientDocumentEndEvent e) {}
  ...
}

public class SOAPClientDocumentEndEvent {
}

Remarks

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

Error Event (SOAPClient Class)

Information about errors during data delivery.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void error(SOAPClientErrorEvent e) {}
  ...
}

public class SOAPClientErrorEvent {
  public int errorCode;
  public String description;
}

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

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void externalSign(SOAPClientExternalSignEvent e) {}
  ...
}

public class SOAPClientExternalSignEvent {
  public String operationId;
  public String hashAlgorithm;
  public String pars;
  public String data;
  public String signedData; //read-write
}

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 class via the SignedData parameter.

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

The class 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 Class)

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void headersPrepared(SOAPClientHeadersPreparedEvent e) {}
  ...
}

public class SOAPClientHeadersPreparedEvent {
}

Remarks

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

HeadersReceived Event (SOAPClient Class)

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void headersReceived(SOAPClientHeadersReceivedEvent e) {}
  ...
}

public class SOAPClientHeadersReceivedEvent {
}

Remarks

The received headers are available via the ResponseHeaders property.

Notification Event (SOAPClient Class)

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void notification(SOAPClientNotificationEvent e) {}
  ...
}

public class SOAPClientNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. 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 class, the exact action it is performing, or the document being processed, one or both may be omitted.

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

Progress Event (SOAPClient Class)

Fires periodically during the data transfer.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void progress(SOAPClientProgressEvent e) {}
  ...
}

public class SOAPClientProgressEvent {
  public long total;
  public long current;
  public boolean cancel; //read-write
}

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

Fires when the server suggests a redirect.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void redirection(SOAPClientRedirectionEvent e) {}
  ...
}

public class SOAPClientRedirectionEvent {
  public String oldURL;
  public String newURL; //read-write
  public boolean allowRedirection; //read-write
}

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

Fires when a remote TLS party requests a client certificate.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void TLSCertNeeded(SOAPClientTLSCertNeededEvent e) {}
  ...
}

public class SOAPClientTLSCertNeededEvent {
  public String host;
  public String CANames;
}

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

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void TLSCertValidate(SOAPClientTLSCertValidateEvent e) {}
  ...
}

public class SOAPClientTLSCertValidateEvent {
  public String serverHost;
  public String serverIP;
  public boolean accept; //read-write
}

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, classes 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 class, and can be adjusted if needed.

TLSEstablished Event (SOAPClient Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void TLSEstablished(SOAPClientTLSEstablishedEvent e) {}
  ...
}

public class SOAPClientTLSEstablishedEvent {
  public String host;
  public String version;
  public String ciphersuite;
  public byte[] connectionId;
  public boolean abort; //read-write
}

Remarks

The class 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 Class)

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

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void TLSHandshake(SOAPClientTLSHandshakeEvent e) {}
  ...
}

public class SOAPClientTLSHandshakeEvent {
  public String host;
  public boolean abort; //read-write
}

Remarks

The class 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 Class)

Notifies the application about the PSK key exchange.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void TLSPSK(SOAPClientTLSPSKEvent e) {}
  ...
}

public class SOAPClientTLSPSKEvent {
  public String host;
  public String hint;
}

Remarks

The class 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 Class)

Reports the graceful closure of a TLS connection.

Syntax

public class DefaultSOAPClientEventListener implements SOAPClientEventListener {
  ...
  public void TLSShutdown(SOAPClientTLSShutdownEvent e) {}
  ...
}

public class SOAPClientTLSShutdownEvent {
  public String host;
}

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

public Certificate( bytes,  startIndex,  count,  password);

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

public Certificate( bytes,  startIndex,  count);

public Certificate( path,  password);

public Certificate( certPath,  keyPath,  password);

public Certificate( path);

public Certificate( stream);

public Certificate( stream,  password);

public Certificate( certStream,  keyStream,  password);

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

public CRL( bytes,  startIndex,  count);

public CRL( location);

public CRL( stream);

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

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 class.

Fields

Constructors

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

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

public OCSPResponse( bytes,  startIndex,  count);

public OCSPResponse( location);

public OCSPResponse( stream);

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

public ProxySettings();

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

public SocketSettings();

StringNameValuePair Type

A simple name-value pair object.

Remarks

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

Fields

Constructors

public StringNameValuePair( name,  value);

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

Constructors

public TLSConnectionInfo();

TLSSettings Type

A container for TLS connection settings.

Remarks

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

Fields

Constructors

public TLSSettings();

Config Settings (SOAPClient Class)

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

HTTPClient Config Settings

Base Config Settings

Trappable Errors (SOAPClient Class)

SOAPClient Errors