.\" 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::Manual::Cookbook 3pm" .TH SOAP::WSDL::Manual::Cookbook 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::Manual::Cookbook \- SOAP::WSDL recipes .SS "Accessing \s-1HTTPS\s0 webservices" .IX Subsection "Accessing HTTPS webservices" You need Crypt::SSLeay installed to access \s-1HTTPS\s0 webservices. .SS "Accessing protected web services" .IX Subsection "Accessing protected web services" Passing a username and password, or a client certificate and key, to the transport layer is highly dependent on the transport backend. The descriptions below are for \s-1HTTP\s0(S) transport using LWP::UserAgent .PP \fIAccessing \s-1HTTP\s0(S) webservices with basic/digest authentication\fR .IX Subsection "Accessing HTTP(S) webservices with basic/digest authentication" .PP When using SOAP::WSDL::Transport::HTTP (SOAP::Lite not installed), add a method called \*(L"get_basic_credentials\*(R" to SOAP::WSDL::Transport::HTTP: .PP .Vb 3 \& *SOAP::WSDL::Transport::HTTP::get_basic_credentials = sub { \& return ($user, $password); \& }; .Ve .PP When using SOAP::Transport::HTTP (SOAP::Lite is installed), do the same to this backend: .PP .Vb 3 \& *SOAP::Transport::HTTP::Client::get_basic_credentials = sub { \& return ($user, $password); \& }; .Ve .PP \fIAccessing \s-1HTTP\s0(S) webservices protected by \s-1NTLM\s0 authentication\fR .IX Subsection "Accessing HTTP(S) webservices protected by NTLM authentication" .PP If you want to connect to a windows server using some Windows Domain Login, please consider using Kerberos instead of the (older) \s-1NTLM\s0 mechanism \- see below. .PP Kerberos and \s-1NTLM\s0 are (currently) mutually exclusive \- when LWP::Authen::Negotiate is installed, it will always be queried (and will always raise an error), even if you don't want to use it. See http://rt.cpan.org/Public/Bug/Display.html?id=32826 for details. .PP You need the \s-1NTLM\s0 distribution installed to access webservices protected by \s-1NTLM\s0 authentication. More specifically, you need the Authen::NTLM module from this distribution. Note that this is different from the Authen::NTML distribution by Yee Man Chan also available from \s-1CPAN.\s0 .PP Your user credentials usually need to include the windows domain or the windows hostname like this: .PP .Vb 1 \& testdomain\etestuser .Ve .PP or .PP .Vb 1 \& \e\etesthost\etestuser .Ve .PP Besides passing user credentials as when accessing a web service protected by basic or digest authentication, you also need to enforce connection keep_alive on the transport backens. .PP To do so, pass a \fIproxy\fR argument to the \fBnew()\fR method of the generated class. This unfortunately means that you have to set the endpoint \s-1URL,\s0 too: .PP .Vb 3 \& my $interface = MyInterfaces::SERVICE_NAME::PORT_NAME\->new({ \& proxy => [ $url, keep_alive => 1 ] \& }); .Ve .PP You may, of course, decide to just hack the generated class. Be advised that subclassing might be a more appropriate solution \- re-generating overwrites changes in interface classes. .PP \fIAccessing \s-1HTTP\s0(S) webservices protected by NTLMv2\fR .IX Subsection "Accessing HTTP(S) webservices protected by NTLMv2" .PP There are different variants of \s-1NTLM,\s0 and by default Authen::NTLM uses the v1 variant. .PP \&\s-1NTLM\s0 is a connection-based handshake authentication protocol, which requires three or more requests on the same connection: .PP .Vb 3 \& Request POST \& Response 401 Unauthorized \& WWW\-Authenticate: NTLM \& \& Request Authorization: NTLM \& Response 401 Unauthorized \& WWW\-Authenticate: NTLM \& \& Request Authorization: NTLM \& Response 200 Ok .Ve .PP If you try to access a NTLMv2 protected web service and switch on LWP::Debug by saying .PP .Vb 1 \& use LWP::Debug qw(+); .Ve .PP you should see at least two lines containing something like .PP .Vb 3 \& Authorization NTLM TlRMTVNTUAABAAAAB7IAAAAAAAAAAAAAAwADACAAAABmb28= \& ... \& Authorization NTLM TlRMTVNTUAABAAAAB7IAAAAAAAAAAAAAAw ... much longer ... ADACAAAABmb28= .Ve .PP If you're talking to a Server using NTLMv2 exclusively, you will only the first line in the debug output, and then an error. .PP To explicitly enable NTLMv2, do the following in your client: .PP .Vb 2 \& use Authen::NTLM; \& ntlmv2(1); .Ve .PP This globally enables the use of NTLMv2. Note that this is a global setting: All clients running in the same perl interpreter will be affected. This can cause unexpected issues when running under mod_perl. .PP \fIAccessing webservices protected by \s-1HTTP\s0 Kerberos Authentication\fR .IX Subsection "Accessing webservices protected by HTTP Kerberos Authentication" .PP Use the LWP::Authen::Negotiate plugin from \s-1CPAN.\s0 You need to set up \s-1GSSAPI\s0 to perform the Kerberos authentication, though. How to do this is implementation specific (\s-1MIT\s0 or Heimdahl). See your Kerberos/GSSAPI documentation for details. .PP (Newer) Windows Web Services usually allow one to use both the Negotiate (Kerberos) and \s-1NTLM\s0 authentication scheme. .PP \fIAccessing \s-1HTTPS\s0 webservices protected by certificate authentication\fR .IX Subsection "Accessing HTTPS webservices protected by certificate authentication" .PP You need Crypt::SSLeay installed to access \s-1HTTPS\s0 webservices. .PP See Crypt::SSLeay on how to configure client certificate authentication. .SH "XML OUTPUT" .IX Header "XML OUTPUT" .SS "Outputting namespaces as prefixes" .IX Subsection "Outputting namespaces as prefixes" Q: I need to interface with a \s-1SOAP\s0 server which doesn't accept the following format: .PP .Vb 8 \& \& \& \& 12345 \& \& \& .Ve .PP Instead, it requires this: .PP .Vb 9 \& \& \& \& 12345 \& \& \& .Ve .PP How do I do this using \s-1SOAP::WSDL\s0? .PP A: The following steps are necessary to achieve this result: .PP First, you would need to write a new serializer, which is quite easy, as it just creates the envelope and calls \->\fBserialize_qualified()\fR on \f(CW$header\fR and \&\f(CW$body\fR to fill them in. The new serializer has to declare all namespace prefixes used, the rest is just the same as the original \s-1XSD\s0 serializer. .PP Second, you'd need to overwrite the start_tag method in SOAP::WSDL::XSD::Typelib::Element to use the appropriate prefixes for the body elements. .PP In contrast to the original method, it would probably look up the appropriate prefix from some data set in the serializer class, so this could be the appropriate place to load SOAP::WSDL::XSD::Typelib::Element and override the method. .PP Something like this should do (without the handling of specialties like empty or nil elements): .PP .Vb 1 \& %PREFIX_OF = { \*(Aqhttp://services.company.com/\*(Aq => \*(Aqns2\*(Aq }; \& \& *SOAP::WSDL::XSD::Typelib::Element::start_tag = sub { \& # use prefix instead of xmlns attribute and copy the rest from \& # SOAP::WSDL::XSD::Typelib::Element::start_tag \& my $prefix = $PREFIX_OF{ $_[0]\->get_xmlns() }; \& my $name = $_[1]\->{ name } || $self\->_\|_get_name(); \& return "<$prefix:$name>"; \& } .Ve .ie n .SH "Skipping unknown XML elements \- ""lax"" XML processing" .el .SH "Skipping unknown XML elements \- ``lax'' XML processing" .IX Header "Skipping unknown XML elements - lax XML processing" \&\s-1SOAP::WSDL\s0's default serializer SOAP::WSDL::Deserializer::XSD is a \*(L"strict\*(R" \&\s-1XML\s0 processor in the sense that it throws an exception on encountering unknown \&\s-1XML\s0 elements. .PP SOAP::WSDL::Deserializer::XSD allows switching off the stric \s-1XML\s0 processing by passing the \f(CW\*(C`strict => 0\*(C'\fR option. .SS "Disabling strict \s-1XML\s0 processing in a Client" .IX Subsection "Disabling strict XML processing in a Client" Pass the following as \f(CW\*(C`deserializer_args\*(C'\fR: .PP .Vb 1 \& { strict => 0 } .Ve .PP Example: The generated \s-1SOAP\s0 client is assumed to be \*(L"MyInterface::Test\*(R". .PP .Vb 1 \& use MyInterface::Test; \& \& my $soap = MyInterface::Test\->new({ \& deserializer_args => { strict => 0 } \& }); \& \& my $result = $soap\->SomeMethod(); .Ve .SS "Disabling strict \s-1XML\s0 processing in a \s-1CGI\s0 based server" .IX Subsection "Disabling strict XML processing in a CGI based server" You have to set the deserializer in the transport class explicitly to a SOAP::WSDL::Deserializer object with the \&\f(CW\*(C`strict\*(C'\fR option set to 0. .PP Example: The generated \s-1SOAP\s0 server is assumed to be \*(L"MyServer::Test\*(R". .PP .Vb 3 \& use strict; \& use MyServer::Test; \& use SOAP::WSDL::Deserializer::XSD; \& \& my $soap = MyServer::Test\->new({ \& transport_class => \*(AqSOAP::WSDL::Server::CGI\*(Aq, \& dispatch_to => \*(Aqmain\*(Aq, \& }); \& $soap\->get_transport()\->set_deserializer( \& SOAP::WSDL::Deserializer::XSD\->new({ strict => 0 }) \& ); \& \& $soap\->handle(); .Ve .SS "Disabling strict \s-1XML\s0 processing in a mod_perl based server" .IX Subsection "Disabling strict XML processing in a mod_perl based server" Sorry, this is not implemented yet \- you'll have to write your own handler class based on SOAP::WSDL::Server::Mod_Perl2. .SH "Changing the encoding of a SOAP request" .IX Header "Changing the encoding of a SOAP request" \&\s-1SOAP::WSDL\s0 uses utf\-8 per default: utf\-8 is the de-facto standard for webservice ommunication. .PP However, you can change the encoding the transport layer announces by calling \&\f(CW\*(C`set_encoding($encoding)\*(C'\fR on a client object. .PP You probably have to write your own serializer class too, because the default serializer has the utf\-8 encoding hardcoded in the envelope. .PP Just look into SOAP::WSDL::Serializer on how to do that. .PP Don't forget to register your serializer at the serializer factory SOAP::WSDL::Factory::Serializer. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2008, 2009 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 .SH "REPOSITORY INFORMATION" .IX Header "REPOSITORY INFORMATION" .Vb 4 \& $Rev: 583 $ \& $LastChangedBy: kutterma $ \& $Id: $ \& $HeadURL: $ .Ve