5. WBEM server API¶
The WBEM server API encapsulates certain functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace of the server, or the management profiles advertised by the server.
This chapter has the following sections:
- Example - An example on how to use the API.
- WBEMServer - The
WBEMServer
class serves as a general access point for clients to WBEM servers. It allows determining the Interop namespace of the server, or the advertised management profiles. - ValueMapping - The
ValueMapping
class maps corresponding values of the Values and ValueMap qualifiers of a CIM element and supports the translation of the actual value (often an integer) to the corresponding value of the Values qualifier.
Note
The WBEM server API has been introduced in v0.9.0 as experimental and has been declared final in 0.10.0.
5.1. Example¶
The following example code displays some information about a WBEM server:
from pywbem import WBEMConnection, WBEMServer, ValueMapping
def explore_server(server_url, username, password):
print("WBEM server URL:\n %s" % server_url)
conn = WBEMConnection(server_url, (username, password))
server = WBEMServer(conn)
print("Brand:\n %s" % server.brand)
print("Version:\n %s" % server.version)
print("Interop namespace:\n %s" % server.interop_ns)
print("All namespaces:")
for ns in server.namespaces:
print(" %s" % ns)
print("Advertised management profiles:")
org_vm = ValueMapping.for_property(server, server.interop_ns,
'CIM_RegisteredProfile', 'RegisteredOrganization')
for inst in server.profiles:
org = org_vm.tovalues(inst['RegisteredOrganization'])
name = inst['RegisteredName']
vers = inst['RegisteredVersion']
print(" %s %s Profile %s" % (org, name, vers))
Example output:
WBEM server URL:
http://0.0.0.0
Brand:
pegasus
Version:
2.12.0
Interop namespace:
root/PG_Interop
All namespaces:
root/PG_InterOp
root/PG_Internal
root/cimv2
root
Advertised management profiles:
SNIA Indication Profile 1.1.0
SNIA Indication Profile 1.2.0
SNIA Software Profile 1.1.0
SNIA Software Profile 1.2.0
SNIA Profile Registration Profile 1.0.0
SNIA SMI-S Profile 1.2.0
SNIA Server Profile 1.1.0
SNIA Server Profile 1.2.0
DMTF Profile Registration Profile 1.0.0
DMTF Indications Profile 1.1.0
5.2. WBEMServer¶
-
class
pywbem.
WBEMServer
(conn)[source]¶ A representation of a WBEM server that serves as a general access point to a client.
It supports determining the Interop namespace of the server, all namespaces, its brand and version, the advertised management profiles and finally allows to retrieve the central instances of a management profile with one method invocation regardless of whether the profile implementation chose the central or scoping class profile advertisement methodology (see DSP1033).
It also provides functions to subscribe for indications.
Parameters: conn ( WBEMConnection
) – Connection to the WBEM server.-
INTEROP_NAMESPACES
= ['interop', 'root/interop', 'root/PG_Interop']¶ A class variable with the possible names of Interop namespaces that should be tried when determining the Interop namespace on the WBEM server.
-
NAMESPACE_CLASSNAMES
= ['CIM_Namespace', '__Namespace']¶ A class variable with the possible names of CIM classes for representing CIM namespaces, that should be tried when determining the namespaces on the WBEM server.
-
__repr__
()[source]¶ Return a representation of the
WBEMServer
object with all attributes, that is suitable for debugging.
-
conn
¶ The connection to the WBEM server, as a
WBEMConnection
object.
-
interop_ns
¶ The name of the Interop namespace of the WBEM server, as a string.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
- Exceptions raised by
-
namespace_classname
¶ The name of the CIM class that was found to represent the CIM namespaces of the WBEM server, as a string.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
- Exceptions raised by
-
namespaces
¶ A list with the names of all namespaces of the WBEM server, each list item being a string.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Namespace class could not be determined.
- Exceptions raised by
-
brand
¶ Brand of the WBEM server, as a string.
The brand string will be one of the following:
"OpenPegasus"
, for OpenPegasus"SFCB"
, for SFCB- First word of the value of the ElementName property of the CIM_ObjectManager instance, for any other WBEM servers.
"unknown"
, if the ElementName property is Null.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
-
version
¶ Version of the WBEM server, as a string. None, if the version cannot be determined.
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.CIMError
– CIM_ERR_NOT_FOUND, Unexpected number of CIM_ObjectManager instances.
- Exceptions raised by
-
profiles
¶ List of management profiles advertised by the WBEM server, each list item being a
CIMInstance
object representing a CIM_RegisteredProfile instance.Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.
- Exceptions raised by
-
get_selected_profiles
(registered_org=None, registered_name=None, registered_version=None)[source]¶ List of management profiles advertised by the WBEM server and filtered by the input parameters for registered_org, registered_name, and registered_version parameters. Each list item is a
CIMInstance
object representing a CIM_RegisteredProfile instance.Parameters: - profile_org (string) – the RegisteredOrganization to match the RegisteredOrganization of the profile. This match is case sensitive. If None, this parameter is ignored in the filter
- profile_name (string) – the RegisteredName. This match is case sensitive If None, this parameter is ignored in the filter
- profile_version (string) – the RegisteredVersion. This match is case sensitive. If None, this parameter is ignored in the filter
Raises: - Exceptions raised by
WBEMConnection
. CIMError
– CIM_ERR_NOT_FOUND, Interop namespace could not be determined.KeyError
– If an instance in the list of profiles is incomplete and does not include the required properties.
-
get_central_instances
(profile_path, central_class=None, scoping_class=None, scoping_path=None)[source]¶ Determine the central instances for a management profile, and return their instance paths as a list of
CIMInstanceName
objects.This method supports the following profile advertisement methodologies (see DSP1033), and attempts them in this order:
- GetCentralInstances methodology (new in DSP1033 1.1)
- Central class methodology
- Scoping class methodology
Use of the scoping class methodology requires specifying the central class, scoping class and scoping path defined by the profile. If any of them is None, this method will attempt only the GetCentralInstances and central class methodologies, but not the scoping class methodology. If using these two methodologies does not result in any central instances, and the scoping class methodology cannot be used, an exception is raised.
The scoping path is a directed traversal path from the central instances to the scoping instances. Its first list item is always the association class name of the traversal hop starting at the central instances. For each further traversal hop, the list contains two more items: The class name of the near end of that hop, and the class name of the traversed association. As a result, the class names of the central instances and scoping instances are not part of the list.
Example for a 1-hop traversal:
- central class:
"CIM_Fan"
- scoping path:
["CIM_SystemDevice"]
- scoping class:
"CIM_ComputerSystem"
Example for a 2-hop traversal:
- central class:
"CIM_Sensor"
- scoping path:
["CIM_AssociatedSensor", "CIM_Fan", "CIM_SystemDevice"]
- scoping class:
"CIM_ComputerSystem"
Parameters: - profile_path (
CIMInstanceName
) – Instance path of CIM_RegisteredProfile instance representing the management profile. - central_class (string) –
Class name of central class defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- scoping_class (string) –
Class name of scoping class defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
- scoping_path (list of string) –
Scoping path defined by the management profile.
Will be ignored, unless the profile is a component profile and its implementation supports only the scoping class methodology. None will cause the scoping class methodology not to be attempted.
Returns: List of
CIMInstanceName
objects representing the instance paths of the central instances of the management profile.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– Various errors in scoping path traversal.TypeError
– profile_path must be a CIMInstanceName.
-
5.3. ValueMapping¶
-
class
pywbem.
ValueMapping
[source]¶ A utility class that translates the values of a corresponding integer-typed CIM element (property, method, parameter) that is qualified with the ValueMap and Values qualifiers, from the element value space into into its Values qualifier space.
This is done by retrieving the CIM class definition defining the CIM element in question, and by inspecting its ValueMap and Values qualifiers.
The actual translation of the values is performed by the
tovalues()
method.Instances of this class should be created through one of the factory class methods:
for_property()
,for_method()
, orfor_parameter()
.Value ranges (
"2..4"
) and the indicator for unclaimed values (".."
) in the ValueMap qualifier are supported.Example: Given the following definition of a property in MOF:
[ValueMap{ "0", "2..4", "..6", "7..", "9", ".." }, Values{ "zero", "two-four", "five-six", "seven-eight", "nine", "unclaimed"}] uint16 MyProp;
The following code will create a value mapping for this property and will print a few integer values and their Values strings:
vm = pywbem.ValueMapping.for_property(server, namespace, classname, "MyProp") for value in range(0, 12): print("value: %s, Values string: %r" % (value, vm.tovalues(value)) Results: value: 0, Values string: 'zero' value: 1, Values string: 'unclaimed' value: 2, Values string: 'two-four' value: 3, Values string: 'two-four' value: 4, Values string: 'two-four' value: 5, Values string: 'five-six' value: 6, Values string: 'five-six' value: 7, Values string: 'seven-eight' value: 8, Values string: 'seven-eight' value: 9, Values string: 'nine' value: 10, Values string: 'unclaimed' value: 11, Values string: 'unclaimed'
-
classmethod
for_property
(server, namespace, classname, propname)[source]¶ Factory method that returns a new
ValueMapping
instance corresponding to a CIM property.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMServer
) – The WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the property. The property can be defined in that class or inherited into that class.
- propname (string) – Name of the CIM property that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– No Values qualifier defined.TypeError
– The property is not integer-typed.
- server (
-
classmethod
for_method
(server, namespace, classname, methodname)[source]¶ Factory method that returns a new
ValueMapping
instance corresponding to a CIM method.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMServer
) – The WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
- methodname (string) – Name of the CIM method that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– No Values qualifier defined.TypeError
– The method is not integer-typed.
- server (
-
classmethod
for_parameter
(server, namespace, classname, methodname, parametername)[source]¶ Factory method that returns a new
ValueMapping
instance corresponding to a CIM parameter.If a Values qualifier is defined but no ValueMap qualifier, a default of 0-based consecutive numbers is applied (that is the default defined in DSP0004).
Parameters: - server (
WBEMServer
) – The WBEM server containing the namespace. - namespace (string) – Name of the CIM namespace containing the class.
- classname (string) – Name of the CIM class exposing the method. The method can be defined in that class or inherited into that class.
- methodname (string) – Name of the CIM method that has the parameter.
- parametername (string) – Name of the CIM parameter that defines the Values / ValueMap qualifiers.
Returns: The new
ValueMapping
instance.Raises: - Exceptions raised by
WBEMConnection
. ValueError
– No Values qualifier defined.TypeError
– The parameter is not integer-typed.
- server (
-
element
¶ Return the corresponding CIM element of this instance, as a CIM object (
CIMProperty
,CIMMethod
, orCIMParameter
).
-
tovalues
(element_value)[source]¶ Return the Values string for an element value, based on the ValueMap / Values qualifiers of the corresponding CIM element.
Parameters: element_value (integer or
CIMInt
) – The value of the CIM element.Returns: The Values string for the element value.
Return type: Raises: ValueError
– Element value outside of the set defined by ValueMap.ValueError
– No Values qualifier defined.ValueError
– Invalid ValueMap entry.TypeError
– The CIM element is not integer-typed.TypeError
– Element value is not an integer type.
-
classmethod