NAME

Net::OpenWBEM - Perl interface for OpenWBEM

DESCRIPTION

This is owperlprovider, a Perl provider interface for OpenWBEM. This lets you write OpenWBEM providers in Perl. It also includes client side Perl bindings for OpenWBEM, which lets you write an OpenWBEM client in Perl.

This module (Net::OpenWBEM) contains functionality common to OpenWBEM clients and providers.

OPENWBEM APPLICATION PROGRAMMING INTERFACE

This section documents the various CIM elements made available to the Provider script, and the methods available on those elements.

Catching Exceptions

Certain OpenWBEM operations may throw exceptions. To catch these, wrap the method invocation in an eval { } block. Then check the $@ variable. If this variable is set, then an exception occurred. Here is an example using the getInstance method:

  my $ci = eval { $cimom->getInstance($ns, $cop) };
  if ($@)
  {
      # exception occurred
  }

Constant Values

Some methods take enumerated values for parameters. The definitions of these enumerations are defined as scalar variables in the Net::OpenWBEM::WBEMFlags namespace. E.g.

  $cimom->getInstance($ns, $cop,
        $Net::OpenWBEM::WBEMFlags::E_NOT_LOCAL_ONLY,
        $Net::OpenWBEM::WBEMFlags::E_INCLUDE_QUALIFIERS);

CIMClass

Contains information about a CIM Class, and allows providers to create new instances of that class.

$name = $cimClass->getName;
Returns the name of the class, as a string.

$className = $cimClass->getSuperClass;
Returns the name of the class's superclass, or an empty string if the class does not have a superclass.

$ci = $cimClass->newInstance;
 $ci = $cimClass->newInstance( 
         { 
            property => 'value', 
            property2 => 'value2',
            property3 => 'value3'
         }
 );

Creates a new instance of class $cimClass. If a single hash ref is passed as parameter, the new instance's properties will be assigned from this hash ref.

Note that this does not work for properties named like one of Net::OpenWBEM::CIMInstance's methods.

$keysRef = $cimClass->getKeys;
Returns a referenced array of CIMProperty objects, one for each key property of the class.

$arrayRef = $cimClass->getAllProperties;
Returns a referenced array of CIMProperty objects: all properties for this class, including overrides.

$arrayRef = $cimClass->getProperties;
Returns a referenced array of CIMProperty objects: all properties for this class, excluding overrides.

$prop = $cimClass->getProperty($propName);
Returns a CIMProperty object for the named property in this class.

print $cimClass->toString;
Prints a string representation of the class; this may be helpful for debugging purposes.

CIMInstance

CIMInstance represents the classname, properties, and property values associated with an instance of a CIMClass.

Providers construct objects of type CIMInstance when returning instance data. They may also receive objects of type CIMInstance (e.g. when implementing modifyInstance).

To create a new object of type CIMInstance, use the newInstance method of the CIMClass object for the type of instance you want to create.

$className = $ci->getClassName;
Returns the name of the class as a string.

$property = $ci->getProperty($propertyName);
Returns an object of type CIMProperty, corresponding to the property identified by $propertyName.

$value = $ci->getPropertyValue($propertyName);
Returns the value of the property as a Perl string, or undef if it is Null. This works for numerical values as well as string values.

$value = $ci->getBooleanProperty($name);
Gets the value of a property of type boolean on a CIMInstance. If the property does not exist or the value is NULL, false is returned.

$value = $ci->getIntegerProperty($name);
Gets the value of a property of type integer on a CIMInstance. If the property does not exist or the value is NULL, an exception will be raised. Catch the exception by doing try {} catch {} or eval {}.

$value = $ci->getStringProperty($name);
Gets the value of a property of type string on a CIMInstance. If the property does not exist or the value is NULL, an empty string is returned.

$value = $ci->getArrayProperty($name);
Get the values of an array property (of all types) as list reference.

Note: This is not functional for DateTime arrays by now.

$ci->setBooleanProperty($name, $boolValue);
Sets a property of type boolean on a CIMInstance.

$ci->setIntegerProperty($name, $intValue);
Sets a property of type integer on a CIMInstance.

$ci->setRefProperty($name, $copValue);
Sets a reference property. The $copValue parameter is of type CIMObjectPath.

$ci->setStringProperty($name, $stringValue);
Sets a property of type string on a CIMInstance. $name identifies the name of the property to set.

$ci->setArrayProperty( $name, $listRef );
Sets an array property of any type to the values provided in $listRef (which, of course, must be a list reference).

This will fail, if the values presented in $listRef are not convertable to the type of the property (i.e. like setting an array property of UInt8 to [ foo, bar ] );

print $ci->toString;
Prints a string representation of the instance; this may be helpful for debugging purposes.

CIMInstanceEnumeration

This object is returned from CIMOM methods that return multiple instance objects, such as enumInstancesE. Iterate through each instance like this:

  while ($enumeration->hasMoreElements)
  {
      my $ci = $enumeration->nextElement;
      # do stuff...
  }
$enumeration->hasMoreElements
Returns a true value if the enumeration has more elements (i.e. instances) remaining.

my $ci = $enumeration->nextElement;
Returns the next CIM instance from the enumeration.

Shortcut accessors/mutators

To ease working with Net::OpenWBEM::CIMInstance objects, shortcut accessors / mutators exist for all of the instance's properties.

To get the value of a property $name, simply call

 $value = $ci->$name();

like

 $ccn = $ci->CreationClassName();

To set the value of a property $name, simply call

 $ci->$name( $value );

like

 $ci->CreationClassName( 'CIM_ObjectClass' );

For setting an array property, simply pass in a list reference as value. Similarly, when getting an array property this way, a list reference is returned (or undef if the property's not set).

CIMInstanceResultHandlerIFC

This object is used to return results from operations that return instance data from multiple instances (e.g. enumInstances, associators, references).

$result->handle($cop);
Return an object of type CIMInstance to the caller.

CIMObjectPath

Contains the information needed to uniquely identify a CIM instance.

$cop = Net::OpenWBEM::CIMObjectPath->new($className, $ns, \%keys);
Creates a new CIMObjectPath with the given class name $className and namespace $ns.

The \%keys hash ref is optional, and may contain a list of key-value pairs.

If a \%keys hash is present, the contained keys will be set to the corresponding values.

$cop = Net::OpenWBEM::CIMObjectPath->new($ns, $inst, \%keys);
Creates a new CIMObjectPath using the provided CIMInstance $inst. Since the CIMInstance object doesn't contain a namespace, you must also specify the namespace $ns.

The \%keys hash ref is optional, and may contain a list of key-value pairs.

If a \%keys hash is present, the contained keys will be set to the corresponding values, overriding the instance's values.

$cop = Net::OpenWBEM::CIMObjectPath::parse($instanceName);
Creates a new CIMObjectPath using the provided stringified object path. See also toString.

$bool = $cop->equals($otherCop);
Returns a true value if the two CIMObjectPaths are considered equal. This uses the underlining OpenWBEM equals method, which currently has some limitations... e.g. the keys must be specified in the same order to be considered equal.

$className = $cop->getClassName;
Returns the name of the class of the object identified by $cop.

$ns = $cop->getHost;
Returns the host name from the name space for this object path.

$ns = $cop->getNameSpace;
Returns the namespace of the object identified by $cop.

$cop->setHost($host);
Sets the host name on the name space for this object path.

$cop->setNameSpace($ns);
Sets the namespace for this object path.

$intValue = $cop->getIntegerKeyValue($keyName);
Returns the value of an integer key property, which is included in $cop.

$mcop = $cop->getRefKeyValue($keyName);
Returns the value of a reference key property, which is included in $cop.

$strValue = $cop->getStringKeyValue($keyName);
Returns the value of a string key property, which is included in $cop.

$cop->setIntegerKeyValue($keyName, $intValue);
Sets a numeric key value of $cop named $keyName to $intValue.

$cop->setRefKeyValue($keyName, $mcop);
Sets a reference key value (a CIMObjectPath) of $cop named $keyName to $mcop.

$cop->setStringKeyValue($keyName, $strValue);
Sets a string key value of $cop named $keyName to $strValue.

print $cop->toString;
Prints a string representation of the object, which may be useful when debugging a provider. See also the parse function.

$ci = $cop->createInstanceMinimal;
Experimental. Creates a new empty instance object, then adds in the keys of this object path to the instance. Unlike CIMClass::newInstance (an alternate way to create an instance), the instance object does not initialize non-key properties or include property qualifiers.

Shortcut accessors/mutators

To ease working with Net::OpenWBEM::CIMObjectPath objects, shortcut accessors / mutators exist for all of the ObjectPath's keys.

To get the value of a key $name, simply call

 $value = $cop->$name();

like

 $ccn = $cop->CreationClassName();

To set the value of a key $name, simply call

 $cop->$name( $value );

like

 $ci->CreationClassName( 'CIM_ObjectClass' );

CIMObjectPathEnumeration

This object is returned from CIMOM methods that return multiple instance names, such as enumInstanceNamesE. Iterate through each object path like this:

  while ($enumeration->hasMoreElements)
  {
      my $cop = $enumeration->nextElement;
      # do stuff...
  }
$enumeration->hasMoreElements
Returns a true value if the enumeration has more elements (i.e. object paths) remaining.

my $cop = $enumeration->nextElement;
Returns the next CIM object path from the enumeration.

CIMObjectPathResultHandlerIFC

This object is used to return results from operations that return multiple object names (e.g. enumInstanceNames, associatorNames, referenceNames).

$result->handle($cop);
Return an object of type CIMObjectPath to the caller.

CIMOMHandleIFCRef

A provider may need to access schema data not provided directly. Use the $env parameter to get the CIMOM handle, then use one of the following methods:

$copEnumeration = $cimom->associatorNamesE($ns, $path, $assocClass, $resultClass, $role, $resultRole);
Returns an ``enumeration'' of all instances' object paths that are associated with the specified instance $path. The $assocClass parameter is optional. If specified, it is the name of an association class, and only names of instances associated via that class (or subclass) will be returned.

$instanceEnumeration = $cimom->associatorsE($ns, $path, $assocClass, $resultClass, $role, $resultRole);
Returns an ``enumeration'' of all instances that are associated with the specified instance $path. The $assocClass parameter is optional. If specified, it is the name of an association class, and only instances associated via that class (or subclass) will be returned.

$copEnumeration = $cimom->referenceNamesE($ns, $path, $resultClass, $role);
Returns an ``enumeration'' of all association instances' object paths that reference the specified instance $path. The $resultClass parameter is optional, specifying the name of an association class. Only the names of association instances that are that class (or subclass) will be returned.

$instanceEnumeration = $cimom->referencesE($ns, $path, $resultClass, $role, $includeQualifiers, $includeClassOrigin);
Returns an ``enumeration'' of all association instances that reference the specified instance $path. The $resultClass parameter is optional. If specified, it is the name of an association class, and only instances of that class (or subclass) will be returned.

$copEnumeration = $cimom->enumInstanceNamesE($ns, $className);
Returns an ``enumeration'' of all instances' object paths that are of the specified class or a subclass of the specified class.

$instanceEnumeration = $cimom->enumInstancesE($ns, $className);
Returns an ``enumeration'' of all instances that are of the specified class or a subclass of the specified class.

$path = $cimom->createInstance($ns, $cimInstance);
Creates a new instance, using the instance data provided, returning an object path that names the new instance.

$cimom->deleteClass($ns, $className);
Deletes the specified class.

$cimom->deleteInstance($ns, $path);
Deletes the instance specified by $path.

$cimClass = $cimom->getClass($ns, $className);
Gets class data for a given class. $ns is a string value identifying the namespace; $className is a string value--the name of the class to get.

$cimInstance = $cimom->getInstance($ns, $path, $localOnly, $includeQualifiers);
Retrieves instance data for the instance specified by $path. $localOnly is an optional parameter, by default is $Net::OpenWBEM::WBEMFlags::E_NOT_LOCAL_ONLY. $includeQualifiers is also optional, by default it is $Net::OpenWBEM::WBEMFlags::E_EXCLUDE_QUALIFIERS. To get qualifier information, specify Net::OpenWBEM::WBEMFlags::E_INCLUDE_QUALIFIERS.

$cimom->modifyInstance($ns, $modifiedInstance);
Updates instance data. The instance is identified by the key properties of $modifiedInstance (a CIMInstance object). This means you cannot change the values of key properties with this method, and the supplied instance data must include the ``Key'' qualifiers on the key properties.

$result = $cimom->invokeMethod($ns, $path, $methodName, $inParams, $outParams);
Invokes the specified method on the specified object $path (a CIMObjectPath). $inParams and $outParams are CIMParamValueArray objects; the former supplies the ``in'' parameters matching the order specified in the schema, and the latter is filled with the ``out'' parameters when the metod returns.

CIMParamValue

$pv = Net::OpenWBEM::CIMParamValue($paramName);
Creates a new CIMParamValue object with the specified name and no initial value.

$copValue = $pv->getRefValue;
Accesses the parameter's value, assuming it's a CIM object path.

$stringValue = $pv->getStringValue;
Accesses the parameter's value, assuming it's a string.

$pv->setRefValue($copValue);
Sets the parameter's value to be the specified CIM object path.

$pv->setStringValue($stringValue);
Sets the parameter's value to be the specified string.

CIMParamValueArray

$array = Net::OpenWBEM::CIMParamValueArray->new;
Creates a new array for holding CIMParamValues.

$array->push_back($pv);
Appends the specified parameter value $pv to the array.

$len = $array->size;
Accesses the number of elements in the array.

$pv = $array->get($idx);
Accesses the element at the specified index $idx.

$array->set($idx, $pv);
Sets the element at the specified index $idx to $pv.

CIMProperty

$name = $property->getName;
Returns the name of the property.

$result = $property->isKey;
Returns a true value if the property is a key property of the class.

$result = $property->isReference;
Returns a true value if the property is a reference.

$val = $property->getValue;
Returns an object of type CIMValue representing the value of the property.

print $property->toString;
Generates a stringified representation of the property object; may be useful for debugging purposes.

CIMValue

The CIMValue class is an abstraction for all CIM data types.

$val = Net::OpenWBEM::CIMValue::createNull;
Creates a new CIM value, with an initially null value.

$val = Net::OpenWBEM::CIMValue->new($stringValue);
Creates a new CIM value, with a string value.

$str = $value->toString;
Accesses the string value.

ProviderEnvironmentIFCRef

$cimom = $env->getCIMOMHandle;
Gets a CIMOM handle that you can use, for example, to get class data.

$cimom = $env->getRepositoryCIMOMHandle;
Gets a CIMOM handle that accesses the repository, bypassing dynamic instance data.

SEE ALSO

the Net::OpenWBEM::Provider manpage, the Net::OpenWBEM::Client manpage

AUTHOR

Jason Long - jason@long.name

COPYRIGHT

This file is part of owperlprovider.

Copyright (c) 2004-2005 Jason Long. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.