view release on metacpan or  search on metacpan

lib/SOAP/Transport.pod  view on Meta::CPAN

Creates a new object instance and returns it. Like the constructors for both C<SOAP::Lite> and L<SOAP::Server> classes, all arguments passed in are treated as key/value pairs, where the key is expected to be one of the methods the class supports, and...

=item send_receive(key/value pairs)

    $client->send_recieve(%hash_table);

(Required for client classes only) When the SOAP::Lite objects attempt to send out requests, the means for doing so is to attempt to call this method on the object held within the SOAP::Transport object contained within the client itself. All clients...

=over

=item action

The URI specifying the action being performed, usually the result from the on_action hook on the client object.

=item encoding

The URI of the encoding scheme that governs the message being sent.

=item endpoint

The URI specifying the endpoint to which the message is being sent.

=item envelope

The XML content of the message to be sent. It is generally the return value of the envelope method from the L<SOAP::Serializer> object instance that the client object maintains.

=item parts

Attachments to add to the request. Currently this only supports an array of MIME::Entity objects, but in theory could support attachments of any format.

=back

=item handle

    $server->handle;

(Required for server classes only.) This method is the central point for the various server classes to provide an interface to handling requests. The exact set and nature of parameters generally varies based on the classes themselves.

=back

=head2 SOAP::Transport::HTTP

The most commonly used transport module is the HTTP implementation. This is loaded whenever an endpoint is given that starts with the characters, http:// or https://. This is also the most involved of the transport modules, defining not only a client...

=head3 HTTP PROXY SETTINGS

Because C<SOAP::Client> inherits from C<LWP::UserAgent>, you can use any of C<LWP::UserAgent>'s proxy settings. For example:

   SOAP::Lite->proxy("http://endpoint.server/",
                     proxy => ["http" => "http://my.proxy.server"]);

or

   $soap->transport->proxy("http" => "http://my.proxy.server");

The above code samples should specify a proxy server for you. And should you use C<HTTP_proxy_user>
and C<HTTP_proxy_pass> for proxy authorization, C<SOAP::Lite> will handle it properly.

=head3 HTTP BASIC AUTHENTICATION

HTTP Basic authentication is accomplished by overriding the get_basic_credentials subroutine in C<LWP::UserAgent> (which C<SOAP::Transport::HTTP::Client> is a subclass):

  BEGIN {
    sub SOAP::Transport::HTTP::Client::get_basic_credentials {
      return 'username' => 'password';
    }
  }

=head3 COOKIE-BASED AUTHENTICATION

    use HTTP::Cookies;
    my $cookies = HTTP::Cookies->new(ignore_discard => 1);
    # you may also add 'file' if you want to keep them between sessions
    my $soap = SOAP::Lite->proxy('http://localhost/');
    $soap->transport->cookie_jar($cookies);

Or, alternatively, you can do the above on a single line:

  $soap->proxy('http://localhost/',
               cookie_jar => HTTP::Cookies->new(ignore_discard => 1));

Cookies will be taken from the response and provided to the request. You may access and manipulate cookies received, as well as add cookies of your own by using the C<HTTP::Cookies> interfaces.

=head3 SSL CERTIFICATE AUTHENTICATION

The default SSL implementation for the HTTP client library L<LWP::UserAgent> used by SOAP::Lite is L<IO::Socket::SSL>.

To enable certificate based authentication, you'll have to pass your certificate and key as additional options to the
proxy() method like this:

    $soap->proxy( $url, ssl_opts => {
        SSL_cert_file => 'client-cert.pem',
        SSL_key_file  => 'client-key.pem'
    });

Or you can set them later like this:

    $soap->transport->ssl_opts(
        SSL_cert_file => 'client-cert.pem',
        SSL_key_file  => 'client-key.pem'
    );


If you're using L<Crypt::SSLeay>, the following applies:

To get certificate authentication working you need to set three environment variables: C<HTTPS_CERT_FILE>, C<HTTPS_KEY_FILE>, and optionally C<HTTPS_CERT_PASS>. This can be done either through the command line, or directly within your Perl script usi...

  $ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
  $ENV{HTTPS_KEY_FILE}  = 'client-key.pem';

These settings are referenced by C<Crypt::SSLeay>. Other options (e.g. CA peer verification) can be specified in a similar way. See L<Crypt::SSLeay> documentation for more information.

Please note that you probably should not be using L<Crypt::SSLeay> because it does not perform hostname verification; LWP::UserAgent uses IO::Socket::SSL by default. See also L<https://metacpan.org/pod/Crypt::SSLeay#DO-YOU-NEED-Crypt::SSLeay>.

Those who would like to use encrypted keys may find the following thread in the SOAP::Lite newsgroup helpful:

http://groups.yahoo.com/group/soaplite/message/729

=head3 COMPRESSION

SOAP::Lite provides you with the option for enabling compression over the wire using HTTP I<only> in both the server and client contexts, provided that you have L<Compress::Zlib> installed. Compression and decompression is done transparently to your ...

A server will respond with an encoded/compressed message only if the client has asserted that it can accept it (indicated by client sending an C<Accept-Encoding> HTTP header with a 'deflate' or '*' value).