NAME

SOAP::Envelope - Creates SOAP streams

SYNOPSIS

    use SOAP::Envelope;

    sub output_fcn {
        my $string = shift;
        print $string;
    }

    my $namespaces_to_preload = ["urn:foo", "urn:bar"];
    my $env = SOAP::Envelope->new(\&output_fcn,
                                  $namespaces_to_preload);
    my $header = $env->header("urn:a", "MyHeaderA",
                              undef, undef,
                              0, 0);
    ...
    $header->term();

    $header = $env->header("urn:b", "MyHeaderB",
                           undef, undef,
                           0, 0);
    ...
    $header->term();

    my $body = $env->body("urn:c", "MyCall",
                          undef, undef);
    ...
    $body->term();

    $env->term();

DESCRIPTION

This class bootstraps and manages the serialization of an object graph into a SOAP stream. It is used by the SOAP::Transport classes, but may be used directly as well.

The new function

Creates a new envelope. If you know you'll be using certain namespaces a lot, you can save some space by preloading those namespaces (pass the set of URI strings as an array when creating a new envelope, as in the example above).

The header function

Creates a new header in the specified namespace URI (which is required). You can call this function multiple times to create several different headers, but don't call the body function until you've created all the headers. If omitted, the typename and typeuri will be taken from the accessor name and accessor uri, but the accessor name and uri are required. Be sure to term() the current header before creating a new one. For a discussion of the $object optional parameter, please see body(), below.

The body function

Creates the body. You can only call this function once per envelope, and you must call it after you're done creating all the headers you need to create. If omitted, the typename and typeuri will be taken from the accessor name and accessor uri, but the accessor name is required. The $object parameter is optional, but must be passed if headers (or subelements in the body) may point to the body itself. SOAP::Envelope adds this object reference into its identity dictionary to correctly deal with these cases (a doubly-linked list is a simple example of this case). If you pass $object, you have to be prepared for body() to return undef, which indicates that the object was already marshaled into the header area (because it was referred to by a header element). In this case, the body element will simply be a reference to the previously marshaled body. If body() returns a value, don't forget to call term() through it when you're done serializing the body, because this forces the output of any outstanding multi-ref items.

The term function

This writes an end tag, terminating the SOAP envelope.

DEPENDENCIES

SOAP::OutputStream SOAP::Packager SOAP::Defs

AUTHOR

Keith Brown