EnvelopeMaker(3)

NAME

       SOAP::EnvelopeMaker - Creates SOAP envelopes

SYNOPSIS

       use SOAP::EnvelopeMaker;

       my $soap_request = ''; my $output_fcn = sub {
           $soap_request .= shift; }; my $em = SOAP::EnvelopeMaker->new($out-
       put_fcn);

       my $body = SOAP::Struct->new(
           origin => { x => 10,  y => 20  },
           corner => { x => 100, y => 200 }, );

       $em->set_body("urn:com-develop-geometry", "calculateArea", 0, $body);

       my $host        = "soapl.develop.com"; my $port        = 80; my $end-
       point    = "/soap?class=Geometry"; my $method_uri  =
       "urn:com-develop-geometry"; my $method_name = "calculateArea";

       use SOAP::Transport::HTTP::Client;

       my $soap_on_http = SOAP::Transport::HTTP::Client->new();

       my $soap_response = $soap_on_http->send_receive($host, $port, $end-
       point,
                                                       $method_uri,
                                                       $method_name,
                                                       $soap_request); use
       SOAP::Parser; my $soap_parser = SOAP::Parser->new();
       $soap_parser->parsestring($soap_response);

       my $area = $soap_parser->get_body()->{result};

       print "The area is: $area\n";

DESCRIPTION

       The overall usage pattern of SOAP::EnvelopeMaker is as follows:

       1) Determine what you want to do with the resulting SOAP packet
          and create an output function that implements this policy.

       2) Create an instance of SOAP::EnvelopeMaker, passing a reference
          to your output function, or to a string if you were just planning
          on buffering the output anyway (in this case, you'll get an output
          function that looks like this: sub {$$r .= shift}

       (note that somebody may already have done these first two steps
        on your behalf and simply passed you a reference to a pre-initialized
        EnvelopeMaker - see SOAP::Transport::HTTP::Server for an example)

       3) (optional) Call add_header one or more times to specify headers.

       4) (required) Call set_body to specify the body.

       5) Throw away the EnvelopeMaker and do something with the envelope
          that you've collected via your output function (assuming you've
          not simply been piping the output somewhere as it's given to you).

       EnvelopeMaker expects that you'll add *all* your headers *before* set-
       ting the body - if you mess this up, the results are undefined.

       By the time set_body returns, a complete SOAP envelope will have been
       sent to your output function (in one or more chunks). You can

       new(OutputFcn)

       OutputFcn should accept a single scalar parameter, and will be called
       multiple times with chunks of the SOAP envelope as it is constructed.
       You can either append these chunks into a big string, waiting until the
       entire envelope is constructed before you do something with it (like
       calculate the content-length, for instance), or you can simply pipe
       each chunk directly to somebody else.

       As of version 0.25, you can now pass a string reference for OutputFcn
       and the EnvelopeMaker will provide a very simple buffering output func-
       tion (one that we all ended up writing anyway during testing): sub {$$r
       .= shift}

       add_header(AccessorUri, AccessorName, MustUnderstand, IsPackage,
       Object)

       The first two parameters allow you to specify a QName (qualified name)
       for your header. Note that in SOAP, all headers MUST be namespace qual-
       ified. MustUnderstand and IsPackage turn on SOAP features that are
       explained in the SOAP spec; if you haven't yet grok'd SOAP packages,
       just pass 0 for IsPackage. Finally, Object is whatever you'd like to
       serialize into the header (see set_body for notes on what can go here;
       headers can contain the same stuff as the body).

       set_body(AccessorUri, AccessorName, IsPackage, Object)

       The first two parameters allow you to specify a QName (qualified name)
       for the body. The name of the accessor is the name of the SOAP method
       call you're making. IsPackage says that the body will be a SOAP pack-
       age; just pass 0 if you're not sure what this means. Object is whatever
       you'd like to serialize. This can be one of the following things:

       1) a scalar - the body will contain the scalar content.

       2) a hash reference - the body will contain a SOAP serialized version
                             of the contents of the hash.

       3) a SOAP::Struct reference - the body will contain a SOAP serialized
                                     version of the struct, where the serial-
       ized
                                     contents of the struct will be in the
       same
                                     order in the SOAP bar as they appeared
                                     in the SOAP::Struct constructor.

       Note that the SOAP/Perl serialization architecture deals with refer-
       ences very carefully, so it is possible to pass arbitrary object graphs
       (although each "object reference" must currently be a non-blessed
       scalar or hash reference).

       In the future, expect to see support for passing blessed object refer-
       ences (if you want to do this today, see the experimental
       SOAP::TypeMapper).  SOAP::Struct is an example of this.

       One interesting thing SOAP (and SOAP/Perl) support is that the headers
       and body can share references. They can point to the same stuff. Also,
       cycle detection is a natural part of SOAP/Perl's serialization archi-
       tecture, so you can pass linked lists, circular queues, etc. and they
       will be rehydrated correctly.

DEPENDENCIES

       SOAP::Envelope

AUTHOR

       Keith Brown

EnvelopeMaker(3)

NAME

SYNOPSIS

DESCRIPTION

DEPENDENCIES

AUTHOR

SEE ALSO