☰
Navigation :

SOAP-C Messages

Introduction

Any application may use SOAP-C-… messages to the SoapClientApp to request that an outbound SOAP/HTTP(S) request be made to an external SOAP/HTTP(S) Server.

The following applications from the core n2svcd module make requests to SoapClientApp.

The following LuaApp agents from the core n2svcd module use SoapClientApp.

The internal SOAP-C-… messages are:

Note that this page uses the term “on-the-wire” to refer to the sending or receiving of SOAP content by the SoapClientApp. This term is also inclusive of the case where the message is sent by local loopback and does not physically transit a Network Interface Controller (NIC).

SOAP-C-REQUEST

The SOAP-C-REQUEST message is sent to SoapClientApp by any application that wishes to perform an outbound SOAP request.

Refer to the SoapClientApp Configuration documentation for more information on setting default parameters.

The attributes of the SOAP-C-REQUEST message are:

Field Type Description
soap Object Container for the parameters of the SOAP request that we are to send.
.path String The URI path with which the request should be sent.
(Default = Path from action, or / root path)
.query String The URI query string (the part following "?" in the URI).
(Default = None)
.fragment String The URI fragment string (the part following "#" in the URI).
(Default = None)
.action String [Required] The fully-specified SOAP action for the SOAPAction HTTP header.
.message_name String [Required] The name of the SOAP method within the Body.
This should not include any namespace part.
.message_namespace Object A container for the message namespace information.
.uri String The message namespace URI, if one should be used.
.alias String The message namespace alias, if a URI is being used.
(Default = oper)
.location envelope/message The message namespace alias location, if a URI is being used.
(Default = As configured in the SoapClientApp)
.args Object User parameters to encode into the request message.
The encoding (and decoding of the response) will vary according to quirks_mode.
.http_headers Array of Objects Additional user-level header objects to apply to an outbound HTTP Request (see below for object structure).
These headers are added after any headers defined by static SoapClientApp application configuration.
You should not set the Content-Type or Content-Length headers.
(Default = No Additional Headers)

Note that it is not possible to set or override connection or SSL parameters in the SOAP-C-REQUEST message. Connection and SSL parameters can only be set in the SoapClientApp configuration.

Each object in the soap.http_headers Array for SOAP-C-REQUEST has the following structure.

Field Type Description
.name String [Required] The name of the HTTP Request header.
.value String [Required] The full string value of the HTTP Request header.
.replace 0 / 1 If 1 then all previous headers of this name are removed, and this header replaces them.
(Default = Append to the existing headers, do not replace)

SOAP-C-SENT

The SOAP-C-SENT message is sent by SoapClientApp to the requesting application when the original SOAP-C-REQUEST is placed on-the-wire.

The attributes of the SOAP-C-SENT message are:

Field Type Description
soap Object The SOAP parameters used to encode the final on-the-wire HTTP Request.
This Object has the same structure as the soap Object in SOAP-C-REQUEST.
Note however that this object will also contain any field values which were filled-in using default values configured within SoapClientApp itself.
http String The full HTTP Request message. This field may or may not be present.
The SoapClientApp may decide not to supply it in order to reduce traffic on the message bus.

Note that the on-the-wire HTTP Request is not returned in the SOAP-C-SENT. This is a decision made for efficiency, since these messages can be quite large.

SOAP-C-RESPONSE

The SOAP-C-RESPONSE message is sent by SoapClientApp to the requesting application when a HTTP Response is received to the original SOAP-C-REQUEST, or if a failure occurs which indicates that no HTTP Response will be received.

The attributes of the SOAP-C-RESPONSE message are:

Field Type Description
success 0/1 [Required] Indicates if the request was successful or not.
error String Indicates the reason why the request failed.
Present and applicable only if success == 0.
soap Object Container for the SOAP response parameters received.
Present only if success == 1.
.result_name String The name of the result message received.
This will exclude the namespace alias (if present).
.fault Object A container for the SOAP Fault contents, if a SOAP fault is present.
.code String The SOAP Fault faultcode/faultCode value.
.string String The SOAP Fault faultstring/faultString value.
.detail String The SOAP Fault detail value, if it is a simple scalar string.
Structured detail result values are not currently processed.
.result_namespace Object A container for the result namespace information.
These are not present in the case of a SOAP Fault.
.uri String The result namespace URI, if one was returned.
.location envelope/message Location of the result namespace URI, if one was used.
.args Object The decoded result attributes.
The decoding of the response will vary according to quirks_mode.
These are not present in the case of a SOAP Fault.
.code Integer The returned HTTP Response status code, e.g. `200`.
.content_type String The HTTP Response Content-Type header value which is always present for success.
.http_headers Array of Object The list of HTTP headers parsed from the HTTP Response (see below for object structure).
All HTTP headers are present, including Content-Length and Content-Type.
If a HTTP header was repeated in the HTTP Response, then it is repeated in this Array.

Each object in the soap.http_headers Array for SOAP-C-RESPONSE has the following structure.

Field Type Description
.name String [Required] The name of the HTTP Response header.
.value String [Required] The full string value of the HTTP Response header.