.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SOAP::WSDL::Client 3pm"
.TH SOAP::WSDL::Client 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SOAP::WSDL::Client \- SOAP::WSDL's SOAP Client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& use SOAP::WSDL::Client;
\& my $soap = SOAP::WSDL::Client\->new({
\&     proxy => \*(Aqhttp://www.example.org/webservice/test\*(Aq
\& });
\& $soap\->call( \e%method, $body, $header);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "call"
.IX Subsection "call"
.Vb 1
\& $soap\->call( \e%method, \e@parts );
.Ve
.PP
\&\f(CW%method\fR is a hash with the following keys:
.PP
.Vb 6
\& Name           Description
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& operation      operation name
\& soap_action    SOAPAction HTTP header to use
\& style          Operation style. One of (document|rpc)
\& use            SOAP body encoding. One of (literal|encoded)
.Ve
.PP
The style and use keys have no influence yet.
.PP
\&\f(CW@parts\fR is a list containing the elements of the message parts.
.PP
For backward compatibility, call may also be called as below:
.PP
.Vb 1
\& $soap\->call( $method, \e@parts );
.Ve
.PP
In this case, \f(CW$method\fR is the \s-1SOAP\s0 operation name, and the SOAPAction header
is guessed from the first part's namespace and the operation name (which is
mostly correct, but may fail). Operation style and body encoding are assumed to
be document/literal
.SS "Configuration methods"
.IX Subsection "Configuration methods"
\fIoutputxml\fR
.IX Subsection "outputxml"
.PP
.Vb 1
\& $soap\->outputxml(1);
.Ve
.PP
When set, \fBcall()\fR returns the raw \s-1XML\s0 of the \s-1SOAP\s0 Envelope.
.PP
\fIset_content_type\fR
.IX Subsection "set_content_type"
.PP
.Vb 1
\& $soap\->set_content_type(\*(Aqapplication/xml; charset: utf8\*(Aq);
.Ve
.PP
Sets the content type and character encoding.
.PP
You probably should not use a character encoding different from utf8:
SOAP::WSDL::Client will not convert the request into a different encoding
(yet).
.PP
To leave out the encoding, just set the content type without appending charset
like this:
.PP
.Vb 1
\&  $soap\->set_content_type(\*(Aqtext/xml\*(Aq);
.Ve
.PP
Default:
.PP
.Vb 1
\& text/xml; charset: utf8
.Ve
.PP
\fIset_prefix\fR
.IX Subsection "set_prefix"
.PP
.Vb 1
\& $soap\->set_prefix(\*(Aqns2\*(Aq);
.Ve
.PP
If set, alters the serialization of the request \s-1XML\s0 such that the supplied value is used as a namespace prefix for \s-1SOAP\s0 method calls. By way of example, the default \s-1XML\s0 serialization returns something like this:
.PP
.Vb 10
\&    <?xml version="1.0"?>
\&    <SOAP\-ENV:Envelope
\&        xmlns:xsi="http://www.w3.org/2001/XMLSchema\-instance"
\&        xmlns:SOAP\-ENV="http://schemas.xmlsoap.org/soap/envelope/">
\&      <SOAP\-ENV:Body>
\&        <getElementId xmlns="http://services.exmaple.org/">
\&          <elementId>12345</elementId>
\&        </getElementId>
\&      </SOAP\-ENV:Body>
\&    </SOAP\-ENV:Envelope>
.Ve
.PP
If the sample \fBset_prefix()\fR call above is used prior to calling your \s-1SOAP\s0 method, the \s-1XML\s0 serialization returns this instead:
.PP
.Vb 11
\&    <?xml version="1.0"?>
\&    <SOAP\-ENV:Envelope
\&        xmlns:xsi="http://www.w3.org/2001/XMLSchema\-instance"
\&        xmlns:SOAP\-ENV="http://schemas.xmlsoap.org/soap/envelope/"
\&        xmlns:ns2="http://services.example.org/">
\&      <SOAP\-ENV:Body>
\&        <ns2:getElementId>
\&          <elementId>12345</elementId>
\&        </ns2:getElementId>
\&      </SOAP\-ENV:Body>
\&    </SOAP\-ENV:Envelope>
.Ve
.PP
This is useful in cases where, for instance, one is communicating with a \s-1JAX\s0 <https://jax\-ws.dev.java.net/> webservice, which tends to understand the latter but not the former. Note that this implementation is currently limited to a single additional namespace; if you require multiple custom namespaces, you should probably look into creating your own serializer.
.SS "Features different from SOAP::Lite"
.IX Subsection "Features different from SOAP::Lite"
\&\s-1SOAP::WSDL\s0 does not aim to be a complete replacement for SOAP::Lite \- the
SOAP::Lite module has its strengths and weaknesses and \s-1SOAP::WSDL\s0 is
designed as a cure for the weakness of little \s-1WSDL\s0 support \- nothing more,
nothing less.
.PP
Nonetheless \s-1SOAP::WSDL\s0 mimics part of SOAP::Lite's \s-1API\s0 and behaviour,
so SOAP::Lite users can switch without looking up every method call in the
documentation.
.PP
A few things are quite different from SOAP::Lite, though:
.PP
\fI\s-1SOAP\s0 request data\fR
.IX Subsection "SOAP request data"
.PP
\&\s-1SOAP\s0 request data may either be given as message object, or as a hash ref (in
which case it will automatically be encoded into a message object).
.PP
\fIReturn values\fR
.IX Subsection "Return values"
.PP
The result from \fBcall()\fR is not a \s-1SOAP::SOM\s0 object, but a message object.
.PP
Message objects' classes may be generated from \s-1WSDL\s0 definitions automatically
\&\- see SOAP::WSDL::Generator::Typelib on how to generate your own \s-1WSDL\s0 based
message class library.
.PP
\fIFault handling\fR
.IX Subsection "Fault handling"
.PP
SOAP::WSDL::Client returns a fault object on errors, even on transport layer
errors.
.PP
The fault object is a \s-1SOAP1.1\s0 fault object of the following
\&\f(CW\*(C`SOAP::WSDL::SOAP::Typelib::Fault11\*(C'\fR.
.PP
SOAP::WSDL::SOAP::Typelib::Fault11 objects are false in boolean context, so
you can just do something like:
.PP
.Vb 1
\& my $result = $soap\->call($method, $data);
\&
\& if ($result) {
\&    # handle result
\& }
\& else {
\&    die $result\->faultstring();
\& }
.Ve
.PP
\fIoutputxml\fR
.IX Subsection "outputxml"
.PP
SOAP::Lite returns only the content of the \s-1SOAP\s0 body when outputxml is set
to true. SOAP::WSDL::Client returns the complete \s-1XML\s0 response.
.PP
\fIAuto-Dispatching\fR
.IX Subsection "Auto-Dispatching"
.PP
SOAP::WSDL::Client \fBdoes not\fR support auto-dispatching.
.PP
This is on purpose: You may easily create interface classes by using
SOAP::WSDL::Client and implementing something like
.PP
.Vb 4
\& sub mySoapMethod {
\&     my $self = shift;
\&     $soap_wsdl_client\->call( mySoapMethod, @_);
\& }
.Ve
.PP
You may even do this in a class factory \- see wsdl2perl for creating
such interfaces.
.SH "TROUBLESHOOTING"
.IX Header "TROUBLESHOOTING"
.SS "Accessing protected web services"
.IX Subsection "Accessing protected web services"
Accessing protected web services is very specific for the transport
backend used.
.PP
In general, you may pass additional arguments to the set_proxy method (or
a list ref of the web service address and any additional arguments to the
new method's \fIproxy\fR argument).
.PP
Refer to the appropriate transport module for documentation.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2004\-2007 Martin Kutter.
.PP
This file is part of SOAP-WSDL. You may distribute/modify it under the same
terms as perl itself
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Kutter <martin.kutter fen\-net.de>
.SH "REPOSITORY INFORMATION"
.IX Header "REPOSITORY INFORMATION"
.Vb 4
\& $Rev: 851 $
\& $LastChangedBy: kutterma $
\& $Id: Client.pm 851 2009\-05\-15 22:45:18Z kutterma $
\& $HeadURL: https://soap\-wsdl.svn.sourceforge.net/svnroot/soap\-wsdl/SOAP\-WSDL/trunk/lib/SOAP/WSDL/Client.pm $
.Ve