<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<refentry id="fn_soap_client">
  <refmeta>
    <refentrytitle>soap_client</refentrytitle>
    <refmiscinfo>soap</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>soap_client</refname>
    <refpurpose>Invoke a SOAP service and returns result value.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis id="fsyn_soap_client">
      <funcprototype id="fproto_soap_client">
        <funcdef><function>soap_client</function></funcdef>
	<paramdef>in <parameter>url</parameter> varchar</paramdef>
	<paramdef>in <parameter>operation</parameter> varchar</paramdef>
	<paramdef>in <parameter>target_namespace</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>parameters</parameter> any default null</paramdef>
	<paramdef>in <parameter>headers</parameter> any default null</paramdef>
	<paramdef>in <parameter>soap_action</parameter> varchar default ''</paramdef>
	<paramdef>in <parameter>attachments</parameter> any default null</paramdef>
	<paramdef>in <parameter>ticket</parameter> any default null</paramdef>
	<paramdef>in <parameter>passwd</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>user_name</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>user_password</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>auth_type</parameter> varchar default 'none'</paramdef>
	<paramdef>in <parameter>security_type</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>debug</parameter> integer default 0</paramdef>
	<paramdef>in <parameter>template</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>style</parameter> integer default 0</paramdef>
	<paramdef>in <parameter>version</parameter> integer default 11</paramdef>
	<paramdef>in <parameter>direction</parameter> integer default 0</paramdef>
	<paramdef>in <parameter>http_header</parameter> varchar default null</paramdef>
	<paramdef>in <parameter>security_schema</parameter> any default null</paramdef>
	<paramdef>in <parameter>time_out</parameter> int default 100</paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="desc_soap_client">
    <title>Description</title>
    <para>This will invoke the specified SOAP service.
    </para>
  </refsect1>
  <refsect1 id="params_soap_client">
    <title>Parameters</title>
    <refsect2><title>url</title>
	<para>The target SOAP service endpoint URL. For SSL connections
	    this must begin with 'https:' schema.
	</para>
    </refsect2>
    <refsect2><title>operation</title>
      <para>The name of the SOAP method to be invoked.</para>
    </refsect2>
    <refsect2><title>target_namespace</title>
      <para>The namespace of the SOAP request.</para>
    </refsect2>
    <refsect2><title>parameters</title>
      <para>parameters contained inside a vector in one of two ways:</para>
      <para>vector ("name", "value" ....)</para>
	    <para>or</para>
	    <para>vector (vector ("name", "type") , "value" ....)</para>
	    <para>
		The second way is used when parameters are complex datatypes,
		or in other words "value" datatype will be validated and encoded following
		rules for "type" specified. This means that string "value" for example
		could not be passed and error will be generated if "type" is specified to be
		'int' for example. Also this is a way to pass user defined XSD types to SOAP
		server.
	    </para>
    </refsect2>
    <refsect2><title>headers</title>
      <para>the parameters to be printed in SOAP header element. They are contained inside a vector in following way:</para>
  	  <para>vector (vector ("name", "type", [mustUnderstand-0/1], [SOAP:actor attribute value]) , "value" ....)</para>
	  <para>The mustUnderstand and actor value may be omitted.
	      Also in the case of special type '__XML__' the
	      parameter value will be expected to be an XML entity,
	      hence in that way we can put in a Header any content.
      </para>
      <para>
	  The rules for datatype of "value" are same as for 'parameters' parameter (see above).
      </para>
    </refsect2>
    <refsect2><title>soap_action</title>
	<para>The exact value of the SOAPAction header attribute.</para>
    </refsect2>
    <refsect2><title>attachments</title>
      <para>DIME/MIME message attachments as array of (id, type, content)</para>
    </refsect2>
    <refsect2><title>ticket</title>
	<para>The key instance to perform XML signature and encryption for outgoing SOAP message.
	    Or path to PKCS#12 file containing x509 certificate
	    to perform secure connection over SSL with server's certificate verification.
	    To indicate to use SSL for connection encryption only,
	    then a number as string greater than 0 must be specified (i.e. '1').
	</para>
    </refsect2>
    <refsect2><title>passwd</title>
	<para>The password for opening the x509 certificate specified in 'ticket'.</para>
    </refsect2>
    <refsect2><title>user_name</title>
      <para>name for basic/digest HTTP authentication.</para>
    </refsect2>
    <refsect2><title>user_password</title>
      <para>The password for basic/digest HTTP authentication.</para>
    </refsect2>
    <refsect2><title>auth_type</title>
      <para>The type of authentication to use. Valid types are:</para>
      <simplelist>
       <member><emphasis>none</emphasis> do not perform authentication or encryption.  Default.</member>
       <member><emphasis>digest</emphasis> perform digest HTTP authentication.</member>
       <member><emphasis>basic</emphasis> perform basic HTTP authentication.</member>
       <member><emphasis>key</emphasis> encrypt/and sign the message.</member>
       <member><emphasis>x509</emphasis> sign the message using x509 certificate.</member>
      </simplelist>
    </refsect2>
    <refsect2><title>security_type</title>
      <para>This parameter governs the security method of the outgoing
      messages.  Valid values are "encrypt" or "sign", to encrypt the message
      or sign it only.</para>
    </refsect2>
    <refsect2><title>debug</title>
      <para>If this flag is set to 1 then debug mode will be enabled.  When
      enabled the returned message will be an array of 3 elements consisting of
      the request, response, and error if one occurred.</para>
    </refsect2>
    <refsect2><title>template</title>
      <para>The content of an XML signature template.  If the default template
      is to be used only "[key reference for signing]" (note '[]' around name).
      need be specified.  The server will generate a default template
      based on the key and default rules for making a signature.</para>
    </refsect2>
    <refsect2><title>style</title>
      <para>This is a bit-mask parameter that is used to specify the outgoing
      message format.  The mask relies on the following values:</para>
      <itemizedlist>
       <listitem><emphasis>0</emphasis> RPC-encoded SOAP message</listitem>
       <listitem><emphasis>1</emphasis> Document/Literal (free-form) encoded SOAP message</listitem>
       <listitem><emphasis>4</emphasis> Document/Literal encoded SOAP message with wrapped parameters </listitem>
       <listitem><emphasis>8</emphasis> outgoing message will be DIME encoded</listitem>

       <listitem><emphasis>0x10</emphasis> element form default, if supplied the Document/Literal with wrapped parameters outgoing message will be qualified. applicable to Document/Literal encoded SOAP messages only.</listitem>
       <listitem><emphasis>0x20</emphasis> SOAP to XML-RPC translation filter</listitem>
       <listitem><emphasis>0x40</emphasis> return parsed SOAP response Envelope</listitem>
       <listitem><emphasis>0x80</emphasis> do not signal of SOAP Fault response, return fault as result</listitem>
       <listitem><emphasis>0x100</emphasis> do not send response to server, just return the request to be sent</listitem>
       <listitem><emphasis>0x200</emphasis> outgoing message will be MIME encoded</listitem>

       <listitem><para><emphasis>2</emphasis>advanced mode : output will consist of vector of 5 items as:</para>
        <simplelist>
	    <member>parsed response - XML tree of the SOAP response</member>
         <member>outgoing message (wire dump) - string representing the SOAP request</member>
         <member>incoming message - string representing the SOAP response from server</member>
	 <member>error if any - a vector of code, SQL code and SQL message describing the error</member>
         <member>attachments if any - an array of SOAP attachments, structure is same as for 'attachments' parameter.</member>
        </simplelist>
       </listitem>
      </itemizedlist>
    </refsect2>
    <refsect2><title>version</title>
	<para>the SOAP version used in call (SOAP 1.0 = 1, SOAP 1.1 = 11, SOAP 1.2 = 12).
	    Default value = SOAP 1.1.
	</para>
    </refsect2>
    <refsect2><title>direction</title>
	<para>This flag if turned on (1) then one-way messages will be sent.
	    In that case client doesn't expect response from SOAP server, except
	    HTTP headers.
       	</para>
    </refsect2>
    <refsect2><title>http_header</title>
	<para>This parameter is used to include custom HTTP headers in the SOAP POST request.
	    The usual purpose of it to pass special 'X-&lt;extension name&gt;' header to
	    server in order to send data that can't be included in SOAP message.  For example
            this could be used for loop-to-self detection when replicating
	    data collection(s) via SOAP.
	</para>
    </refsect2>
    <refsect2><title>security_schema</title>
	<para>This parameter is used to designate version of WS-Security and WS-Utility
	    protocol to be used when secure SOAP calls will be made.
	    The value is an array containing name/value pairs for 'wsse' (WS-Security) and 'wsu' (WS-Utility)
	    namespace URLs. An example of the value is: vector ('wsse', WSSE_OASIS_URI, 'wsu', WSSU_OASIS_URI).
	</para>
    </refsect2>
    <refsect2><title>time_out</title>
	<para>The connection timeout. Elapsing this value and having no response from server
	    will cause client to disconnect with an connection error.</para>
    </refsect2>
  </refsect1>
  <refsect1 id="ret_soap_client"><title>Return Types</title>
      <para>The function will return a XML tree of the SOAP response in simple mode.
	  Also if one-way message is sent and no body from the SOAP server,
	  then NULL will be returned.
	  When advanced mode is set i.e. 'style' have second bit set, then response
	  will be as described earlier in 'style' parameter description.
      </para>
  </refsect1>
  <!--
  <refsect1 id="errors_soap_client">
    <title>Errors</title>
    <para>This function can generate the following errors:</para>
    <errorcode></errorcode>
  </refsect1>
  -->
  <refsect1 id="ssl_soap_client"><title>Requirements for certificate files for HTTPS operation</title>
      <para>When users going to do operation with an HTTPS endpoint the
	  following are requirements to the PKCS#12 file.
	  The file specified in parameter 'ticket' MUST contain: valid x509 certificate,
	  certificate chain and private key. The password for opening the private key
	  must be specified in the 'passwd' parameter.
	  How client and server certificates and private keys are created
	  are not subject of this document.
	  Also see Web server documentation about how to run an HTTPS listener.
      </para>
  </refsect1>
  <refsect1 id="examples_soap_client">
    <title>Example</title>
    <example id="ex_soap_client"><title></title>
     <para>References: tutorial/services WS-S-2 (triple-des),
     WS-S-3 (RSA), WS-S-4 (X.509 signing)</para>
     <para>The following is an excerpt from the WS-S-2 Services tutorial
     to make encoded SOAP message with a shared key.</para>

<programlisting><![CDATA[
resp :=
	SOAP_CLIENT (
	  url=>'http://example.com/SecureWebServices',
	  operation=>'AddInt',
	  parameters=>vector (vector ('a', 'int'), 3, vector ('b', 'int'), 4),
	  auth_type=>'key',
	  ticket=>xenc_key_inst_create ('WSDK Sample Symmetric Key'),
	  security_type=>'encrypt',
	  target_namespace=>'http://temp.uri/',
	  soap_action=>'"http://temp.uri/#AddInt"',
	  style=>6);
]]></programlisting>

<para>This will produce following SOAP message:</para>

<para>The encoded SOAP request</para>
<programlisting><![CDATA[
------------ REQUEST ------------------
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"
          encodingType="http://schemas.xmlsoap.org/soap/encoding/" >
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/" >
    <Security xmlns="http://schemas.xmlsoap.org/ws/2002/07/secext" >
      <ReferenceList xmlns="http://www.w3.org/2001/04/xmlenc#" >
        <DataReference xmlns="http://www.w3.org/2001/04/xmlenc#"
         URI="#Id-6831bf5c-f4dc-d611-bb59-90b4c67d3be5" />
      </ReferenceList>
    </Security>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
      <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#"
                   Type="http://www.w3.org/2001/04/xmlenc#Content"
		   Id="Id-6831bf5c-f4dc-d611-bb59-90b4c67d3be5" >
      <EncryptionMethod xmlns="http://www.w3.org/2001/04/xmlenc#"
                      Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" />
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#" >
         <KeyName xmlns="http://www.w3.org/2000/09/xmldsig#" >WSDK Sample Symmetric Key</KeyName>
      </KeyInfo>
      <CipherData xmlns="http://www.w3.org/2001/04/xmlenc#" >
        <CipherValue xmlns="http://www.w3.org/2001/04/xmlenc#" >s8YHzbGSxsgfslN6
        eJu7UeiTExKeqwCHrqFml24C6mY8SLxhNE0Vy6xBuS50uchjbupjE4Z8EtkSuyljR8mkpmrW
        GCfUQEvrW7iu1ji0j4XR7m5P4dgxh7RYwqxqoprwTnCZ9b6X9D/UpN0aAYVdNs+S6l2Rw56d
        s5Gf4sv2f/sTYpEHTYPReqyo+9LSm9CsbtlPXia9djkH+75PUtsKZXZvHnVfHICQGjBJPpsh
        eE7Dq7mt8AkKVQ==</CipherValue>
       </CipherData>
    </EncryptedData>
  </Body>
</Envelope>
---------------------------------------
]]></programlisting>

<para>Server approves the request and returns an unencrypted message.
This shows one-way encoding only.</para>

<programlisting><![CDATA[
------------ RESPONSE -----------------
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" >
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/" >
    <AddIntResponse xmlns="http://temp.uri/" >
      <CallReturn type="http://www.w3.org/2001/XMLSchema:int" >7</CallReturn>
    </AddIntResponse>
  </Body>
</Envelope>
---------------------------------------
]]></programlisting>
</example>

    <example id="ex_soapheader_client"><title>Adding a SOAP:Header</title>
     <para>This example makes call to the interop round4 test echoVoidSoapHeader (exists in the demo DB).
     Request and response wire dumps are listed below PL code excerpt.
     </para>
<programlisting><![CDATA[
     ...
     resp := soap_client (url=>url, operation=>'echoVoidSoapHeader',
		          parameters=>vector(),
 	                  headers=>vector(
			    vector('echoMeStringRequest',
			           'http://soapinterop.org/:echoMeStringRequest',
				   1,
				   'http://schemas.xmlsoap.org/soap/actor/next') ,
		                   vector('String')),
 		          style=>7,
			  soap_action=>'"http://soapinterop.org"',
			  target_namespace=>'http://soapinterop.org'
			  );
     ...

]]></programlisting>
<para>This will produce the following SOAP message:</para>

<para>The SOAP request</para>
<programlisting><![CDATA[
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ns1="http://soapinterop.org/echoheader/"
 xmlns:ns0="http://soapinterop.org/">
   <SOAP:Header>
     <ns0:echoMeStringRequest SOAP:mustUnderstand='1' SOAP:actor='http://schemas.xmlsoap.org/soap/actor/next'>
       <ns1:varString>String</ns1:varString>
     </ns0:echoMeStringRequest>
   </SOAP:Header>
   <SOAP:Body>
     <echoVoidSoapHeader xmlns='http://soapinterop.org' ></echoVoidSoapHeader>
   </SOAP:Body>
</SOAP:Envelope>
]]></programlisting>
<para>And will receive the SOAP server response:</para>
<programlisting><![CDATA[
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns2="http://soapinterop.org/echoheader/"
  xmlns:ns1="http://soapinterop.org/"
  xmlns:ns0="http://soapinterop.org">
  <SOAP:Header>
    <ns1:echoMeStringResponse>
      <ns2:varString>String</ns2:varString>
    </ns1:echoMeStringResponse>
  </SOAP:Header>
  <SOAP:Body>
    <ns1:echoVoidSoapHeaderResponse />
  </SOAP:Body>
</SOAP:Envelope>
]]></programlisting>
     </example>

    <example id="ex_soapssl_client"><title>Performing SOAP call over secure connection</title>
	<para>
	    The example code below makes a simple 'upper-case' service, exposes it under
	    secured endpoint and invoke with x509 certificate.
	    Note that default HTTPS listener MUST be enable in the INI file.
	    Also the cli5.p12 certificate file MUST exists in server working directory.
     </para>
     <programlisting><![CDATA[
SQL> create procedure
  WS.SOAPDEMO.SOAPTEST (in par varchar)
{
  return (upper(par));
};

SQL> grant execute on WS.SOAPDEMO.SOAPTEST to SOAPDEMO;

SQL> VHOST_DEFINE (vhost=>'*sslini*',lhost=>'*sslini*',lpath=>'/secure',
 ppath=>'/SOAP/',soap_user=>'SOAPDEMO');

-- SSL connection with server's certificate verification
SQL> select xpath_eval ('//CallReturn/text()', xml_tree_doc (
 	soap_client (url=>'https://localhost:4443/secure',
	operation=>'SOAPTEST', parameters=>vector('par', 'demotext'),
	ticket=>'cli5.p12', passwd=>'secret')));
-- SSL connection only, no certificate verification
SQL> select xpath_eval ('//CallReturn/text()', xml_tree_doc (
 	soap_client (url=>'https://localhost:4443/secure',
	operation=>'SOAPTEST', parameters=>vector('par', 'demotext'),
	ticket=>'1')));
-- response
callret
VARCHAR
_______________________________________________________________________________

DEMOTEXT


]]></programlisting>
     </example>

  </refsect1>
  <refsect1 id="seealso_soap_client">
    <title>See Also</title>
    <para><link linkend="vwsssectemplates">Signature Templates</link></para>
  </refsect1>
</refentry>