The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

DMTF::CIM - Object Orieted Interface to a CIM Schema

VERSION

This document describes DMTF::CIM version 0.04

SYNOPSIS

  use DMTF::CIM;
  my $cim = DMTF::CIM->new();
  $cim->parse_mof( "/path/to/cim_schema_2.31.0.mof" );
  my $system = $cim->instance_of( 'cim_system' );
  $cim->class_tag_alias( 'CIM_LogEntry', 'entry' );
  $cim->resolve_target_class_tag( tag=>'sometag' [,assoc=>1] [,uri=>'/interop:CIM_RegisteredProfile.InstanceID=magic'] [,via=>'CIM_ElementConformsToProfile'])
  $uri = $cim->UFiP_to_URI( '/system1', 'wsman.wbem://interop:CIM_RegisteredProfile.InsanceID=EX' );
  $cim->clear_uri_cache()
  $cim->cache_uri_path( '/',
  $cim->GetClass(arg=>value...);
  $cim->GetInstance(arg=>value...); (get)
  $cim->ModifyInstance(arg=>value...); (put)
  $cim->CreateInstance(arg=>value...); (create)
  $cim->DeleteInstance(arg=>value...); (delete)
  $cim->GetClassInstancePaths(arg=>value...); (class_uris)
  $cim->GetClassInstancesWithPath(arg=>value...); (class_instances)
  $cim->GetReferencingInstancePaths(arg=>value...); (associations)
  $cim->GetReferencingInstancesWithPath(arg=>val...); (association_instances)
  $cim->GetAssociatedInstancePaths(arg=>value...); (associated)
  $cim->GetAssociatedInstancesWithPath(arg=>value...); (associated_instances)
  $cim->InvokeMethod(arg=>value...); (invoke)

DESCRIPTION

The DMTF::CIM class provides object-oriented access to a CIM schema and, when created using a protocol module such as DMTF::CIM::WSMan, permits the use of DSP0223 generic operations against a target.

INTERFACE

METHODS

instance_of( name );

Returns a new DMTF::CIM instance of CIM_System (the name is case insensitive). Refer to DMTF::CIM::Instance for details of the returned object.

class_tag_alias( class [, alias] );

Returns the first or adds a new UFcT (User-Friendly class Tag) alias for use in UFiPs (User-Friendly instance Paths). The first argument is the CIM class name in the normal capitalization (if the class is known, the capitalization is corrected if needed). After the alias is added, future UFiPs may include the specified tag. Aliases may not be changed, only added. Refer to DSP0215 for details on the UFiP syntax.

If the alias is not specified and the class cannot be resolved, returns the class name as translated.

resolve_target_class_tag( tag=>sometag [,assoc=>bool] [,uri=>instance_uri] [,via=>class])

Converts a UFcT to a CIM class name. Returns undef on failure. The first source of information is the class tag alias list. If the tag is not in this list, and a session is associated with the object, will attempt to use the GetClass() method to retrieve the class definition and add it to the internal mode. Failing this, will attempt to enumerate via association traversal using the rest of the arguments. as follows:

uri=>string

Specifies the WEBEM URI to use as the reference point. If the URI is a namespace URI (ie: no colon), association traversal will not be attempted. The default URI is '/interop'.

assoc=>bool (defaults to zero)

This boolean value indicates if the tag is an association class. If it is, GetReferencingInstancePaths() will be used. If not, GetAssociatedInstancePaths() will be.

via=>string

The class name of the association instance when assoc=>0 (ie: when GetAssociatedInstancePaths() is used).

If this fails as well, will attempt to use the GetClassInstancePaths() operation from the namespace specified in the uri argument then, if the GetClassInstancePaths() operation is not defined by the binding class, will use GetAllInstancePaths().

After any enumeration of this type, all returned class names will be cached as UFcTs so that the operation will not need to occur again.

UFiP_to_URI( UFiP, root_uri )

Converts a full UFiP (argument 1) into a WBEM URI using the GetReferencingInstancePaths() and GetAssociatedInstancePaths() methods (if available). The results are cached so that future lookups of the same path in the same context will not need to use the underlying protocol. The second argument is a WBEM URI to the root instance. If the second argument is unspecified, attempts to used the value cached for '/' in the URI cache.

For a UFiP which ends with a UFsT of '*', returns an arrayref.

clear_uri_cache()

Removes all entries from the URI cache used by the UFiP_to_URI() method.

cache_uri_path( path, uri );

Adds an entry to the URI cache. The first argument is the path and the second argument is the URI to cache.

parse_mof( path [, clear] )

Parsed a MOF file into an internal data model. If clear is false (the default) the current model is added to. If clear is true, the current model is deleted, and the MOf file loaded in its place.

GetClass( arg=>value... );
GetInstance( arg=>value... ); (get)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    InstancePath (uri)
    IncludedProperties (props)
ModifyInstance arg=>value... ); (put)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    ModifiedInstance (object)
    InstancePath (uri)
    IncludedProperties (props)
CreateInstance( arg=>value... ); (create)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    ClassPath (uri)
    NewInstance (object)
DeleteInstance( arg=>value... ); (delete)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    InstancePath (uri)
GetClassInstancePaths( arg=>value... ); (class_uris)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    EnumClassPath (uri)
GetClassInstancesWithPath( arg=>value... ); (class_instances)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    EnumClassPath (uri)
    IncludedProperties (props)
    ExcludeSubclassProperties (esp)
GetReferencingInstancePaths( arg=>value... ); (associations)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    SourceInstancePath (uri)
    AssociationClassName (via)
    AssociatedClassName (class)
    SourceRoleName (role)
    AssociatedRoleName (rrole)
GetReferencingInstancesWithPath( arg=>value... ); (association_instances)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    SourceInstancePath (uri)
    AssociationClassName (via)
    AssociatedClassName (class)
    SourceRoleName (role)
    AssociatedRoleName (rrole)
    IncludedProperties (props)
    ExcludeSubclassProperties (esp)
GetAssociatedInstancePaths( arg=>value... ); (associated)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    SourceInstancePath (uri)
    AssociationClassName (via)
    AssociatedClassName (class)
    SourceRoleName (role)
    AssociatedRoleName (rrole)
GetAssociatedInstancesWithPath( arg=>value... ); (associated_instances)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    SourceInstancePath (uri)
    AssociationClassName (via)
    AssociatedClassName (class)
    SourceRoleName (role)
    AssociatedRoleName (rrole)
    IncludedProperties (props)
    ExcludeSubclassProperties (esp)
InvokeMethod( arg=>value... ); (invoke)

Available args:

    IncludeClassOrigin (ico)
    IncludeQualifiers (iq)
    InstancePath (uri)
    MethodName (method)
    InParmValues (params)

These methods function as the documented Generic operation in DSP0223 available from the DMTF web site. The name in paranthesis after is a short alias.

OBJECTS

All returned objects will have a common set of methods.

parent

Returns the parent object which created this object.

name

Returns the name of the object as specified in the model.

is_array ( property )

Returns a true value equal to the length of the array if the named property is an array or 0 otherwise. A zero-length array returns '0 but true'

is_ref ( property )

Returns true if the named property is a reference or false otherwise.

map_value ( value )

If the object has a valuemap, will return the value from the map for a specific "raw" value.

unmap_value ( value )

If the object has a valuemap, will return the raw value associated with the map for a specific value. Will return the value unmodified if there is no match, but may return a range in the "X..Y" format where X and Y are optional minimum and maximum values respectively.

type ( property )

Returns the type name of the specified property. If the property is an array, will have '[]' appended. For properties which have no type information in the instance, the type is assumed to be 'string'.

CIM types as of this writing are:

uint8
uint16
uint32
uint64
sint8
sint16
sint32
sint64
real32
real64
string
char16
boolean
datetime

The name of the target class, or 'ref' is returned for references.

qualifier( name )

Returns the value of the qualifier with name.

Additionaly, some objects (properties and parameters) can have a value. Valued objects have the following additional methods:

value ( [ newvalue ] )

If the newvalue list is specified, sets the value to that. Returns the current mapped value. If the property is an array, and the method is used in a scalar context, the values are join(', ')ed.

The return value is has been passed through the map_value() method. When a value is set, it will first pass through the unmap_value() method. It is not reccomended to use value($new) for setting mapped values as some values may unmap to a range and cause an error.

raw_value ( [ newvalue ] )

If the newvalue list is specified, sets the value to that. Returns the current unmapped value. If the property is an array, and the method is used in a scalar context, the values are join(', ')ed.

DIAGNOSTICS

This module will carp() on errors and return undef or an empty list.

CONFIGURATION AND ENVIRONMENT

DMTF::CIM requires no configuration files or environment variables.

DEPENDENCIES

DMTF::CIM::Instance (available from the same location as this module)

DMTF::CIM::MOF (available from the same location as this module) is required to call the parse_mof() method.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-dmtf-cim@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Stephen James Hurd <shurd@broadcom.com>

LICENCE AND COPYRIGHT

Copyright (c) 2012, Broadcom Corporation <shurd@broadcom.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.