Distributed Management Task Force, Inc.
Specification for CIM Operations over HTTP
Version 1.0
August 11th, 1999
This list shows the names of the companies and organizations that have participated in the Distributed Management Task Force - CIM TC XML Sub-Committee whose contributions made this document possible.
| Version 1.0a | May 1st, 1999 | First Draft Release |
| Version 1.0b | May 7th, 1999 | Updates after first Working Group Review |
| Version 1.0c | May 11th, 1999 | Further updates |
| Version 1.0d | May 25th, 1999 | Changed LOCAL to PROPAGATED Added VALUETYPE attribute to KEYVALUE |
| Version 1.0e | May 28th, 1999 |
AssociationTraversal dependent on BasicRead. not
BasicWrite |
| Version 1.0 | June 2nd, 1999 |
Clarified meaning of default intrinsic parameter value |
| July 6th, 1999 |
Updated examples to reflect DTD changes | |
| July 20th, 1999 |
Remove IncludeClassOrigin and IncludeQualifiers
parameters from ExecQuery. |
The Common Information Model (CIM) [1] is an object-oriented information model defined by the Distributed Management Task Force (DMTF) which provides a conceptual framework for describing management data.
The Hypertext Transfer Protocol (HTTP) [6,7,10] is an application-level protocol for distributed, collaborative, hypermedia information systems. It is a generic stateless protocol which can be used for many tasks through extension of its request methods, error codes and headers.
The Extensible Markup Language (XML) [3] is a simplified subset of SGML that offers powerful and extensible data modeling capabilities. An XML Document is a collection of data represented in XML. An XML Schema is a grammar that describes the structure of an XML Document.
This document defines a mapping of CIM Operations onto HTTP that allows implementations of CIM to interoperate in an open, standardized manner. It utilizes the CIM XML DTD [2,11] that defines the XML Schema for CIM objects and messages.
This document defines a mapping of CIM operations onto HTTP that allows implementations of CIM to operate in an open, standardized manner. It also defines the notion of conformance in the context of this mapping, and describes what behavior an implementation of CIM must exhibit in order to be described as a conforming CIM implementation.
The remainder of this document is structured as follows.
There are potentially many different ways in which CIM operations could be represented within XML, and those operations encapsulated within HTTP messages. In the interests of interoperability between different implementations of CIM there is an obvious requirement for standardization of both the XML representation and the HTTP encapsulation. The XML representation is defined in [2,11]. This document utilizes that representation to defines the HTTP encapsulation.
The following criteria have been applied to the representation of CIM Operations in XML [2,11]:
The following criteria have been applied to the HTTP encapsulation of CIM Operations herein:
The key phrases and words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL in this document are to be interpreted as described in RFC 2119 [8].
This specification uses the same notational conventions and basic parsing constructs as defined in [7].
This document uses a number of stylistic conventions to highlight examples and definitions.
Examples are displayed in this fashion:
| This is an example |
Definitions are illustrated thusly:
| This is a definition |
This specification defines all interactions between CIM entities as Operations. CIM Operations belong to a larger category known as CIM Messages (currently all Messages are Operations, but in future this may not be true).
This section describes the syntax and semantics of CIM Operations in a manner independent of the encapsulation of such operations within a particular protocol (such as HTTP).
XML is used as the basis for this description, and in particular the CIM XML DTD [2,11].
Where this document makes reference to the concept of a Well-formed or Valid XML documents, the meaning intended is the standard one defined in [3].
XML DTDs are restricted to these terms to describe XML documents, but this document requires a further classification of an XML document with respect to a DTD. Henceforth the term loosely valid is defined to apply to an XML Document with the following characteristics:
In effect, a loosely valid document is one which is valid with respect to the CIM XML DTD apart from having additional attributes or elements not defined by that DTD. The concept is very similar to that of an open content model as defined by the working draft on XML Schemas [21], expressed within the more limited scope of DTDs. One corollary of this definition is that any XML document that is valid with respect to the CIM XML DTD is also loosely valid.
The motivation for introducing this class of XML Documents is to relax the restrictions on a CIM Client or a CIM Server when parsing received XML documents defined within the scope of this mapping. It is recognized that not all Clients (respectively, Servers) should be required to validate each received Operation Response Message (respectively, Operation Request Message) as this would place too great a processing burden on the validating entity at the expense of footprint and performance, most notably in communication between robust and conformant implementations of this mapping.
Instead the following requirements are made by this specification:
The behavior of a CIM Server with respect to a received Operation Request Message is covered in detail in the section on Errors and Status Codes .
The CIM XML DTD [2,11] defines a subelement under the root <CIM> element called <MESSAGE>, which contains one of the following subelements:
In the remainder of this document:
An Operation Request Message MUST contain a non-empty value for the ID attribute of the <MESSAGE> element. The corresponding Operation Response Message MUST supply the same value for that attribute. Clients SHOULD employ a message ID scheme that minimizes the chance of receiving a stale Operation Response Message.
Any Operation Request Message or Operation Response Message conforming to this specification MUST specify a value of "1.0" for the PROTOCOLVERSION attribute of the <MESSAGE> element.
An Operation Response Message sent in response to an Operation Request Message MUST:
A Simple Operation Request is an Operation Request Message that contains a <SIMPLEREQ> subelement. A Simple Operation Response is an Operation Response Message that contains a <SIMPLERSP> subelement.
A Multiple Operation Request is an Operation Request Message that contains a <MULTIREQ> subelement. A Multiple Operation Response is an Operation Response Message that contains a <MULTIRSP> subelement.
All CIM Operation requests defined for this mapping are defined as invocations of one or more methods. A method may be either:
Intrinsic methods are further characterized by the fact that they are made against a CIM Namespace. Extrinsic methods are invoked on a CIM Class (if static) or Instance (otherwise). Intrinsic methods are defined in the section Intrinsic Methods
An extrinsic method call is represented in XML by the <METHODCALL> element, and the response to that call represented by the <METHODRESPONSE> element.
An intrinsic method call is represented in XML by the <IMETHODCALL> element, and the response to that call represented by the <IMETHODRESPONSE> element.
An Input parameter is one with an IN Qualifier (with value true) in the Method definition. An Output parameter is one with an OUT Qualifier (with value true) in the Method definition. An Optional parameter is one with an OPTIONAL Qualifier in the Method definition. A parameter may be both an Input and Output parameter.
The <METHODCALL> or <IMETHODCALL> element serves to name the method to be invoked and supply any Input parameters to the method call. Note that:
The <METHODRESPONSE> or <IMETHODRESPONSE> element defines either an <ERROR> or a (possibly optional) return value and output parameters (i.e. one decorated with the OUT Qualifier in the method definition). In the latter case:
The method invocation process may be thought of as:
A simple operation is defined as one that requires the invocation of a single method. A simple operation request is represented by a <SIMPLEREQ> element, and a simple operation response by a <SIMPLERSP> element.
If the method is intrinsic then the <SIMPLEREQ> MUST contain a <IMETHODCALL> element, which in turn contains a <LOCALNAMESPACEPATH> subelement identifying the local CIM Namespace against which the method is to be executed. If the method is extrinsic then the <SIMPLEREQ> element MUST contain a <METHODCALL> element which in turn contains either:
A multiple operation is defined as one that requires the invocation of more than one method. A multiple operation request is represented by a <MULTIREQ> element, and a multiple operation response by a <MULTIRSP> element.
A <MULTIREQ> (respectively, <MULTIRSP>) element is a sequence of two or more <SIMPLEREQ> (respectively, <SIMPLERSP>) elements.
A <MULTIRSP> element MUST contain a <SIMPLERSP> element for every <SIMPLEREQ> element in the corresponding Multiple Operation Response, and these <SIMPLERSP> elements MUST be in the same order as their <SIMPLEREQ> counterparts (so the first <SIMPLERSP> in the response corresponds to the first <SIMPLEREQ> in the request, and so forth).
Multiple Operations provide a convenient mechanism whereby multiple method invocations may be batched into a single HTTP Message, thereby reducing the number of roundtrips between a CIM Client and a CIM Server and allowing the CIM Server to make certain internal optimizations should it choose so to do. Note that Multiple Operations do not confer any transactional capabilities in the processing of the request (for example, there is no requirement that the CIM Server guarantee that the constituent method calls either all failed or all succeeded, only that the entity make a "best effort" to process the operation).
Not all CIM Servers support Multiple Operations; the means by which they declare support for this feature is defined in the section on Determining CIM Server Capabilities.
This section defines the status codes that may be returned by a conforming CIM Server application as the value of the CODE attribute of an <ERROR> subelement within a <METHODRESPONSE> or <IMETHODRESPONSE> element.
The symbolic names defined in the table below do not appear on the wire. They are used here solely as a convenient way to refer to an error in other parts of this specification.
Not all methods would be expected to return all the status codes listed below. For intrinsic methods, the relevant section on each method in this specification defines the expected error codes to be returned. For extrinsic methods the specification of which of the following codes can be used is described in the section on Extrinsic Method Invocation .
|
Symbolic Name |
CODE |
Definition |
| CIM_ERR_FAILED | 1 | A general error occured that is not covered by a more specific error code |
| CIM_ERR_ACCESS_DENIED | 2 | Access to a CIM resource was not available to the client |
| CIM_ERR_INVALID_NAMESPACE | 3 | The target namespace does not exist |
| CIM_ERR_INVALID_PARAMETER | 4 | One or more parameter values passed to the method were invalid |
| CIM_ERR_INVALID_CLASS | 5 | The specified Class does not exist |
| CIM_ERR_NOT_FOUND | 6 | The requested object could not be found |
| CIM_ERR_NOT_SUPPORTED | 7 | The requested operation is not supported |
| CIM_ERR_CLASS_HAS_CHILDREN | 8 | Operation cannot be carried out on this class since it has subclasses |
| CIM_ERR_CLASS_HAS_INSTANCES | 9 | Operation cannot be carried out on this class since it has instances |
| CIM_ERR_INVALID_SUPERCLASS | 10 | Operation cannot be carried out since the specified superclass does not exist |
| CIM_ERR_ALREADY_EXISTS | 11 | Operation cannot be carried out because an object already exists |
| CIM_ERR_NO_SUCH_PROPERTY | 12 | The specified Property does not exist |
| CIM_ERR_TYPE_MISMATCH | 13 | The value supplied is incompatible with the type |
| CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED | 14 | The query language is not recognized or supported |
| CIM_ERR_INVALID_QUERY | 15 | The query is not valid for the specified query language |
| CIM_ERR_METHOD_NOT_AVAILABLE | 16 | The extrinsic Method could not be executed |
| CIM_ERR_METHOD_NOT_FOUND | 17 | The specified extrinsic Method does not exist |
This section describes the Intrinsic methods that are defined outside of schema for the purposes of CIM operations. These methods can only be called on a CIM Namespace, rather than a CIM Class or CIM Instance.
The following intrinsic methods are defined by this specification:
The convention used in the following subsections to define the signatures of the intrinsic methods is a pseudo-MOF notation that extends the standard MOF BNF [1] for describing CIM Methods with a number of pseudo parameter types (which are indicated by being placed within "<" and ">" characters).
This notation admits of the decoration of parameters with a number of pseudo-qualifiers (IN, OPTIONAL and NULL) to define their invocation semantics. It is important to understand that these qualifiers are used for descriptional purposes only within the scope of this specification, and in particular a CIM Client MUST NOT specify them in intrinsic method invocations.
This notation uses the IN qualifier to denote that the parameter is an input parameter.
This notation uses the OPTIONAL qualifier to indicate paramaters whose presence is not mandatory, and declares default values for optional method parameters using similar notation employed for default property values in MOF.
A CIM Client MAY omit an optional parameter in the case that the required value is the specified default, by not specifying an <IPARAMVALUE> element for that parameter. It MUST NOT omit any parameter that is not marked as optional.
This notation uses the NULL qualifier to indicate parameters whose values may be be specified as NULL in a method call. A NULL (unassigned) value for a parameter is specified by an <IPARAMVALUE> element with no subelement. For parameters which do not possess the NULL qualifier, the CIM Client MUST specify a value for the parameter by including a suitable subelement for the <IPARAMVALUE> element for that parameter.
All parameters MUST be named uniquely, and MUST correspond to a valid parameter name for that method as described by this specification. The order of the parameters is not significant.
The non-NULL values of intrinsic method parameters or return values which are modelled as standard CIM types (such as string and boolean, or arrays thereof) are represented as follows:
The following table describes how each of the pseudo-types used by the intrinsic methods MUST be mapped to an XML element described in [2] in the context of both a parameter value (subelement of <IPARAMVALUE>) and a return value (subelement of <IRETURNVALUE>).
|
Type |
XML Element |
| <object> | (VALUE.OBJECT|VALUE.OBJECTWITHLOCALPATH|VALUE.OBJECTWITHPATH) |
| <class> | CLASS |
| <instance> | INSTANCE |
| <className> | CLASSNAME |
| <namedInstance> | VALUE.NAMEDINSTANCE |
| <instanceName> | INSTANCENAME |
| <objectWithPath> |
VALUE.OBJECTWITHPATH |
| <objectName> | (CLASSNAME|INSTANCENAME) |
| <propertyValue> | (VALUE|VALUE.ARRAY|VALUE.REFERENCE) |
| <qualifierDecl> | QUALIFIER.DECLARATION |
This operation is used to return a single CIM Class from the target Namespace.
| GetClass |
| <class>
GetClass ( [IN] <className> ClassName, [IN,OPTIONAL] boolean LocalOnly = true, [IN,OPTIONAL] boolean IncludeQualifiers = true, [IN,OPTIONAL] boolean IncludeClassOrigin = false, [IN,OPTIONAL,NULL] string PropertyList [] = NULL ) |
The ClassName input parameter defines the name of the Class to be retrieved.
If the LocalOnly input parameter is true, this specifies that only CIM Elements (properties, methods and qualifiers) overriden within the definition of the Class are returned [1]. If false, all elements are returned. This parameter therefore effects a CIM Server-side mechanism to filter certain elements of the returned object based on whether or not they have been propagated from the parent Class (as defined by the PROPAGATED attribute).
If the IncludeQualifiers input parameter is true, this specifies that all Qualifiers for that Class (including Qualifiers on the Class and on any returned Properties, Methods or Method Parameters) MUST be included as <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are present in the returned Class.
If the IncludeClassOrigin input parameter is true, this specifies that the CLASSORIGIN attribute MUST be present on all appropriate elements in the returned Class. If false, no CLASSORIGIN attributes are present in the returned Class.
If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. The returned Class MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true this acts as an additional filter on the set of Properties returned (for example, if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to the requested Class, then it will not be included in the response). If the PropertyList input parameter is an empty array this signifies that no Properties are included in the response. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in the response.
If the PropertyList contains duplicate elements, the Server MUST ignore the duplicates but otherwise process the request normally. If the PropertyList contains elements which are invalid Property names for the target Class, the Server MUST ignore such entries but otherwise process the request normally.
If successful, the return value is a single CIM Class.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to return a single CIM Instance from the target Namespace.
| GetInstance |
| <instance> GetInstance ( [IN] <instanceName> InstanceName, [IN,OPTIONAL] boolean LocalOnly = true, [IN,OPTIONAL] boolean IncludeQualifiers = false, [IN,OPTIONAL] boolean IncludeClassOrigin = false, [IN,OPTIONAL,NULL] string PropertyList [] = NULL ) |
The InstanceName input parameter defines the name of the Instance to be retrieved.
If the LocalOnly input parameter is true, this specifies that only elements (properties and qualifiers) overriden within the definition of the Instance are returned [1]. If false, all elements are returned. This parameter therefore effects a CIM Server-side mechanism to filter certain elements of the returned object based on whether or not they have been propagated from the parent Class (as defined by the PROPAGATED attribute).
If the IncludeQualifiers input parameter is true, this specifies that all Qualifiers for that Instance (including Qualifiers on the Instance and on any returned Properties) MUST be included as <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are present in the returned Instance.
If the IncludeClassOrigin input parameter is true, this specifies that the CLASSORIGIN attribute MUST be present on all appropriate elements in the returned Instance. If false, no CLASSORIGIN attributes are present in the returned Instance.
If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. The returned Instance MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true this acts as an additional filter on the set of Properties returned (for example, if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to the requested Instance, then it will not be included in the response). If the PropertyList input parameter is an empty array this signifies that no Properties are included in the response. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in the response.
If the PropertyList contains duplicate elements, the Server MUST ignore the duplicates but otherwise process the request normally. If the PropertyList contains elements which are invalid Property names for the target Instance, the Server MUST ignore such entries but otherwise process the request normally.
If successful, the return value is a single CIM Instance.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to delete a single CIM Class from the target Namespace.
| DeleteClass |
| void DeleteClass ( [IN] <className> ClassName ) |
The ClassName input parameter defines the name of the Class to be deleted.
If successful, the specified Class (including any subclasses and any instances) MUST have been removed by the CIM Server. The operation MUST fail if any one of these objects cannot be deleted.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to delete a single CIM Instance from the target Namespace.
| DeleteInstance |
| void DeleteInstance ( [IN] <instanceName> InstanceName ) |
The InstanceName input parameter defines the name (model path) of the Instance to be deleted.
If successful, the specified Instance MUST have been removed by the CIM Server.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to create a single CIM Class in the target Namespace. The Class MUST NOT already exist.
| CreateClass |
| void CreateClass ( [IN] <class> NewClass ) |
The NewClass input parameter defines the new Class. The proposed definition MUST be a correct Class definition according to the CIM specification [1].
In processing the creation of the new Class, the following rules MUST be conformed to by the CIM Server:
If successful, the specified Class MUST have been created by the CIM Server.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to create a single CIM Instance in the target Namespace. The Instance MUST NOT already exist.
| CreateInstance |
| <instanceName> CreateInstance ( [IN] <instance> NewInstance ) |
The NewInstance input parameter defines the new Instance. The proposed definition MUST be a correct Instance definition for the underlying CIM Class according to the CIM specification [1].
In processing the creation of the new Instance, the following rules MUST be conformed to by the CIM Server:
If successful, the return value defines the object path of the new CIM Instance relative to the target Namespace (i.e. the Model Path as defined by [1]), created by the CIM Server. It is returned in case one or more of the new keys of the Instance are allocated dynamically during the creation process rather than specified in the request.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to modify an existing CIM Class in the target Namespace. The Class MUST already exist.
| ModifyClass |
| void ModifyClass ( [IN] <class> ModifiedClass ) |
The ModifiedClass input parameter defines the set of changes (which MUST be correct amendments to the CIM Class as defined by the CIM Specification [1]) to be made to the current class definition.
In processing the modifcation of the Class, the following rules MUST be conformed to by the CIM Server:
If successful, the specified Class MUST have been updated by the CIM Server.
The request to modify the Class MUST fail if the Server cannot update any existing Subclasses or Instances of that Class in a consistent manner.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to modify an existing CIM Instance in the target Namespace. The Instance MUST already exist.
| ModifyInstance |
| void ModifyInstance ( [IN] <namedInstance> ModifiedInstance ) |
The ModifiedInstance input parameter identifies the name of the Instance to be modified, and defines the set of changes (which MUST be correct amendments to the Instance as defined by the CIM Specification [1]) to be made to the current Instance definition.
In processing the modifcation of the Instance, the following rules MUST be conformed to by the CIM Server:
If successful, the specified Instance MUST have been updated by the CIM Server.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate subclasses of a CIM Class in the target Namespace.
| EnumerateClasses |
| <class>* EnumerateClasses ( [IN,OPTIONAL,NULL] <className> ClassName=NULL, [IN,OPTIONAL] boolean DeepInheritance = false, [IN,OPTIONAL] boolean LocalOnly = true, [IN,OPTIONAL] boolean IncludeQualifiers = true, [IN,OPTIONAL] boolean IncludeClassOrigin = false ) |
The ClassName input parameter defines the Class that is the basis for the enumeration.
If the DeepInheritance input parameter is true, this specifies that all subclasses of the specified Class should be returned (if the ClassName input parameter is absent, this implies that all Classes in the target Namespace should be returned). If false, only immediate child subclasses are returned (if the ClassName input parameter is NULL, this implies that all base Classes in the target Namespace should be returned).
If the LocalOnly input parameter is true, it specifies that, for each returned Class, only elements (properties, methods and qualifiers) overriden within the definition of that Class are included [1]. If false, all elements are returned. This parameter therefore effects a CIM Server-side mechanism to filter certain elements of the returned object based on whether or not they have been propagated from the parent Class (as defined by the PROPAGATED attribute).
If the IncludeQualifiers input parameter is true, this specifies that all Qualifiers for each Class (including Qualifiers on the Class and on any returned Properties, Methods or Method Parameters) MUST be included as <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are present in each returned Class.
If the IncludeClassOrigin input parameter is true, this specifies that the CLASSORIGIN attribute MUST be present on all appropriate elements in each returned Class. If false, no CLASSORIGIN attributes are present in each returned Class.
If successful, the method returns zero or more Classes that meet the required criteria.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate the names of subclasses of a CIM Class in the target Namespace.
| EnumerateClassNames |
| <className>* EnumerateClassNames ( [IN,OPTIONAL,NULL] <className> ClassName = NULL, [IN,OPTIONAL] boolean DeepInheritance = false ) |
The ClassName input parameter defines the Class that is the basis for the enumeration.
If the DeepInheritance input parameter is true, this specifies that the names of all subclasses of the specified Class should be returned (if the ClassName input parameter is absent, this implies that the names of all Classes in the target Namespace should be returned). If false, only the names of immediate child subclasses are returned (if the ClassName input parameter is NULL, this implies that the names of all base Classes in the target Namespace should be returned).
If successful, the method returns zero or more names of Classes that meet the requested criteria.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate instances of a CIM Class in the target Namespace.
| EnumerateInstances |
| <namedInstance>* EnumerateInstances ( [IN] <className> ClassName, [IN,OPTIONAL] boolean LocalOnly = true, [IN,OPTIONAL] boolean DeepInheritance = true, [IN,OPTIONAL] boolean IncludeQualifiers = false, [IN,OPTIONAL] boolean IncludeClassOrigin = false, [IN,OPTIONAL,NULL] string PropertyList [] = NULL ) |
The ClassName input parameter defines the Class that is the basis for the enumeration.
If the LocalOnly input parameter is true, this specifies that, for each returned Instance, only elements (properties and qualifiers) overriden within the definition of that Instance are included [1]. If false, all elements are returned. This parameter therefore effects a CIM Server-side mechanism to filter certain elements of the returned object based on whether or not they have been propagated from the parent Class (as defined by the PROPAGATED attribute).
If the DeepInheritance input parameter is true, this specifies that, for each returned Instance of the Class, all properties of the Instance MUST be present (subject to constraints imposed by the other parameters), including any which were added by subclassing the specified Class. If false, each returned Instance includes only properties defined for the specified Class.
If the IncludeQualifiers input parameter is true, this specifies that all Qualifiers for each Instance (including Qualifiers on the Instance and on any returned Properties) MUST be included as <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are present in each returned Instance.
If the IncludeClassOrigin input parameter is true, this specifies that the CLASSORIGIN attribute MUST be present on all appropriate elements in each returned Instance. If false, no CLASSORIGIN attributes are present in each returned Instance.
If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. Each returned Instance MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true (or DeepInheritance is specified as false) this acts as an additional filter on the set of Properties returned (for example, if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to a returned Instance, then it will not be included in that Instance). If the PropertyList input parameter is an empty array this signifies that no Properties are included in each returned Instance. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in each returned Instance.
If the PropertyList contains duplicate elements, the Server MUST ignore the duplicates but otherwise process the request normally. If the PropertyList contains elements which are invalid Property names for any target Instance, the Server MUST ignore such entries but otherwise process the request normally.
If successful, the method returns zero or more named Instances that meet the required criteria.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate the names (model paths) of the instances of a CIM Class in the target Namespace.
| EnumerateInstanceNames |
| <instanceName>* EnumerateInstanceNames ( [IN] <className> ClassName ) |
The ClassName input parameter defines the Class that is the basis for the enumeration.
If successful, the method returns zero or more names of Instances (model paths) that meet the requsted criteria.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to execute a query against the target Namespace.
| ExecQuery |
| <object>* ExecQuery ( [IN] string QueryLanguage, [IN] string Query ) |
The QueryLanguage input parameter defines the query language in which the Query parameter is expressed.
The Query input parameter defines the query to be executed.
Neither the Query language nor the format of the Query are defined by this specification. It is anticipated that Query languages will be submitted to the DMTF as separate proposals.
A mechanism whereby CIM Servers can declare which query languages they support (if any) is defined in Determining CIM Server Capabilities.
If successful, the method returns zero or more CIM Classes or Instances that correspond to the results set of the query.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate CIM Objects (Classes or Instances) that are associated to a particular source CIM Object.
| Associators |
| <objectWithPath>*
Associators ( [IN] <objectName> ObjectName, [IN,OPTIONAL,NULL] <className> AssocClass = NULL, [IN,OPTIONAL,NULL] <className> ResultClass = NULL, [IN,OPTIONAL,NULL] string Role = NULL, [IN,OPTIONAL,NULL] string ResultRole = NULL, [IN,OPTIONAL] boolean IncludeQualifiers = false, [IN,OPTIONAL] boolean IncludeClassOrigin = false, [IN,OPTIONAL,NULL] string PropertyList [] = NULL ) |
The ObjectName input parameter defines the source CIM Object whose associated Objects are to be returned. This may be either a Class name or Instance name (model path).
The AssocClass input parameter, if not NULL, MUST be a valid CIM Association Class name. It acts as a filter on the returned set of Objects by mandating that each returned Object MUST be associated to the source Object via an Instance of this Class or one of its subclasses.
The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It acts as a filter on the returned set of Objects by mandating that each returned Object MUST be either an Instance of this Class (or one of its subclasses) or be this Class (or one of its subclasses).
The Role input parameter, if not NULL, MUST be a valid Property name. It acts as a filter on the returned set of Objects by mandating that each returned Object MUST be associated to the source Object via an Association in which the source Object plays the specified role (i.e. the name of the Property in the Association Class that refers to the source Object MUST match the value of this parameter).
The ResultRole input parameter, if not NULL, MUST be a valid Property name. It acts as a filter on the returned set of Objects by mandating that each returned Object MUST be associated to the source Object via an Association in which the returned Object plays the specified role (i.e. the name of the Property in the Association Class that refers to the returned Object MUST match the value of this parameter).
If the IncludeQualifiers input parameter is true, this specifies that all Qualifiers for each Object (including Qualifiers on the Object and on any returned Properties) MUST be included as <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are present in each returned Object.
If the IncludeClassOrigin input parameter is true, this specifies that the CLASSORIGIN attribute MUST be present on all appropriate elements in each returned Object. If false, no CLASSORIGIN attributes are present in each returned Object.
If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. Each returned Object MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true (or DeepInheritance is specified as false) this acts as an additional filter on the set of Properties returned (for example, if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to a returned Instance, then it will not be included in that Instance). If the PropertyList input parameter is an empty array this signifies that no Properties are included in each returned Object. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in each returned Object.
If the PropertyList contains duplicate elements, the Server MUST ignore the duplicates but otherwise process the request normally. If the PropertyList contains elements which are invalid Property names for any target Object, the Server MUST ignore such entries but otherwise process the request normally.
Clients SHOULD NOT explicitly specify properties in the PropertyList parameter unless they have specified a non-NULL value for the ResultClass parameter.
If successful, the method returns zero or more CIM Classes or Instances meeting the requested criteria. Since it is possible for CIM Objects from different hosts or namespaces to be associated, each returned Object includes location information.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate the names of CIM Objects (Classes or Instances) that are associated to a particular source CIM Object.
| AssociatorNames |
| <objectPath>* AssociatorNames ( [IN] <objectName> ObjectName, [IN,OPTIONAL,NULL] <className> AssocClass = NULL, [IN,OPTIONAL,NULL] <className> ResultClass = NULL, [IN,OPTIONAL,NULL] string Role = NULL, [IN,OPTIONAL,NULL] string ResultRole = NULL ) |
The ObjectName input parameter defines the source CIM Object whose associated names are to be returned. This is either a Class name or Instance name (model path).
The AssocClass input parameter, if not NULL, MUST be a valid CIM Association Class name. It acts as a filter on the returned set of names by mandating that each returned name identifies an Object that MUST be associated to the source Object via an Instance of this Class or one of its subclasses.
The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It acts as a filter on the returned set of names by mandating that each returned name identifies an Object that MUST be either an Instance of this Class (or one of its subclasses) or be this Class (or one of its subclasses).
The Role input parameter, if not NULL, MUST be a valid Property name. It acts as a filter on the returned set of names by mandating that each returned name identifies an Object that MUST be associated to the source Object via an Association in which the source Object plays the specified role (i.e. the name of the Property in the Association Class that refers to the source Object MUST match the value of this parameter).
The ResultRole input parameter, if not NULL, MUST be a valid Property name. It acts as a filter on the returned set of names by mandating that each returned name identifies an Object that MUST be associated to the source Object via an Association in which the named returned Object plays the specified role (i.e. the name of the Property in the Association Class that refers to the returned Object MUST match the value of this parameter).
If successful, the method returns zero or more full CIM Class paths or Instance paths of Objects meeting the requested criteria. Since it is possible for CIM Objects from different hosts or namespaces to be associated, each returned path is an absolute path that includes host and namespace information.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate the association objects that refer to a particular target CIM Object (Class or Instance).
| References |
| <objectWithPath>* References ( [IN] <objectName> ObjectName, [IN,OPTIONAL,NULL] <className> ResultClass = NULL, [IN,OPTIONAL,NULL] string Role = NULL, [IN,OPTIONAL] boolean IncludeQualifiers = false, [IN,OPTIONAL] boolean IncludeClassOrigin = false, [IN,OPTIONAL,NULL] string PropertyList [] = NULL ) |
The ObjectName input parameter defines the target CIM Object whose referring Objects are to be returned. This is either a Class name or Instance name (model path).
The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It acts as a filter on the returned set of Objects by mandating that each returned Object MUST be an Instance of this Class (or one of its subclasses), or this Class (or one of its subclasses).
The Role input parameter, if not NULL, MUST be a valid Property name. It acts as a filter on the returned set of Objects by mandating that each returned Objects MUST refer to the target Object via a Property whose name matches the value of this parameter.
If the IncludeQualifiers input parameter is true, this specifies that all Qualifiers for each Object (including Qualifiers on the Object and on any returned Properties) MUST be included as <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are present in each returned Object.
If the IncludeClassOrigin input parameter is true, this specifies that the CLASSORIGIN attribute MUST be present on all appropriate elements in each returned Object. If false, no CLASSORIGIN attributes are present in each returned Object.
If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. Each returned Object MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true (or DeepInheritance is specified as false) this acts as an additional filter on the set of Properties returned (for example, if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to a returned Instance, then it will not be included in that Instance). If the PropertyList input parameter is an empty array this signifies that no Properties are included in each returned Object. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in each returned Object.
If the PropertyList contains duplicate elements, the Server MUST ignore the duplicates but otherwise process the request normally. If the PropertyList contains elements which are invalid Property names for any target Object, the Server MUST ignore such entries but otherwise process the request normally.
Clients SHOULD NOT explicitly specify properties in the PropertyList parameter unless they have specified a non-NULL value for the ResultClass parameter.
If successful, the method returns zero or more CIM Classes or Instances meeting the requested criteria. Since it is possible for CIM Objects from different hosts or namespaces to be associated, each returned Object includes location information.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate the association objects that refer to a particular target CIM Object (Class or Instance).
| ReferenceNames |
| <objectPath>* ReferenceNames ( [IN] <objectName> ObjectName, [IN,OPTIONAL,NULL] <className> ResultClass = NULL, [IN,OPTIONAL,NULL] string Role = NULL ) |
The ObjectName input parameter defines the target CIM Object whose referring object names are to be returned. It may be either a Class name or an Instance name (model path).
The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It acts as a filter on the returned set of Object Names by mandating that each returned Object Name MUST identify an Instance of this Class (or one of its subclasses), or this Class (or one of its subclasses).
The Role input parameter, if not NULL, MUST be a valid Property name. It acts as a filter on the returned set of Object Names by mandating that each returned Object Name MUST identify an Object that refers to the target Instance via a Property whose name matches the value of this parameter.
If successful, the method returns the names of zero or more full CIM Class paths or Instance paths of Objects meeting the requested criteria. Since it is possible for CIM Objects from different hosts or namespaces to be associated, each returned path is an absolute path that includes host and namespace information.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to retrieve a single property value from a CIM Instance in the target Namespace.
| GetProperty |
| <propertyValue>? GetProperty ( [IN] <instanceName> InstanceName, [IN] string PropertyName ) |
The InstanceName input parameter specifies the name of the Instance (model path) from which the Property value is requested.
The PropertyName input parameter specifies the name of the Property whose value is to be returned.
If successful, the return value specifies the value of the requested Property. If the value is NULL then no element is returned.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to set a single property value in a CIM Instance in the target Namespace.
| SetProperty |
| void SetProperty ( [IN] <instanceName> InstanceName, [IN] string PropertyName, [IN,OPTIONAL,NULL] <propertyValue> NewValue = NULL ) |
The InstanceName input parameter specifies the name of the Instance (model path) for which the Property value is to be updated.
The PropertyName input parameter specifies the name of the Property whose value is to be updated.
The NewValue input parameter specifies the new value for the Property (which may be NULL).
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to retrieve a single Qualifier declaration from the target Namespace.
| GetQualifier |
| <qualifierDecl> GetQualifier ( [IN] string QualifierName ) |
The QualifierName input parameter identifies the Qualifier whose declaration to be retrieved.
If successful, the method returns the Qualifier declaration for the named Qualifier.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to create or update a single Qualifier declaration in the target Namespace. If the Qualifier declaration already exists it is overwritten.
| SetQualifier |
| void SetQualifier ( [IN] <qualifierDecl> QualifierDeclaration ) |
The QualifierDeclaration input parameter defines the Qualifier Declaration to be added to the Namespace.
If successful, the Qualifier declaration MUST have been added to the target Namespace. If a Qualifier declaration with the same Qualifier name already existed, then it MUST have been replaced by the new declaration.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to delete a single Qualifier declaration from the target Namespace.
| DeleteQualifier |
| void DeleteQualifier ( [IN] string QualifierName ) |
The QualifierName input parameter identifies the Qualifier whose declaration to be deleted.
If successful, the specified Qualifier declaration MUST have been deleted from the Namespace.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
This operation is used to enumerate Qualifier declarations from the target Namespace.
| EnumerateQualifiers |
| <qualifierDecl>* EnumerateQualifiers ( ) |
If successful, the method returns zero or more Qualifier declarations.
If unsuccessful, one of the following status codes MUST be returned by this method, where the first applicable error in the list (starting with the first element of the list, and working down) is the error returned. Any additional method-specific interpretation of the error in is given in parentheses.
There are no intrinsic methods defined specifically for the purpose of manipulating CIM Namespaces. However, the modelling of a CIM Namespace using the class __Namespace, together with the requirement that the root Namespace MUST be supported by all CIM Servers, implies that all Namespace operations can be supported.
For example:
This section partitions the intrinsic methods into functional groups for the purpose of establishing conformance.
Support for a particular group does not guarantee that all invocations of any method in that group will succeed. Rather, the exclusion of a group is a declaration that any attempt to call a method in that group will always return CIM_ERR_NOT_SUPPORTED.
Mechanisms by which a CIM Server may declare the functional groups that it supports are defined in the section on Determining CIM Server Capabilities.
In order to limit the number of different profiles that may be supported by a CIM Server, each functional group has a dependency on another group (with the exception of the Basic Read functional group). If functional group G1 has a dependency on functional group G2, then a CIM Server which supports G1 MUST also support G2.
The dependency relation is transitive, so that if G1 depends on G2, and G2 depends on G3, then G1 depends on G3. It is also anti-symmetric, so that if G1 depends on G2 then G2 cannot depend on G1.
Using these rules, the table below defines a rooted directed tree of dependencies with the Basic Read dependency representing the root node.
For example, a CIM Server which supports the Schema Manipulation functional group MUST also support the Instance Manipulation, Basic Write and Basic Read.
|
Funct |