SOAP Message Construction with WSMan::WSBasic

You can use the WSMan::WSBasic class to construct SOAP messages for communicating with the WS-Management server. The Perl module is located in Perl/lib/WSMan/WSBasic.pm. All operations in this class return deserialized SOAP::SOM objects from which you can extract the fault code or the SOAP replies.

You usually do not use this module directly. Instead, you use the GenericOps module built on top of WSBasic. GenericOps supports generic operations as defined by the DMTF standards. See Generic CIM Operations with WSMan::GenericOps. If you want to use the SOAP::SOM library directly, see the CPAN documentation for SOAP::SOM.

The WSMan::WSBasic module requires the following Perl modules:

■	SOAP::Lite – WSMan::WSBasic requires Version 0.65 or later to form SOAP messages and to parse XML replies that are received from the WS-Management server.

■	UUID – Generates UUIDs for the SOAP messages.

Methods in WSMan::WSBasic lists the methods the WSBasic class provides, which are discussed in more detail below.

Methods in WSMan::WSBasic

Method	Description
WSMan::WSBasic->new	Constructor.
register_xml_ns	Registers extra XML namespaces that might be required for proprietary tags in the SOAP message
register_class_ns	Registers extra CIM namespaces that the WS-Management server might require.
Identify	Performs the wsmid:Identify operation, which causes the WS-Management server to identify itself.
Enumerate	Filters results differently depending on the arguments you pass in.
PullRelease	Performs a Pull or a Release operation (overloaded method).
Get	Retrieves an instance of a class.

WSMan::WSBasic->new

Constructor that takes a hash argument containing key-value pairs.

Arguments

The constructor takes the following arguments:

Argument	Description
address	WS-Management server URL. Specify the transport protocol by adding http (basic user-password authentication) or https (HTTP with SSL encryption).
port	Port on which the WS-Management server listens for requests.
path	Path to the WS-Management server. The path is combined with the address and port arguments to form the complete URL of the WS-Management server. The resulting URL is http://address:port/path.
username	User name for the WS-Management server.
password	Password for the WS-Management server.
namespace	CIM namespace. Default is root/cimv2.If the namespace is not root/cimv2, you must pass in the namespace of the class in this argument.
timeout (optional)	Timeout for the HTTP request.

Example

$client = WSMan::WSBasic->new( address => 'http://www.abc.com/',

port => '80',

path => 'wsman',

username => 'wsman',

password => 'secret',

namespace => 'root/cimv2', #optional

timeout => '60' #optional

);

register_xml_ns

Registers extra XML namespaces that might be required for proprietary tags in the SOAP message. Calling register_xml_ns is not usually required.

Arguments

A hash. Keys are the prefixes, values are the relative URLs as values.

Example

$client->register_xml_ns((wsen => 'http://www.dmtf.org/wsen'));

Declares a prefix wsen with the URL http://www.dmtf.org/wsen in the global XML namespace.

register_class_ns

Registers extra ResourceURIs that the WS-Management server might require. By default, the constructor provides a set of ResourceURIs only for classes in the CIM schema. Classes with other schema names, such as VMware_* classes, require a different ResourceURI when enumerated using the vSphere SDK for Perl.

You can find the ResourceURIs corresponding to other supported schemas in the OpenWSMan configuration file, which is located in the server's file system at /etc/openwsman/openwsman.conf. The ResourceURIs are listed in the value of the vendor_namespaces configuration parameter.

Arguments

A hash. Keys are the prefixes, values are the relative URLs as values.

Example

$client->register_class_ns((OMC => 'http://schema.omc-project.org/wbem/wscim/1/cim-schema/2',

VMware => 'http://schemas.vmware.com/wbem/wscim/1/cim-schema/2'));

Registers the ResourceURIs needed to enumerate classes in the OMC and VMware schemas.

Identify

Performs the wsmid:Identify operation, which causes the WS-Management server to identify itself. Helps you determine whether the server is up and running.

Arguments

No arguments.

Returns

Returns a SOAP::SOM object, which you can use to parse the results or do error correction.

Enumerate

Filters results depending on the arguments you pass in. Several arguments perform generic operations that are implemented in another class, as described in Generic CIM Operations with WSMan::GenericOps. Other arguments implement enumeration for non-standard-compliant servers. This document discusses the most common arguments. Look at the Perl code for information on other arguments.

Arguments

Accepts the following arguments:

Argument	Description
class_name	Specifies the class that you want to enumerate. This argument is passed as a string.
namespace	Default CIM namespace. Default is root/cimv2. If the namespace is not root/cimv2, you must pass in the namespace of the class in this argument.
enummode (optional)	Specifies an enumeration mode such as EnumerateEPR or EnumerateEPRandObject. This argument is passed as a string.
polymorphism (optional)	Specifies polymorphism modes, passed in as a string. For example IncludeSubClassProperties, ExcludeSubClassProperties, and None.

Returns

Returns a SOAP::SOM object that can be used to either check for errors ($result->fault) or to parse the results ($result->result). The SOAP object includes a header and data in XML format.

PullRelease

An overloaded method that performs a Pull operation or a Release operation.

Arguments

Accepts the following arguments:

Argument	Description
enumid	Enumeration ID that the Pull or Release operation should use. This argument is passed as a string.
action	Specifies the operation to perform, Pull or Release. This argument is passed as a string.
namespace	Default CIM namespace. Default is root/cimv2. If the namespace is not root/cimv2, you must pass in the namespace of the class in this argument.

Get

Retrieves an instance of a class.

Arguments

Accepts the following named arguments:

Argument	Description
class_name	The class whose instance you want to retrieve. This argument is passed as a string.
options	Passes keys for the particular instance on which you want to perform a Get operation. Passed as a reference to a hash containing the keys in name-value pairs.
namespace	Default CIM namespace. Default is root/cimv2. If the namespace is not root/cimv2, you must pass in the namespace of the class in this argument.

WSMan::WSBasic Examples

This section shows a few code examples for WSMan::WSBasic.

Using Enumeration Modes

To use one of the enumeration modes like EnumerateEPR or EnumerateEPRandObject, call the Enumerate operation with EnumerationMode enabled. You can also specify the enumeration mode in the constructor.

$result = $client->Enumerate(class_name => 'CIM_Processor',

#namespace => 'root/cimv2', #if needed.

enummode => 'EnumerateEPR'

);

Registering Classes

To perform operations on vendor-specific classes, you must register them first with the client. The actual URL depends on your WS-Management software.

$client->register_class_ns(Linux => 'http://www.dmtf.org/linux');

Using Enumerate and Pull Operations

#!/usr/bin/perl -w

use strict;

use WSMan::WSBasic; #Import the module.

my ($enumid, result, $client); #declaring variables.

#Construct the client.

$client = WSMan::WSBasic->new(

path => 'wsman',

username => 'wsman',

password => 'secret',

port => '8889',

address => 'http://something.somewhere.com'

);

#Execute the Enumerate method.

$result = $client->Enumerate(class_name => 'CIM_Processor',

#namespace => 'root/cimv2'

);

if($result->fault){

#If a fault occurred, then print the faultstring

die $result->faultstring;

}

else{

   #If no fault occurred then get the enumid.

   $enumid = $result->result;

}

$result = $client->PullRelease(

class_name => 'CIM_Processor',

enumid => $enumid,

action => 'Pull',

#namespace => 'root/cimv2'

);

if($result->fault){

   #If a fault occurred, then print the faultstring

   die $result->faultstring;

}

else{

# Do stuff with $result, which is a SOAP::SOM object containing a deserialized XML reply.

# It is better to use the Generic Operations module, built on top of this module.

}