=encoding utf8

=head1 NAME

XML::Compile::SOAP::Daemon::LWPutil - LWP helper routines

=head1 INHERITANCE

 XML::Compile::SOAP::Daemon::LWPutil
   is a Exporter

=head1 SYNOPSIS

  # used by ::Daemon::NetServer
  #     and ::Daemon::AnyDaemon

=head1 DESCRIPTION

=head1 FUNCTIONS

=over 4

=item B<lwp_action_from_header>(REQUEST)

Collect the soap action URI from the request, with C<undef> on failure.
Officially, the "SOAPAction" has no other purpose than the ability to
route messages over HTTP: it should not be linked to the portname of
the message (although it often can).

=item B<lwp_add_header>(FIELD, CONTENT, ...)

=item B<lwp_handle_connection>(CONNECTION, OPTIONS)

=item B<lwp_http11_connection>(DAEMON, SOCKET)

Initialize a HTTP/1.1 connect on the client SOCKET.

=item B<lwp_make_response>(REQUEST, RC, MSG, BODY, [POSTPROC])

=item B<lwp_run_request>(REQUEST, HANDLER, [CONNECTION, POSTPROC])

Handle one REQUEST (HTTP::Request object), which was received from
the CLIENT (string).  When the request has been received, the HANDLER
is called. Returns the status, the status as text message, and the
output as XML::LibXML::Document.

=item B<lwp_socket_init>(SOCKET)

Initialize LWP usage based on a created SOCKET.

=item B<lwp_wsdl_response>([WSDLFILE|RESPONSE])

Set the result of WSDL query responses, either to a response which
is created internally containing WSDLFILE, or to an already complete
RESPONSE object (HTTP::Response).  The response object is returned.

=back

=head1 DETAILS

=head2 Postprocessing responses

The C<LWP> based daemons provide a C<postprocess> option to their C<run()>
methods.  The parameter is a CODE reference.

When defined, the CODE is called when the response message is ready
to be returned to the client:

  $code->($request, $response, $status, \$body)

The source C<$requests> is passed as first parameter.  The C<$response>
is an HTTP::Response object, with all headers but without the body.
The C<$status> is the result code of the handler.  A value of 200
(C<HTTP_OK> from C<HTTP::Status>) indicates successful processing of the
request.  When the status is not HTTP_OK you may skip the postprocessing.

The C<$body> are the bytes which will be added as body to the response
after this postprocessing has been done.  You may change the body.
B<Be warned> that the body is not a (latin1 or utf-8) string but already
encoded into a byte string.

=head1 SEE ALSO

This module is part of XML-Compile-SOAP-Daemon distribution version 3.08,
built on January 08, 2014. Website: F<http://perl.overmeer.net/xml-compile/>

Other distributions in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::WSDL11>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::C14N>,
L<XML::Compile::WSS>,
L<XML::Compile::WSS::Signature>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>
and
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2007-2014 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>