Specification
for CIM
Operations over HTTPDSP0200
Status: Final
Version 1.2, January 09, 2007
Copyright © 2000-2007 Distributed
Management
Task Force, Inc. (DMTF). All rights reserved.
DMTF is a not-for-profit association of industry
members
dedicated to promoting enterprise and systems management and
interoperability.
Members and non-members may reproduce DMTF specifications and documents
for uses consistent with this purpose, provided that correct
attribution
is given. As DMTF specifications may be revised from time to
time,
the particular version and release date should always be noted.
Implementation of certain elements of this standard
or
proposed standard may be subject to third party patent rights,
including
provisional patent rights (herein "patent rights"). DMTF makes no
representations
to users of the standard as to the existence of such rights, and is not
responsible to recognize, disclose, or identify any or all such third
party
patent right, owners or claimants, nor for any incomplete or inaccurate
identification or disclosure of such rights, owners or claimants. DMTF
shall have no liability to any party, in any manner or circumstance,
under
any legal theory whatsoever, for failure to recognize, disclose, or
identify
any such third party patent rights, or for such party’s reliance on the
standard or incorporation thereof in its product, protocols or testing
procedures. DMTF shall have no liability to any party implementing such
standard, whether such implementation is foreseeable or not, nor to any
patent owner or claimant, and shall have no liability or responsibility
for costs or losses incurred if a standard is withdrawn or modified
after
publication, and shall be indemnified and held harmless by any party
implementing
the standard from any and all claims of infringement by a patent owner
for such implementations.
For information about patents held by third-parties
which have notified the DMTF that, in their opinion, such patent may
relate
to or impact implementations of DMTF standards, visit
http://www.dmtf.org/about/policies/disclosures.php.
Contents
1. Introduction
- 1.1. Requirements
- 1.2. Terminology
- 1.3. Style
2. CIM Operation Syntax and
Semantics
- 2.1. Overview
- 2.1.1. Well-Formed, Valid and
Loosely Valid
- 2.2. Operational Semantics
- 2.3. CIM Message Syntax and Semantics
- 2.3.1. Method Invocations
- 2.3.1.1. Simple Operations
- 2.3.1.2. Multiple Operations
- 2.3.1.3. Status Codes
- 2.3.2. Intrinsic Methods
- 2.3.2.1. GetClass
- 2.3.2.2. GetInstance
- 2.3.2.3. DeleteClass
- 2.3.2.4. DeleteInstance
- 2.3.2.5. CreateClass
- 2.3.2.6. CreateInstance
- 2.3.2.7. ModifyClass
- 2.3.2.8. ModifyInstance
- 2.3.2.9. EnumerateClasses
- 2.3.2.10. EnumerateClassNames
- 2.3.2.11. EnumerateInstances
- 2.3.2.12. EnumerateInstanceNames
- 2.3.2.13. ExecQuery
- 2.3.2.14. Associators
- 2.3.2.15. AssociatorNames
- 2.3.2.16. References
- 2.3.2.17. ReferenceNames
- 2.3.2.18. GetProperty
- 2.3.2.19. SetProperty
- 2.3.2.20. GetQualifier
- 2.3.2.21. SetQualifier
- 2.3.2.22. DeleteQualifier
- 2.3.2.23. EnumerateQualifiers
- 2.3.3. Namespace
Manipulation
- 2.3.3.1. CIM_Namespace
- 2.3.3.1.1. Namespace Creation
- 2.3.3.1.2. Namespace Deletion
- 2.3.3.1.3. Namespace Manipulation
and Query
- 2.3.3.2 Use of the __Namespace Pseudo
Class (DEPRECATED)
- 2.3.4. Functional Profiles
- 2.3.5. Extrinsic
Method Invocation
- 2.4. CIM Export Syntax and Semantics
- 2.4.1. Export Method Invocations
- 2.4.1.1. Simple Export
- 2.4.1.2. Multiple Export
- 2.4.1.3. Status Codes
- 2.4.2. Export Methods
- 2.4.2.1 Export Indication
- 2.4.3 Functional Profiles
3. Encapsulation of CIM
Messages
- 3.1. CIM Clients, CIM
Servers and CIM
Listeners
- 3.2. Use of M-POST
- 3.2.1. Use of the Ext Header
- 3.2.2. Naming of
Extension Headers
- 3.3. Extension
Headers Defined
for CIM Operation Requests and Responses
- 3.3.1.
Encoding of CIM
Names within HTTP Headers and Trailers
- 3.3.2.
Encoding
of CIM Object Paths within HTTP Headers and Trailers
- 3.3.3. CIMOperation
- 3.3.4. CIM Export
- 3.3.5. CIMProtocolVersion
- 3.3.6. CIMMethod
- 3.3.7. CIMObject
- 3.3.8 CIMExportMethod
- 3.3.9. CIMBatch
- 3.3.10. CIMExportBatch
- 3.3.11. CIMError
- 3.3.12. CIMRoleAuthenticate
- 3.3.13.
CIMRoleAuthorization
- 3.3.14. CIMStatusCode
- 3.3.15.
CIMStatusCodeDescription
- 3.3.16.
WBEMServerResponseTime
- 4. HTTP Requirements &
Usage
- 4.1. HTTP Support
- 4.2. Use of Standard Headers
- 4.2.1. Accept
- 4.2.2. Accept-Charset
- 4.2.3. Accept-Encoding
- 4.2.4. Accept-Language
- 4.2.5. Accept-Ranges
- 4.2.6. Allow
- 4.2.7. Authorization
- 4.2.8. Cache-Control
- 4.2.9. Connection
- 4.2.10. Content-Encoding
- 4.2.11. Content-Language
- 4.2.12. Content-Range
- 4.2.13. Content-Type
- 4.2.14. Expires
- 4.2.15. If-Range
- 4.2.16. Proxy-Authenticate
- 4.2.17. Range
- 4.2.18. WWW-Authenticate
- 4.3. Errors and Status Codes
- 4.4. Security
Considerations
- 4.5. Determining
CIM Server
Capabilities
- 4.5.1 Determining CIM Server Capabilities
through CIM
Classes
- 4.5.2 Determining CIM Server Capabilities
through HTTP
Options
- 4.5.2.1.
CIMSupportedFunctionalGroups
- 4.5.2.2.
CIMSupportsMultipleOperations
- 4.5.2.3.
CIMSupportedQueryLanguages
- 4.5.2.4. CIMValidation
- 4.6. Other HTTP Methods
- 4.7. Discovery and
Addressing
- 4.8.
Internationalization
Considerations
5. References
Appendix A - Change History
Appendix B - Examples of Message Exchanges
- A.1. Retrieval
of a Single
Class Definition
- A.2.
Retrieval of a
Single Instance Definition
- A.3. Deletion of
a Single
Class Definition
- A.4. Deletion
of a Single
Instance Definition
- A.5. Creation of
a Single
Class Definition
- A.6. Creation
of a Single
Instance Definition
- A.7. Enumeration of Class Names
- A.8. Enumeration of Instances
- A.9. Retrieval of a
Single Property
- A.10. Execution of
an Extrinsic
Method
- A.11. Indication Delivery
- A.12. Subscription Example
- A.14. Multiple Operations Example
Appendix C – LocalOnly Parameter Discussion
Abstract
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 Messages 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.
Back to contents
1. Introduction
This document defines a mapping of CIM Messages 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.
- Section 2 describes
the
CIM
messages that form the HTTP payload, using XML. It specifies the syntax
and semantics of the message requests and their corresponding responses.
- Section 3
describes
the
encapsulation of these messages in HTTP request and response messages,
with examples of each. It describes the extension headers used to
convey
additional CIM-specific semantics in the HTTP Header.
- Section 4 describes
in
more
detail other aspects of the encapsulation:
- HTTP Version Support
- The use of standard HTTP Headers
- HTTP Error codes
- Security Considerations
Back to contents
1.1. Requirements
There are potentially many different ways in which CIM messages could
be
represented within XML, and those messages 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
define the HTTP encapsulation.
The following criteria have been applied to the representation of
CIM
messages in XML [2,11]:
- Each CIM message is described completely in XML; completeness is
favored
over conciseness.
- The set of CIM Messages provide sufficient functionality to
enable
implementations
of CIM to communicate effectively for the purposes of management. It is
not a goal of this release of the mapping to provide a complete
set of messages. It is a goal to define the mapping so as to admit
straightforward
extension (addition of further features) in future versions.
- The set of CIM messages are classified into functional profiles
so that
a range of implementations (varying from complete support of all
messages
to support of a minimal subset) is allowed. The number of functional
profiles
is kept as small as possible to encourage interoperability, and
mechanisms
provided by which CIM implementations can declare their level of
support.
The following criteria have been applied to the HTTP encapsulation of
CIM
Messages herein:
- In recognition of the large installed base of HTTP/1.0 systems,
the
encapsulation
is designed to support both HTTP/1.0 and HTTP/1.1
- The encapsulation does not introduce any requirements which are
in
conflict
with those stated in HTTP/1.0 or HTTP/1.1
- The encapsulation should be straightforwardly usable over the
current
base
HTTP infrastructures. Some features are intended to anticipate and
exploit
enhancements to this base, but no aspects of the encapsulation require
any such enhancements as mandatory.
- The encapsulation avoids the use of pure HTTP Tunneling or URL
munging
(e.g. the use of the "?" character) in favor of a mechanism which
allows
existing HTTP infrastructures to safely control content.
- The encapsulation exposes key CIM message information in headers
to
allow
efficient firewall/proxy handling. The information is limited to
that which is considered essential, in order not to have significant
impact
on the size of the Header. No CIM-specific information appears in a
Header
that does not also appear within the CIM message.
- There is a clear and unambiguous encapsulation of the CIM message
payload
within the HTTP Message. Conciseness of the encapsulation is of
secondary
importance.
Back to contents
1.2. Terminology
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].
Back to contents
1.3. Style
This document uses a number of stylistic conventions to highlight
examples
and definitions.
Examples are displayed in this fashion:
Definitions are illustrated thusly:
Back to contents
2. CIM Message
Syntax and
Semantics
2.1. Overview
This specification defines all interactions between CIM products as CIM
messages.
A CIM Message is a well-defined request
or
response data packet used to exchange information between CIM products.
There are currently two types of CIM Messages: CIM
Operation
Messages and CIM Export Messages.
- A CIM Operation Message is a CIM message used to invoke
an
operation
on the target namespace.
- A CIM Export Message is a CIM message used to communicate
information
about a CIM namespace or element that is foreign to the target. A
CIM
Export Message is informational only and does not define an
operation
on the target CIM namespace or even imply the existence of a target
namespace.
This section describes the syntax and semantics of CIM messages 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].
Back to contents
2.1.1. Well-Formed, Valid and Loosely
Valid
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:
- If any attributes or elements in the XML document which do not
appear
in
the CIM XML DTD are removed, then the resulting document is valid with
respect to the CIM XML DTD.
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, CIM
Server or CIM Listener when parsing
received
XML documents defined within the scope of this mapping. It is
recognized
that not all Clients (respectively, CIM Servers or CIM Listeners)
should
be required to validate each received CIM Message Response
(respectively,
CIM Message Request) 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:
- A CIM Client (respectively, CIM Server or CIM Listener) MAY
include a
DOCTYPE
element in a CIM Message Request (respectively, CIM Message Response).
If so, an External declaration SHOULD be used (in-lining of the
complete
DTD within a message is discouraged).
- A CIM Client (respectively, CIM Server or CIM Listener) MAY elect
to
validate
a received CIM Message Response (respectively, CIM Message Request).
- If a CIM Client (respectively, CIM Server or CIM Listener) elects
not
to
validate a received CIM Message Response (respectively, CIM Message
Request),
then loose validation MUST be enforced.
The behavior of a CIM Server or CIM Listener with respect to a received
CIM Message Request is covered in detail in the section on Errors
and Status Codes.
Back to contents
2.2. Operational
Semantics
The CIM XML DTD [2,11] defines a subelement under the root <CIM>
element
called <MESSAGE>, which contains one of the following
subelements:
- CIM Operation Message Subelements:
- <SIMPLEREQ>
- <SIMPLERSP>
- <MULTIREQ>
- <MULTIRSP>
- CIM Export Message Subelements:
- <SIMPLEXPREQ>
- <SIMPLEXPRSP>
- <MULTIEXPREQ>
- <MULTIEXPRSP>
In the remainder of this document:
- The term Operation
Request
Message denotes an XML document that is loosely
valid with respect to the CIM XML DTD, which contains under the
root
<CIM> node a <MESSAGE> subelement, under which there is a
<MULTIREQ>
or <SIMPLEREQ> subelement, and;
- The term Operation
Response
Message denotes an XML document that is loosely valid with respect
to the CIM XML DTD, which contains under the root <CIM> node a
<MESSAGE>
subelement, under which there is a <MULTIRSP> or
<SIMPLERSP> subelement.
- The term Export Request Message denotes an XML document that is
loosely
valid with respect to the CIM XML DTD, which contains under the root
<CIM>
node a <MESSAGE> subelement, under which there is a
<MULTIEXPREQ>
or <SIMPLEEXPREQ> subelement, and;
- The term Export Response Message denotes an XML document that is
loosely
valid with respect to the CIM XML DTD, which contains under the root
<CIM>
node a <MESSAGE> subelement, under which there is a
<MULTIEXPRSP>
or <SIMPLEEXPRSP> subelement.
- The phrase CIM Message Request will be used to refer to either an
Operation
Request Message or an Export Request Message.
- The phrase CIM Message Response will be used to refer to either
an
Operation
Response Message or an Export Response Message.
A CIM Message Request MUST contain a non-empty value for the ID
attribute
of the <MESSAGE> element. The corresponding CIM Message
Response
MUST supply the same value for that attribute. Clients SHOULD
employ
a message ID scheme that minimizes the chance of receiving a stale CIM
Message Response.
Any CIM Message conforming to this specification MUST have a minimum
value of "1.0" and a maximum value that is equal to the latest version
of this specification for the PROTOCOLVERSION
attribute of the <MESSAGE> element.
An Operation Response Message sent in response to an Operation
Request
Message MUST:
- specify the same value for the ID
attribute of the <MESSAGE> element as appeared in the Operation
Request
Message, and
- contain a <MULTIRSP> subelement if the Operation Request
Message
contained
a <MULTIREQ> subelement, or
- contain a <SIMPLERSP> subelement if the Operation Request
Message
contained
a <SIMPLEREQ> subelement.
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.
An Export Response Message sent in response to an Export Request
Message
MUST:
- specify the same value for the ID attribute of the
<MESSAGE> element
as appeared in the Export Request Message, and
- contain a <MULTIEXPRSP> subelement if the Export Request
Message
contained
a <MULTIEXPREQ> subelement, or
- contain a <SIMPLEEXPRSP> subelement if the Export Request
Message
contained
a <SIMPLEEXPREQ> subelement.
A Simple Export Request is an Export Request Message that contains a
<SIMPLEEXPREQ>
subelement. A Simple Export Response is an Export Response
Message
that contains a <SIMPLEEXPRSP> subelement.
A Multiple Export Request is an Export Request Message that contains
a <MULTIEXPREQ> subelement. A Multiple Export Response is
an Export
Response Message that contains a <MULTIEXPRSP> subelement.
Back to contents
2.3. CIM Operation Syntax and Semantics
2.3.1 Method Invocations
All CIM Operation requests defined for this mapping are defined as
invocations
of one or more methods. A method may be either:
- Intrinsic, which means that
it is
defined
by this specification for the purposes of modeling a CIM operation, or;
- Extrinsic, which means that
it is
defined
as a method on a CIM Class in some Schema.
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. 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:
- Each Input parameter MUST be named using the name assigned in the
method
definition.
- The Input parameters MAY be supplied in any order.
- Each Input parameter of the method, and no others, MUST be
present in
the
call, unless it was defined as Optional.
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:
- Each Output parameter MUST be named using the name assigned in
the
method
definition.
- The Output parameters MAY be supplied in any order.
- Each Output parameter of the method, and no others, MUST be
present in
the response, unless it was defined as Optional.
The method invocation process may be thought of as:
- The binding of the input parameter values specified as
subelements of
the
<METHODCALL> or <IMETHODCALL> element to the input
parameters of
the Method, followed by;
- The attempted execution of the method using the bound input
parameters,
and;
- If attempt to call the method is successful, the binding of the
return
value and output parameters to the subelements of the
<METHODRESPONSE>
or <IMETHODRESPONSE> element, or;
- If the attempt to call the method is unsuccessful, the binding
of an
error
code and (optional) human-readable description of that code to the
<METHODRESPONSE>
or <IMETHODRESPONSE> element.
Back to contents
2.3.1.1. Simple Operations
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 <LOCALCLASSPATH> subelement identifying the CIM Class on
which
the
method is to be invoked, in the case that the method is static, or;
- An <LOCALINSTANCEPATH> subelement identifying the CIM
Instance on
which
the method is to be invoked, otherwise.
Back to contents
2.3.1.2. Multiple Operations
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). However, servers MUST
process
each operation in a batched operation to completion before executing
the
next operation in the batch. Clients MUST recognize that the order of
operations
within a batched operation is significant in the manner described in
the
last sentence.
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.
Back to contents
2.3.1.3. Status Codes
This section defines the status codes and detailed error information
that may be returned by a conforming CIM Server application. The value
of an <ERROR> subelement within a <METHODRESPONSE> or
<IMETHODRESPONSE> element includes
- a mandatory status code,
- an optional human-readable description of the status code,
- and zero or more CIM_Error instances.
The following table 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. In addition to returning a status code,
a conforming CIM Server MAY return zero or more <INSTANCE>
subelements
as part of an <ERROR> element. Each <INSTANCE> subelement
MUST be
an instance of CIM_Error. For each instance of CIM_Error, the value of
CIMStatusCode MUST comply with the definition of expected error codes
for the CIM Operation Request. A CIM Client MAY ignore any
<INSTANCE>
subelements.
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 occurred that is not covered
by a more
specific error code. |
| CIM_ERR_ACCESS_DENIED |
2 |
Access to a CIM resource is 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 are not valid. |
| CIM_ERR_INVALID_CLASS |
5 |
The specified class does not exist. |
| CIM_ERR_NOT_FOUND |
6 |
The requested object cannot be found. |
| CIM_ERR_NOT_SUPPORTED |
7 |
The requested operation is not supported. |
| CIM_ERR_CLASS_HAS_CHILDREN |
8 |
The operation cannot be invoked on this class
because it has subclasses. |
| CIM_ERR_CLASS_HAS_INSTANCES |
9 |
The operation cannot be invoked on this class
because one or more instances of
this class exist. |
| CIM_ERR_INVALID_SUPERCLASS |
10 |
The operation cannot be invoked because the
specified superclass
does not exist. |
| CIM_ERR_ALREADY_EXISTS |
11 |
The operation cannot be invoked 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 not compatible 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 cannot be invoked. |
| CIM_ERR_METHOD_NOT_FOUND |
17 |
The specified extrinsic method does not exist. |
| CIM_ERR_NAMESPACE_NOT_EMPTY |
20 |
The specified Namespace is not empty. |
Back to contents
2.3.2. Intrinsic Methods
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
description
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.
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. A CIM Server MAY omit support for an optional
parameter.
Any attempt to call a method with an optional parameter that is not
supported
MUST return either CIM_ERR_NOT_SUPPORTED or CIM_ERR_INVALID_PARAMETER.
This notation uses the NULL qualifier to indicate parameters whose
values
may 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 modeled as standard CIM types (such as string and boolean, or
arrays thereof) are represented as follows:
- Simple values MUST be represented using the <VALUE>
subelement
within
an <IPARAMETER> element (for method parameters) or within an
<IRETURNVALUE>
element (for method return values).
- Array values MUST be represented using the <VALUE.ARRAY>
subelement
within an <IPARAMETER> element (for method parameters) or within
an
<IRETURNVALUE> element (for method return values).
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) |
| <objectPath> |
OBJECTPATH |
| <propertyValue> |
(VALUE|VALUE.ARRAY|VALUE.REFERENCE) |
| <qualifierDecl> |
QUALIFIER.DECLARATION |
Back to contents
2.3.2.1. GetClass
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)
defined or overridden within the definition of the Class (as
specified
in the classname input parameter) are returned. If false,
all
elements are returned.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_NOT_FOUND (the request CIM Class does not exist in the
specified
namespace)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.2. GetInstance
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, (DEPRECATED)
[IN,OPTIONAL] boolean
IncludeQualifiers = false, (DEPRECATED)
[IN,OPTIONAL] boolean
IncludeClassOrigin = false,
[IN,OPTIONAL,NULL]
string PropertyList [] = NULL
) |
The InstanceName input parameter
defines
the name of the Instance to be retrieved.
DEPRECATION NOTE: With
the 1.2 release of this specification, the LocalOnly parameter is
DEPRECATED. LocalOnly filtering, as defined in 1.1, will not be
supported in the next major revision of this specification. In the 1.1
version of this specification, the definition of the LocalOnly
parameter was incorrectly modified. This change introduced a number of
interoperability and backward compatibility problems for CIM Clients
using the LocalOnly parameter to filter the set of Properties returned.
The DMTF strongly recommends that CIM Clients set LocalOnly = false and
do not rely on the use of this parameter to filter the set of
Properties returned. To minimize the impact of implementing this
recommendation on CIM Clients, a CIM Server MAY choose to treat the
value of the LocalOnly parameter as FALSE for all requests.
A CIM Server MUST consistently support a single interpretation of the
LocalOnly parameter. Refer to Appendix C for additional details.
DEPRECATION NOTE: The
use of the IncludeQualifiers parameter
is DEPRECATED and it may be
removed
in a future version of this specification. The IncludeQualifiers
parameter definition is ambiguous and when set to true CIM Clients can
not be assured of any qualifiers being returned. A CIM Client SHOULD
always set this parameter to false. To minimize the impact of
implementing this recommendation on CIM Clients, a CIM Server MAY
choose to treat the value of the IncludeQualifiers parameter
as FALSE for all requests. The preferred behavior is to use the class
operations to receive qualifier information and not depend on any
qualifiers existing in this response. 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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the
specified
namespace)
- CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
CIM
Instance
does not exist in the specified namespace)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.3. DeleteClass
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_NOT_FOUND (the CIM Class to be deleted does not exist)
- CIM_ERR_CLASS_HAS_CHILDREN (the CIM Class has one or more
subclasses
which
cannot be deleted)
- CIM_ERR_CLASS_HAS_INSTANCES (the CIM Class has one or more
instances
which
cannot be deleted)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.4. DeleteInstance
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.
The deletion of the Instance may or may not cause the automatic
deletion
of additional instances. For example, the deletion of an instance may
cause
the automatic deletion of all associations that reference that
instance.
Or the deletion of an instance may cause the automatic deletion of
instances
(and their associations) that have a Min(1) relationship to that
instance.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the
specified
namespace)
- CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
CIM
Instance
does not exist in the specified namespace)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.5 CreateClass
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:
- Any CLASSORIGIN and PROPAGATED
attributes in the NewClass MUST be
ignored
by the Server.
- If the new Class has no Superclass, the NewClass
parameter defines a new base Class. The Server MUST ensure that all
Properties
and Methods of the new Class have a CLASSORIGIN
attribute whose value is the name of the new Class.
- If the new Class has a Superclass, the NewClass
parameter defines a new Subclass of that Superclass. The Superclass
MUST
exist. The Server MUST ensure that:
- Any Properties, Methods or Qualifiers in the Subclass not
defined in
the
Superclass are created as new elements of the Subclass. In particular
the
Server MUST set the CLASSORIGIN
attribute
on the new Properties and Methods to the name of the Subclass, and
ensure
that all other Properties and Methods preserve their CLASSORIGIN
attribute value from that defined in the Superclass.
- If a Property is defined in the Superclass and in the Subclass,
the
value
assigned to that property in the Subclass (including NULL) becomes the
default value of the property for the Subclass.
- If a Property or Method of the Superclass is not specified in
the
Subclass,
then that Property or Method is inherited without modification by the
Subclass.
- Any Qualifiers defined in the Superclass with a TOSUBCLASS
attribute value of true MUST appear in
the resulting Subclass. Qualifiers in the Superclass with a TOSUBCLASS
attribute value of false MUST NOT be
propagated
to the Subclass.
- Any Qualifier propagated from the Superclass cannot be modified
in the
Subclass if the OVERRIDABLE attribute
of
that Qualifier was set to false in the
Superclass. It is a Client error to specify such a Qualifier in the NewClass
with a different definition to that in the Superclass (where definition
encompasses the name, type and flavor attribute settings of the <QUALIFIER>
element, and the value of the Qualifier).
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_ALREADY_EXISTS (the CIM Class already exists)
- CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a
non-existent
superclass)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.6. CreateInstance
This operation is used to create a single CIM Instance in the target
Namespace.
The Instance MUST NOT already exist.
DEPRECATION NOTE:
The use of qualifiers on instances is
DEPRECATED and may
be removed in a future version of this specification. A CIM Client can
not rely on any qualifiers included in the NewInstance
to have any impact on the operation. It is RECOMMENDED that the CIM
Server ignore any qualifiers included in the instance. 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:
- Any CLASSORIGIN and PROPAGATED
attributes in the NewInstance MUST be
ignored
by the Server.
- The Server MUST ensure that:
- DEPRECATED. Any
Qualifiers in the Instance not defined in the Class are created as
new elements of the Instance.
- All Properties of the Instance preserve their CLASSORIGIN
attribute value from that defined in the Class.
- If a Property is specified in the NewInstance
parameter, the value assigned to that property in the Instance
(including
NULL) becomes the value of the property for the Instance. Note that it
is a Client error to specify a Property that does not belong to the
Class.
- If a Property of the Class is not specified in the Instance,
then that
Property is inherited without modification by the Instance.
- DEPRECATION NOTE: The use of the TOINSTANCE
attribute is DEPRECATED. Servers
MAY
choose to ignore TOINSTANCE. Servers that do not ignore TOINSTANCE
MUST interpret it as follows. Any Qualifiers defined in the Class with
a TOINSTANCE attribute value of true appear in the Instance. Qualifiers
in the Class with a TOINSTANCE attribute value of false MUST NOT be
propagated
to the instance.
- DEPRECATED. Any
Qualifier propagated from the Class cannot be modified in the Instance
if the OVERRIDABLE attribute of that
Qualifier
was set to false in the Class. It is a
Client error to specify such a Qualifier in the NewInstance
with a different definition to that in the Class (where definition
encompasses
the name, type and flavor attribute settings of the <QUALIFIER>
element, and the value of the Qualifier).
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class of which this is to be a new
Instance
does not exist)
- CIM_ERR_ALREADY_EXISTS (the CIM Instance already exists)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.7. ModifyClass
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 modification of the Class, the following rules
MUST
be conformed to by the CIM Server:
- Any CLASSORIGIN and PROPAGATED
attributes in the ModifiedClass MUST
be
ignored by the Server.
- If the modified Class has no Superclass, the ModifiedClass
parameter defines modifications to a base Class. The Server MUST ensure
that:
- All Properties and Methods of the modified Class have a CLASSORIGIN
attribute whose value is the name of this Class.
- Any Properties, Methods or Qualifiers in the existing Class
definition
which do not appear in the ModifiedClass
parameter are removed from the resulting modified Class.
- If the modified Class has a Superclass, the ModifiedClass
parameter defines modifications to a Subclass of that Superclass. The
Superclass
MUST exist, and the Client MUST NOT change the name of the Superclass
in
the modified Subclass. The Server MUST ensure that:
- Any Properties, Methods or Qualifiers in the Subclass not
defined in
the
Superclass are created as elements of the Subclass. In particular the
Server
MUST set the CLASSORIGIN attribute on
the
new Properties and Methods to the name of the Subclass, and MUST ensure
that all other Properties and Methods preserve their CLASSORIGIN
attribute value from that defined in the Superclass.
- Any Property, Method or Qualifier previously defined in the
Subclass
but
not defined in the Superclass, and which is not present in the ModifiedClass
parameter, is removed from the Subclass.
- If a Property is specified in the ModifiedClass
parameter, the value assigned to that property therein (including NULL)
becomes the default value of the property for the Subclass.
- If a Property or Method of the Superclass is not specified in
the
Subclass,
then that Property or Method is inherited without modification by the
Subclass
(so that any previous changes to such an Element in the Subclass are
lost).
- If a Qualifier in the Superclass is not specified in the
Subclass, and
the Qualifier is defined in the Superclass with a TOSUBCLASS
attribute value of true, then the
Qualifier
MUST still be present in the resulting modified Subclass (it is not
possible
to remove a propagated Qualifier from a Subclass).
- Any Qualifier propagated from the Superclass cannot be modified
in the
Subclass if the OVERRIDABLE attribute
of
that Qualifier was set to false in the
Superclass. It is a Client error to specify such a Qualifier in the ModifiedClass
with a different definition to that in the Superclass (where definition
encompasses the name, type and flavor attribute settings of the <QUALIFIER>
element, and the value of the Qualifier).
- Any Qualifiers defined in the Superclass with a TOSUBCLASS
attribute value of false MUST
NOT
be propagated to the Subclass.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_NOT_FOUND (the CIM Class does not exist)
- CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a
non-existent
or incorrect superclass)
- CIM_ERR_CLASS_HAS_CHILDREN (the modification could not be
performed
because
it was not possible to update the subclasses of the Class in a
consistent
fashion)
- CIM_ERR_CLASS_HAS_INSTANCES (the modification could not be
performed
because
it was not possible to update the instances of the Class in a
consistent
fashion)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.8. ModifyInstance
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,
[IN, OPTIONAL] boolean
IncludeQualifiers
= true, (DEPRECATED)
[IN, OPTIONAL, NULL] string
propertyList[] = NULL
) |
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.
DEPRECATION NOTE: The
use of the
IncludeQualifiers parameter is DEPRECATED
and it may be removed in a future version of this specification.
The behavior of the IncludeQualifiers parameter is not specified. A CIM
Client can not rely on the IncludeQualifiers to have any impact on the
operation. It is RECOMMENDED that the CIM Server ignore any qualifiers
included in the instance. If the IncludeQualifiers input parameter is
true, this specifies that
the Qualifiers are modified as specified in the ModifiedInstance.
If false, Qualifiers in the ModifiedInstance are ignored and no
Qualifiers
are explicitly modified in the specified Instance.
If the PropertyList input parameter is not NULL, the members of the
array define one or more Property names. Only those properties
specified
in the PropertyList are modified as specified in the
ModifiedInstance.
Properties of the ModifiedInstance that are missing from the
PropertyList
are ignored. If the PropertyList input parameter is an empty
array
this signifies that no Properties are explicitly modified in the
specified
Instance. If the PropertyList input parameter is NULL this specifies
that
all Properties are updated in the specified 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 the
target Instance, the Server MUST ignore such entries but otherwise
process
the request normally.
In processing the modification of the Instance, the following rules
MUST be conformed to by the CIM Server:
- Any CLASSORIGIN and PROPAGATED attributes in the ModifiedInstance
MUST
be ignored by the Server.
- The Class MUST exist, and the Client MUST NOT change the ame of
the
Class
in the modified Instance. The Server MUST ensure that:
- DEPRECATED. Any
Qualifiers in the Instance not defined in the Class are created as
new elements of the Instance if IncludeQualifiers is true.
- All Properties of the Instance preserve their CLASSORIGIN
attribute
value
from that defined in the Class.
- Any Qualifier previously defined in the Instance but not
defined in the
Class, and which is not present in the ModifiedInstance parameter, is
removed
from the Instance if IncludeQualifiers is true.
- If a Property is specified in the ModifiedInstance and
PropertyList
parameters,
the value assigned to that property therein (including NULL) becomes
the
value of the property for the Instance. Note that it is a Client error
to specify a Property that does not belong to the Class.
- If a Property of the Class is not specified in the
ModifiedInstance but
is specified in the PropertyList, then that Property is inherited
without
modification by the Instance (so that any previous changes to that
Property
in the Instance are lost).
- DEPRECATION NOTE: The use of the TOINSTANCE
Qualifier attribute is DEPRECATED. Servers MAY choose
to ignore
TOINSTANCE. Servers that do not ignore TOINSTANCE
MUST interpret it as follows. Any Qualifiers defined in the Class with
a TOINSTANCE attribute value of true appear in the Instance (it is not
possible remove a propagated Qualifier from an Instance). Qualifiers in
the Class with a TOINSTANCE attribute value of false MUST NOT be
propagated
to the Instance
- DEPRECATED. Any
Qualifier propagated from the Class cannot be modified in the Instance
if the OVERRIDABLE attribute of that Qualifier was set to false in the
Class. It is a Client error to specify such a Qualifier in the
ModifiedInstance
with a different definition to that in the Class (where definition
encompasses
the name, type and flavor attribute settings of the
<QUALIFIER>
element, and the value of the Qualifier).
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class of which this is to be a new
Instance
does not exist)
- CIM_ERR_NOT_FOUND (the CIM Instance does not exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.9. EnumerateClasses
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). This definition of DeepInheritance applies
only
to the EnumerateClasses and EnumerateClassName operations.
If the LocalOnly input parameter is
true, this specifies that only CIM Elements (properties, methods and
qualifiers)
defined or overridden within the definition of the Class (as
specified
in the classname input parameter) are returned. If false,
all
elements are returned.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this
enumeration
does not exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.10. EnumerateClassNames
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 istrue,
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 theClassName
input parameter is NULL, this implies that the names of all base
Classes
in the target Namespace should be returned). This definition of
DeepInheritance
applies only to the EnumerateClasses and EnumerateClassName operations.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this
enumeration
does not exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.11. EnumerateInstances
This operation is used to enumerate instances of a CIM Class (this
includes
instances in the class and any subclasses in accordance with the
polymorphic
nature of CIM objects) in the target Namespace.
| EnumerateInstances |
<namedInstance>*EnumerateInstances
(
[IN] <className>
ClassName,
[IN,OPTIONAL] boolean
LocalOnly = true, (DEPRECATED)
[IN,OPTIONAL] boolean
DeepInheritance = true,
[IN,OPTIONAL] boolean
IncludeQualifiers = false, (DEPRECATED)
[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.
DEPRECATION NOTE: With
the 1.2 release of this specification, the LocalOnly parameter is
DEPRECATED. LocalOnly filtering, as defined in 1.1, will not be
supported in the next major revision of this specification. In the 1.1
version of this specification, the definition of the LocalOnly
parameter was incorrectly modified. This change introduced a number of
interoperability and backward compatibility problems for CIM Clients
using the LocalOnly parameter to filter the set of Properties returned.
The DMTF strongly recommends that CIM Clients set LocalOnly = false and
do not rely on the use of this parameter to filter the set of
Properties returned. To minimize the impact of implementing this
recommendation on CIM Clients, a CIM Server MAY choose to treat the
value of the LocalOnly parameter as FALSE for all requests.
A CIM Server MUST consistently support a single interpretation of the
LocalOnly parameter. Refer to Appendix C for additional details.
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.
DEPRECATION NOTE: The
use of the IncludeQualifiers parameter
is DEPRECATED and it may be
removed
in a future version of this specification. The IncludeQualifiers
parameter definition is ambiguous and when set to true CIM Clients can
not be assured of any qualifiers being returned. A CIM Client SHOULD
always set this parameter to false. To minimize the impact of
implementing this recommendation on CIM Clients, a CIM Server MAY
choose to treat the value of the IncludeQualifiers parameter
as FALSE for all requests. The preferred behavior is to use the class
operations to receive qualifier information and not depend on any
qualifiers existing in this response. 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 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
of the designated class. This may include inherited Property
names
or Property names explicitly defined in the designated class, but MAY
NOT
include Property names defined in subclasses of the designated
class.
Each returned Instance MUST NOT include elements for any Properties
missing
from this list. Note that the PropertyList parameter acts as an
additional
filter on the Properties defined by the LocalOnly and DeepInheritance
input
parameters; if the PropertyList includes a Property that is not
in
the set defined by the LocalOnly and DeepInheritance combination, the
element
for the Property MUST NOT be returned. If the PropertyList input
parameter is an empty array this signifies that no elements for
Properties
are included in the returned Instances. If the PropertyList input
parameter
is NULL, no additional filtering is defined by this parameter.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this
enumeration
does not exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.12. EnumerateInstanceNames
This operation is used to enumerate the names (model paths) of the
instances of a CIM Class (this includes instances in the class and any
subclasses in accordance with the polymorphic nature of CIM objects) in
the target Namespace.
The ClassName input parameter
defines
the Class that is the basis for the enumeration.
If successful, the method returns zero or more InstanceNames
(referred to in the CIM Specification [1] as a Model Path) that meet
the requested criteria. The InstanceName MUST specify the class from
which the instance
was instantiated, not any of its base classes. Please note that this
class may be different from the class specified as input.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this
enumeration
does not exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.13. ExecQuery
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED (the requested query
language is
not
recognized)
- CIM_ERR_INVALID_QUERY (the query is not a valid query in the
specified
query language)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.14. Associators
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, (DEPRECATED)
[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).
DEPRECATION NOTE: The
use of the
IncludeQualifiers parameter is DEPRECATED and it may be
removed in a future version of this specification. The preferred
behavior is to use the class operations to receive qualifier
information and not depend on any qualifiers existing in this response.
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. 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 the ObjectName refers to a class, then
classes are returned.Otherwise, the ObjectName refers to an instance,
and
instances are 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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.15. AssociatorNames
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 CIM Class paths or
Instance
paths 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 the ObjectName refers to a
Class
path, then Class paths are returned.Otherwise, the ObjectName refers to
an instance path, and instance paths are 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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.16. References
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, (DEPRECATED)
[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.
DEPRECATION NOTE: The
use of the
IncludeQualifiers parameter is DEPRECATED and it may be
removed in a future version of this specification. The preferred
behavior is to use the class operations to receive qualifier
information and not depend on any qualifiers existing in this response.
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. 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 the ObjectName refers to a class,
then
classes are returned.Otherwise, the ObjectName refers to an instance,
and
instances are 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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.17. ReferenceNames
This operation is used to enumerate the association objects that refer
to a particular target CIM Object (Class or Instance).
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 zero or more CIM Class paths or
Instance
paths 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 the ObjectName refers to a
Class
path, then Class paths are returned. Otherwise, the ObjectName refers
to
an instance path, and instance paths are 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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.18. GetProperty
This operation is used to retrieve a single
property
value from a CIM Instance in the target Namespace.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the
specified
namespace)
- CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
CIM
Instance
does not exist in the specified namespace)
- CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the
requested
Property does not)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.19. SetProperty
This operation is used to set a single property value in a CIM Instance
in the target Namespace.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the
specified
namespace)
- CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
CIM
Instance
does not exist in the specified namespace)
- CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the
requested
Property does not)
- CIM_ERR_TYPE_MISMATCH (the supplied value is incompatible with
the type
of the Property)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.20. GetQualifier
This operation is used to retrieve a single Qualifier declaration from
the target Namespace.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_NOT_FOUND (the requested Qualifier declaration did not
exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.21. SetQualifier
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.22. DeleteQualifier
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_NOT_FOUND (the requested Qualifier declaration did not
exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.2.23. EnumerateQualifiers
This operation is used to enumerate Qualifier declarations from the
target
Namespace.
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.3.3. Namespace
Manipulation
There are no intrinsic methods defined specifically for the purpose of
manipulating namespaces. The manipulation of namespaces shall be
executed by using intrinsic methods on the CIM_Namespace class.
2.3.3.1 Use of the CIM_Namespace Class to
manipulate
Namespaces
2.3.3.1.1 Namespace Creation
Creation of a namespace is realized by calling the intrinsic method
CreateInstance
for the CIM_Namespace class, specifying a value for the new instance
parameter
which defines a valid instance of the CIM_Namespace class and whose
name
property is the desired name of the new namespace.
The proposed definition MUST be a correct namespace definition
according
to the CIM specification [1]. Despite the naming conventions used
in the CIM specifications (Use of / in namespaces such as root/CIMV2
and
root/CIMV2/test) there is no hierarchy implied between different
namespaces.
Each namespace is independent of all others. The namespaces are to be
considered
flat and there is no defined behavior for navigating namespaces.
In processing the creation of the new namespace, the following rules
MUST be conformed to by the CIM Server:
The namespace defined by name
property
MUST NOT already exist in the CIM Server.
The <LOCALNAMESPACEPATH> defined for the
operation defines the namespace in which the CIM_Namespace instance
associated
with this new namespace is created.
It is the common practice proposed by this document that instances
of
CIM_Namespace be created in root unless there is a specific reason to
define
them in another namespace.
The inclusion of a CIM_Namespace instance within a namespace other
than
root is allowed.
In addition to creating instances of CIM_Namespace, compliant
implementations
MUST also create an instance of the association class
CIM_NamespaceInManager
defining the linking of the namespace created to the current
CIM_ObjectManager.
If successful, the specified Namespace MUST have been created by the
CIM Server. In addition, the CIM Server MUST return information
about
the namespace as an instance of the class CIM_Namespace and of
returning
instances of the association class CIM_NamespaceInManager for each
CIM_Namespace
instance created.
Back to contents
2.3.3.1.2 Namespace Deletion
If the CIM_Namespace class is supported by the CIM Server, all valid
namespaces MUST be represented by an instance of the CIM_Namespace
class. Deletion of a namespace is realized by using the intrinsic
method DeleteInstance to delete the instance of the class CIM_Namespace
that represents the namespace. The namespace to be deleted MUST exist.
If successful, the specified CIM_Namespace instance MUST be removed
by the CIM Server.
If unsuccessful, one of the status codes defined for the
DeleteInstance operation MUST be returned. A CIM Server MAY return
CIM_ERR_FAILED if a non-empty namespace cannot successfully be deleted.
Back to contents
2.3.3.1.3 Manipulation and query of
Namespace Information
The query of namespaces is provided through:
1. Query of the CIM_Namespace class on an
individual
namespace.
2. Use of the CIM_NamespaceInManager association
which links the target CIM_ObjectManager and the instances of
CIM_Namespace
representing all namespaces defined in the target CIM_ObjectManager
Back to contents
2.3.3.2 Use of the __Namespace Pseudo Class
(DEPRECATED)
In previous versions of this specification, namespace
manipulation
was through the pseudo class __Namespace as follows:
There are no intrinsic methods defined
specifically
for the purpose of manipulating CIM Namespaces. However, the modeling
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:
Enumeration
of
all child Namespaces of a particular Namespace is realized by calling
the
intrinsic method EnumerateInstanceNames against the parent Namespace,
specifying
a value for the ClassName parameter of __Namespace.
Creation of
a child Namespace is realized by calling the intrinsic method
CreateInstance
against the parent Namespace, specifying a value for the NewInstance
parameter
which defines a valid instance of the class __Namespace and whose Name
property is the desired name of the new Namespace.
The use of the __Namespace class is deprecated. In its
place,
use the CIM_Namespace class and the behavior as defined in section
2.3.3.1
of this specification.
Back to contents
2.3.4. Functional Profiles
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.
Back to contents
2.3.5. Extrinsic Method
Invocation
Any CIM Server is assumed to support
extrinsic
methods. Extrinsic methods are defined by the Schema supported by the
CIM
Server. If a CIM Server does not support extrinsic method invocations,
it MUST (subject to the considerations described in the rest of this
section)
return the error code CIM_ERR_NOT_SUPPORTED to any request to execute
an
extrinsic method. This allows a CIM client
to determine that all attempts to execute extrinsic methods will fail.
If the CIM Server is unable to perform the extrinsic method
invocation,
one of the following status codes MUST be returned by the CIM Server,
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
specific
interpretation of the error is given in parentheses.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED (the CIM Server does not support extrinsic
method
invocations)
- CIM_ERR_INVALID_NAMESPACE
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_NOT_FOUND (the target CIM Class or instance does not
exist in
the
specified namespace)
- CIM_ERR_METHOD_NOT_FOUND
- CIM_ERR_METHOD_NOT_AVAILABLE (the CIM Server is unable to honor
the
invocation
request)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.4 CIM Export Syntax and Semantics
2.4.1. Export Method Invocations
All CIM Export Message requests defined for this mapping are defined as
invocations of one or more export methods. Export methods do not
operate against CIM Namespaces.
An export method call is represented in XML by the
<EXPMETHODCALL>
element, and the response to that call represented by the
<EXPMETHODRESPONSE>
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. A parameter may be
both
an Input and Output parameter.
The <EXPMETHODCALL> element serves to name the method to be
invoked
and supply any Input parameters to the export method call. Note that:
- Each Input parameter MUST be named using the name assigned in the
method
definition.
- The Input parameters MAY be supplied in any order.
- Each Input parameter of the method, and no others, MUST be
present in
the
call, unless it was defined as Optional.
The <EXPMETHODRESPONSE> 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:
- Each Output parameter MUST be named using the name
assigned
in the method definition.
- The Output parameters MAY be supplied in any order.
- Each Output parameter of the method, and no others,
MUST
be
present in the response, unless it was defined as Optional.
The method invocation process may be thought of as:
- The binding of the input parameter values specified as
subelements of
the
<EXPMETHODCALL> element to the input parameters of the Method,
followed
by;
- The attempted execution of the method using the bound input
parameters,
and;
- If attempt to call the method is successful, the binding of the
return
value and output parameters to the subelements of the
<EXPMETHODRESPONSE>
element, or;
- If the attempt to call the method is unsuccessful, the binding
of an
error
code and (optional) human-readable description of that code to the
<EXPMETHODRESPONSE>
element.
Back to contents
2.4.1.1. Simple Export
A simple export is defined as one that requires the invocation of
a single export method. A simple export request is represented by
a <SIMPLEEXPREQ> element, and a simple export response by a
<SIMPLEEXPRSP>
element.
A <SIMPLEEXPREQ> MUST contain a <EXPMETHODCALL> element.
Back to contents
2.4.1.2. Multiple Export
A multiple export is defined as one that requires the invocation
of more than one export method. A multiple export request is
represented
by a <MULTEXPREQ> element, and a multiple export response by a
<MULTIEXPRSP>
element.
A <MULTIEXPREQ> (respectively, <MULTIEXPRSP>) element is
a sequence
of two or more <SIMPLEEXPREQ> (respectively,
<SIMPLEEXPRSP>) elements.
A <MULTIEXPRSP> element MUST contain a <SIMPLEEXPRSP>
element
for every <SIMPLEEXPREQ> element in the corresponding multiple
export
response, and these <SIMPLEEXPRSP> elements MUST be in the same
order
as their <SIMPLEEXPREQ> counterparts (so the first
<SIMPLEEXPRSP>
in the response corresponds to the first <SIMPLEEXPREQ> in the
request,
and so forth).
Multiple Exports provide a convenient mechanism to batch the
delivery
of multiple export method invocations into a single HTTP Message,
reducing
the number of roundtrips between a CIM Client and a CIM Listener and
allowing
the CIM Listener to make certain internal optimizations should it
choose
so to do. Note that Multiple Exports do not confer any
transactional
capabilities in the processing of the request (for example, there is no
requirement that the CIM Listener guarantee that the constituent export
method calls either all failed or all succeeded, only that the CIM
Listener
make a "best effort" to process the operation). However, CIM
Listeners
MUST process each method invocation in a batched message to completion
before executing the next method invocation in the batch. Clients MUST
recognize that the order of method calls within a batched message is
significant
in the manner described in the last sentence.
Not all CIM Listeners support Multiple Exports. If a CIM Listener
does
not support Multiple Exports it MUST return the status code
CIM_ERR_NOT_SUPPORTED.
Back to contents
2.4.1.3. Status Codes
This section defines the status codes and detailed error information
that may be returned by a conforming CIM Listener. The value of an
<ERROR> subelement within a <EXPMETHODRESPONSE> element
includes
- a mandatory status code,
- an optional human-readable description of the status code,
- and zero or more CIM_Error instances.
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.
In addition to returning a status code, a conforming CIM Listener
MAY return zero or more <INSTANCE> subelements as part of an
<ERROR> element. Each <INSTANCE> subelement MUST be an
instance of CIM_Error. For each instance of CIM_Error, the value of
CIMStatusCode MUST comply with the definition of expected error codes
for the CIM Export Request. A CIM Client MAY ignore any
<INSTANCE> subelements.
|
Symbolic Name
|
CODE
|
Definition
|
| CIM_ERR_FAILED |
1 |
A general error occurred that is not covered by a more
specific error
code |
| CIM_ERR_ACCESS_DENIED |
2 |
Access was not available to the client |
| CIM_ERR_NOT_SUPPORTED |
7 |
The requested operation is not supported |
| CIM_ERR_TYPE_MISMATCH |
13 |
The value supplied is incompatible with the type |
Back to contents
2.4.2. Export Methods
This section describes the methods that can be defined within a CIM
Export
Message. These methods operate only on an external data representation
of a CIM entity, namespace or element. Specifically, export
methods
do not operate on CIM Namespaces or CIM elements.
The following export method is defined by this specification:
The convention used in the following subsections to define the
signatures
of the export methods is a pseudo-MOF notation that extends the
standard
MOF BNF [1] for describing CIM export 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
description
purposes only within the scope of this specification, and in particular
a CIM Client MUST NOT specify them in export method invocations.
This notation uses the IN qualifier to denote that the parameter is
an input parameter.
A CIM Client MAY omit an optional parameter in the case that the
required
value is the specified default, by not specifying an
<EXPPARAMVALUE>
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 specified as NULL in an export method call. A NULL (unassigned)
value for a parameter is specified by an <EXPPARAMVALUE> 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 <EXPPARAMVALUE> 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 export method parameters or return values
that
are modeled as standard CIM types (such as string and boolean, or
arrays
thereof) are represented as follows:
- Simple values MUST be represented using the <VALUE>
subelement
within
an <EXPPARAMVALUE> element (for export method parameters) or
within
an <IRETURNVALUE> element (for export
method
return values).
- Array values MUST be represented using the <VALUE.ARRAY>
subelement
within an <EXPPARAMVALUE> element (for export method parameters)
or
within an <IRETURNVALUE> element (for
export
method return values).
The following table describes how each of the pseudo-types used
by the export methods MUST be mapped to an XML element described in [2]
in the context of both a parameter value (subelement of
<EXPPARAMVALUE>)
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 |
Back to contents
2.4.2.1. ExportIndication
This operation is used to export a single CIM Indication to the
destination
CIM Listener.
| ExportIndication |
void ExportIndication (
[IN] <instance>
NewIndication
) |
The NewIndication input parameter defines the Indication to be
exported.
The proposed definition SHOULD be a correct instance definition for the
underlying CIM Indication Class according to the CIM specification [1].
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.
- CIM_ERR_ACCESS_DENIED
- CIM_ERR_NOT_SUPPORTED
- CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
unrecognized
or
otherwise incorrect parameters)
- CIM_ERR_INVALID_CLASS (the CIM Class of which this is to be a new
Instance
does not exist)
- CIM_ERR_FAILED (some other unspecified error occurred)
Back to contents
2.4.3. Functional Profiles
This section partitions the export methods into functional groups for
the
purpose of establishing conformance.
Support for a particular group does not guarantee that all
invocations
of any export method in that group will succeed. Rather, the
exclusion
of a group is a declaration that any attempt to call an export method
in
that group will always return CIM_ERR_NOT_SUPPORTED.
If group G1 has a dependency on functional group G2, then a CIM
Listener
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.
| Functional Group |
Dependency |
Method |
| Indication |
none |
ExportIndication |
Back to contents
3. Encapsulation
of
CIM Messages
This section describes how to use CIM Messages in HTTP. CIM Message
Requests MAY be used with or without using the HTTP Extension Framework.
Although CIM Messages could be used in combination with a variety
of HTTP request methods, this specification only defines CIM Messages
within HTTP POST requests (M-POST MAY be used in place of POST, See
section 3.2 for how to use CIM Messages with the HTTP Extension
Framework).
All CIM Message Responses are carried in the corresponding HTTP
Response.
In the remainder of this document:
- the term CIM Operation
Request
is a convenient shorthand for an HTTP POST request message that
includes an XML entity body which defines an Operation
Request Message, and;
- the term CIM
Operation
Response
is a convenient shorthand for an HTTP response message, issued in
response
to a CIM Operation Request, that includes an entity body which defines
an Operation Response Message.
- the term CIM Export Request is a convenient shorthand for
an HTTP
POST request message that includes an XML entity body which defines
a CIM Export Message request, and;
- the term CIM Export Response is a convenient shorthand for an
HTTP
response
message, issued in response to a CIM Export Message request, that
includes
an entity body which defines a CIM Export Message response, and;
- the phrase CIM Message Request is a convenient shorthand for an
HTTP
POST request message that includes an XML entity body which defines
either a CIM Operation or Export Message Request, and;
- the phrase CIM Message Response is a convenient shorthand for an
HTTP
response
message, issued in response to a CIM Operation Message (or
respectively,
CIM Export Message) request, that includes an entity body which defines
a CIM Operation Message (or respectively, CIM Export Message) response.
Note that an HTTP response to a CIM Request is not always
a CIM Response; for example a "505 HTTP Version Not Supported" response
would not be a CIM Response.
Back to contents
3.1. CIM Clients, CIM Servers
and
CIM Listeners
A CIM Product is any product capable of supplying, consuming, or both
supplying
and consuming management information using the CIM Schema. In
particular,
CIM Clients, CIM
Servers and CIM Listeners are examples of CIM Products.
- A CIM Client is a client
that
issues CIM
Operation Requests- CIM Message Requests and receives and processes
CIM
Operation Responses - CIM Message Responses.
- A CIM Server is a server
that
receives
and processes CIM Operation Message Requests and issues CIM Operation
Message
Responses.
- A CIM Listener is a server
that receives
and processes CIM Export Message Reqests and issues CIM Export Message
Responses.
An CIM Server MAY be capable of acting as any combination of CIM
Client,
CIM Server and CIM Listener. For example, a CIM Server that
supports
Indication Subscription and Generation would act as a CIM Client when
delivering
an Indication, via ExportIndication, to a CIM Listener.
Throughout this document the terms CIM Client, CIM Server, CIM
Listener
and CIM Product are used as convenient shorthand to refer to the subset
of CIM Products that conform to
this specification.
Back to contents
3.2. Use of M-POST
A CIM client attempting a CIM Message
invocation using the HTTP Extension Framework method "M-POST" MUST
follow these steps.
- If the M-POST invocation fails with an HTTP status of "501 Not
Implemented"
or "510 Not Extended", then the client SHOULD retry the request using
the
HTTP method “POST” with the appropriate modifications (described in Naming
of Extension Headers).
- If the M-POST invocation fails with an HTTP status of "405 Method
Not
Allowed",
then the client SHOULD fail the request.
- For all other status codes the client MUST act in accordance with
standard
HTTP [6,7].
This extended invocation mechanism allows Internet proxies &
firewalls
greater filtering control and administrative flexibility over CIM
Message
invocations.
In the case of a client receiving a 501 or 510 status in response to
an M-POST request, then in subsequent invocations to the same HTTP
server,
the client MAY omit the attempt at M-POST invocations for a suitable
period,
thus avoiding the need for an extra round trip on each and every method
invocation. The details of the caching strategy employed by the
client
are outside of the scope of this specification.
Back to contents
3.2.1. Use of the Ext Header
If a CIM Server or CIM Listener receives a
valid M-POST request, and has fulfilled all mandatory extension header
declarations in the request, then it MUST include in the response the
"Ext"
header defined by [9]. This MUST be protected by the appropriate
Cache-Control
directive.
3.2.2. Naming of
Extension Headers
In M-POST request messages (and their responses), CIM extension headers
MUST be declared using the name space prefix allotted by the "Man"
extension
header (in accordance with [9]) that refers to the name space
"http://www.dmtf.org/cim/mapping/http/v1.0".
The full format of the "Man" header declaration for this
specification
is:
| Man
= "Man" ":" "http://www.dmtf.org/cim/mapping/http/v1.0" |
|
";" "ns" "=" header-prefix |
| header-prefix = 2*DIGIT |
This header-prefix SHOULD be generated at random on a per-HTTP
message
basis, and SHOULD NOT necessarily be a specific number.
In accordance with [9], all POST request messages (and their
responses)
MUST NOT include such a mandatory extension declaration. In POST
request
messages (and their responses), name space prefixes MUST NOT be used.
Example 1
Using M-POST:
| M-POST /cimom HTTP/1.1 |
| Man: http://www.dmtf.org./cim/mapping/http/v1.0 ; ns=23 |
| 23-CIMOperation: MethodCall |
| ... |
Example 2
Using POST:
| POST /cimom HTTP/1.1 |
| CIMOperation: MethodCall |
| ... |
Back to contents
3.3. Extension
Headers Defined
for CIM Message Requests and Responses
A CIM Message contains exactly one of the following: CIM Operation
Request, CIM Operation Response, CIM Export Request or CIM Export
Response. This section describes the extension headers used to specify
CIM Message semantics in the HTTP Header of a POST message.
Any CIM Operation Request or CIM
Operation Response MUST, and only CIM Operation Requests and
Responses
MAY, include the following CIM extension header:
Any CIM Operation Request MUST,
and
only CIM Operation Requests MAY, include one and only one of the
following
CIM extension header sets:
Any CIM Export Request or CIM Export Response MUST, and only CIM Export
Requests and Responses MAY, include the following CIM extension header:
Any CIM Export Request MUST, and only CIM Export Requests MAY, include
one and only one of the following CIM extension headers:
- CIMExportMethod
- CIMExportBatch
An HTTP response with an error status code to a CIM Message Request MAY
include the following CIM extension header:
All CIM Messages MAY include the following CIM extension header:
Back to contents
3.3.1. Encoding
of CIM Element Names within HTTP Headers and Trailers
CIM element (class, property, qualifier,
method or method parameter) names are natively Unicode, and may use
UCS-2
characters unsuitable for inclusion within an HTTP message header or
trailer. In order to encode CIM element names represented in Unicode to
values within HTTP Headers or Trailers, the following mapping MUST be
used:
- Encode the full Unicode CIM element name using UTF-8 [15], and
then;
- Apply the standard URI [16, section 2] escaping mechanism to the
resulting
string to escape any characters that are unsafe within an HTTP Header
or
Trailer, using the ""%" HEX HEX" convention).
The token CIMIdentifier, where used in this document,
represents
a CIM element name to which this transformation has been applied.
One characteristic of this mapping is that CIM elements that are
named
with an ASCII representation will appear in ASCII in the resultant URL.
Examples
| CIM_LogicalElement is unchanged under this transformation |
| The class named using the UCS-2 sequence representing the
Hangul characters
for the Korean word "hangugo" (D55C, AD6D, C5B4) becomes
%ED%95%9C%EA%B5%AD%EC%96%B4=10
after UTF-8 transformation and escaping all characters with
their %
HEX HEX equivalent.
|
Back to contents
3.3.2. Encoding
of CIM Object Paths within HTTP Headers and Trailers
This section describes the mapping that MUST be applied in order to
represent
CIM object paths, as described within an Operation
Request Message using the <LOCALNAMESPACEPATH>,
<LOCALCLASSPATH>
or <LOCALINSTANCEPATH> elements, in a format that is safe for
representation
within an HTTP header or trailer.
If the element to be transformed is a <LOCALNAMESPACEPATH>
element,
the algorithm is as follows:
- For the first NAMESPACE subelement, output the textual content of
that
element.
- For each subsequent NAMESPACE subelement, output the forward
slash
character
(/) followed by the textual content of that NAMESPACE element.
If the element to be transformed is a <LOCALCLASSPATH> element,
the
algorithm is as follows:
- Transform the <LOCALNAMESPACEPATH> subelement using the
rules
described
above, and output a colon character (:).
- Output the value of the NAME
attribute
of the <CLASSNAME> subelement.
If the element to be transformed is an <LOCALINSTANCEPATH>
element,
the algorithm is as follows:
- Transform the <LOCALNAMESPACEPATH> subelement using the
rules
described
above, and output a colon character (:).
- Output the value of the CLASSNAME
attribute
of the <INSTANCENAME> subelement.
- If there is at least one <KEYBINDING> subelement under the
<INSTANCENAME>
subelement, then for each such subelement:
- Output a period character (.) if this is the first
<KEYBINDING>
subelement,
and a comma (,) otherwise.
- Output the value of the NAME
attribute,
followed by an equals character (=).
- If there is a <KEYVALUE> subelement, output the textual
element
content
of that element, subject to the following transformation:
- If the VALUETYPE attribute
is numeric
or
boolean, the output is identical to the content of the element.
- If the VALUETYPE attribute
is string,
the
output is obtained by enclosing the content of the element in double
quote
(") characters, and escaping any double quote characters or backslash
character within the value with a preceding backslash (\) character.
- If there is a <VALUE.REFERENCE> subelement
- output a double quote character (").
- apply the process recursively to the <CLASSPATH> or
<INSTANCEPATH>
subelement of the <VALUE.REFERENCE> element, escaping any double
quote
character or backslash character thereby generated with a preceding
backslash
(\) character.
- output a closing double quote character (").
- If there is no <KEYBINDING> subelement but there is a
<KEYVALUE>
or <VALUE.REFERENCE> subelement under the <INSTANCENAME>
subelement,
then:
- Output an equals character (=).
- Output the transformed value of the <KEYVALUE> or
<VALUE.REFERENCE>,
using the same rules as described above.
- If there were no <KEYBINDING> subelements, or no
<KEYVALUE>
or <VALUE.REFERENCE>
subelement, under the <INSTANCENAME> subelement then output the
string
"=@" to indicate a singleton instance.
Finally, after applying the above rules to the
<LOCALNAMESPACEPATH>,
<LOCALCLASSPATH> or <LOCALINSTANCEPATH> element, transform
the entire
output string into URI-safe format as follows:
- Encode the string using UTF-8 [15] if it is not already in this
format,
and then;
- Apply the standard URI [16, section 2] escaping mechanism to the
resulting
string to escape any characters that are unsafe within an HTTP Header
or
Trailer, using the ""%" HEX HEX" convention).
The token CIMObjectPath, where
used
in this document, represents a <LOCALNAMESPACEPATH>,
<LOCALCLASSPATH>
or <LOCALINSTANCEPATH> element to which the above transformation
has
been applied.
Back to contents
3.3.3. CIMOperation
This header MUST be present in all CIM
Operation Request and CIM
Operation
Response messages. It identifies the HTTP message as carrying
a CIM Operation request or response.
| CIMOperation = "CIMOperation" ":" ("MethodCall" |
"MethodResponse") |
A CIM Client MUST include this header,
with
the value "MethodCall", in all CIM Operation Requests that it
issues.
A CIM Server MUST include this header in
all
CIM Operation Responses, with the value "MethodResponse", that it
issues.
If a CIM Server receives CIM Operation request with this header, but
with a missing value or a value that is not "MethodCall", then it MUST
fail the request with status "400 Bad Request". The CIM Server MUST
include
a CIMError header in the response with a
value
of unsupported-operation.
If a CIM Server receives a CIM Operation request without this
header,
it MUST NOT process it as if it were a CIM Operation Request. The
status code returned by the CIM Server in response to such a request is
outside of the scope of this specification.
If a CIM Client receives a response to a CIM Operation Request
without
this header (or if this header has a value which is not
"MethodResponse"),
it SHOULD discard the response, and take appropriate measures to
publicize
the fact that it has received an incorrect response. The details
as to how this is done are outside of the scope of this specification.
This header affords a simple mechanism by which firewall or proxy
administrators
can make global administrative decisions on all CIM Operations.
Back to contents
3.3.4. CIMExport
This header MUST be present in all CIM Export Request and CIM Export
Response messages. It identifies the HTTP message as carrying a
CIM
Export method request or response. CIMExport = "CIMExport" ":"
("MethodRequest"
| "MethodResponse")
A CIM Client MUST include this header, with the value
"MethodRequest",
in all CIM Export Requests that it issues. A CIM Listener MUST
include
this header in all CIM Export Responses, with the value
"MethodResponse",
that it issues.
If a CIM Listener receives a CIM Export request with this header,
but
with a missing value or a value that is not "MethodRequest", then it
MUST
fail the request with status "400 Bad Request". The CIM Listener
MUST include a CIMError header in the response with a value of
unsupported-operation.
If a CIM Listener receives a CIM Export request without this header,
it MUST NOT process it. The status code returned by the CIM
Listener
in response to such a request is outside of the scope of this
specification.
If a CIM Client receives a response to a CIM Export Request without
this header (or if this header has a value which is not
"MethodResponse”),
it SHOULD discard the response, and take appropriate measures to
publicize
the fact that it has received an incorrect response. The details
as to how this is done are outside of the scope of this specification.
This header affords a simple mechanism by which firewall or proxy
administrators
can make global administrative decisions on all CIM Exports.
Back to contents
3.3.5. CIMProtocolVersion
This header MAY be present in any CIM Message. The header
identifies
the version of the CIM Operations over HTTP Specification being used by
the sending entity.
| CIMProtocolVersion = "CIMProtocolVersion" ":" 1*DIGIT "."
1*DIGIT |
If the header is omitted, then a value of 1.0 MUST be assumed.
The major and minor revision numbers
MUST be treated as independent integers.
The CIMProtocolVersion x1.y1
is less than
CIMProtocolVersion x2.y2
if
and only if:
- x1 is less than x2, or;
- x1 equals x2, and y1 is less
than y2
The CIMProtocolVersion x1.y1 is greater than CIMProtocolVersion x2.y2
if
and only if:
- x1 is greater than x2, or;
- x1 equals x2, and y1 is greater
than y2
A CIMProtocolVersion x1.y1 is within tolerance of CIMProtocolVersion
x2.y2 if:
- x1 equals x2, and
- y1 is less than or equal to y2
If the the CIMProtocolVersion of the CIM Message
received
is within tolerance of CIMProtocolVersion supported for a CIM Server or CIM
Listener implementation,
the receiving implementation MUST accept that CIM Messages.
Equivalent
CIMProtocolVersion values between CIM Server or CIM
Listener and the CIM Client MUST be accepted.
The CIM
Server or CIM
Listener
implementation MAY reject a CIM Message in all other cases. The
section on Errors
and Status Codes describes how
CIM Messages are rejected.
Beyond tolerance considerations, the
implementation SHOULD reject the received CIM Message only if the design as defined by the
CIMProtocolVersion of
the receiving implementation has changed in the declaration of the API,
method parameters, or behavior since the design defined by
CIMProtocolVersion of the received CIM Message.
Back to contents
3.3.6. CIMMethod
This header MUST be present in any CIM
Operation Request message that contains a Simple
Operation Request.
It MUST NOT be present in any CIM
Operation Response message, nor in any CIM
Operation Request message that is not a Simple Operation
Request.
It MUST NOT be present in
any CIM Export Request or Response message
The header identifies the name of the CIM method to be invoked,
encoded
in an HTTP-safe
representation.
Firewalls and proxies may use this header to carry out routing and
forwarding
decisions based on the CIM method to be invoked.
The name of the CIM method within a Simple Operation Request is
defined
to be the value of the NAME attribute
of
the <METHODCALL> or <IMETHODCALL> element.
| CIMMethod = "CIMMethod" ":" MethodName |
| MethodName = CIMIdentifier |
If a CIM Server receives a CIM
Operation
Request for which either:
- The CIMMethod header is present but has an invalid value, or;
- The CIMMethod header is not present but the Operation Request
Message
is
a Simple Operation Request,
or;
- The CIMMethod header is present but the Operation Request Message
is
not
a Simple Operation Request, or;
- The CIMMethod header is present, the Operation Request Message is
a
Simple
Operation Request, but the CIMIdentifier value (when unencoded) does
not
match the unique method name within the Simple Operation Request,
then it MUST fail the request and return a status of "400 Bad Request"
(and MUST include a CIMError header in the
response
with a value of header-mismatch),
subject
to the considerations specified in Errors.
Note that this verification provides a basic level of
assurance
that any intermediate firewall or proxy was not acting on misleading
information
when it decided to forward the request based on the content of the
CIMMethod
header. Additional securing of HTTP messages against modification
in transit (such as the encryption of the payload or appending of a
digital
signature thereto) would be required to provide a higher degree of
integrity.
Back to contents
3.3.7. CIMObject
This header MUST be present in any CIM
Operation Request message that contains a Simple
Operation Request.
It MUST NOT be present in any CIM
Operation Response message, nor in any CIM
Operation Request message that that is not a Simple Operation
Request.
It MUST NOT be
present in any CIM Export Request or Response message.
The header identifies the CIM object (which MUST be a Class or
Instance
for an extrinsic method, or a Namespace
for
an intrinsic method) on which the method
is
to be invoked, using a CIM object path encoded in an HTTP-safe
representation. Firewalls and proxies may use this header to
carry out routing and forwarding decisions based on the CIM object that
is the target of a method invocation.
| CIMObject = "CIMObject" ":" ObjectPath |
| ObjectPath = CIMObjectPath |
The ObjectPath value is constructed by applying the algorithm
defined
in Encoding
CIM
Object Paths to either:
- The <LOCALNAMESPACEPATH> subelement of the
<IMETHODCALL>
element,
or;
- The <LOCALCLASSPATH> or <LOCALINSTANCEPATH>
subelement of
the <METHODCALL>
element
within the CIM Operation Request.
If a CIM Server receives a CIM
Operation
Request for which either:
- The CIMObject header is present but has an invalid value, or:
- The CIMObject header is not present but the Operation Request
Message
is
a Simple Operation Request,
or;
- The CIMObject header is present but the Operation Request Message
is
not
a Simple Operation Request, or;
- The CIMObject header is present, Operation Request Message is a
Simple
Operation Request, but the ObjectPath value does not match (where match
is
defined in the section on Encoding
CIM Object Paths) the Operation Request Message,
then it MUST fail the request and return a status of "400 Bad Request"
(and MUST include a CIMError header in the
response
with a value of header-mismatch),
subject
to the considerations specified in Errors.
Note that this verification provides a basic level of
assurance
that any intermediate firewall or proxy was not acting on misleading
information
when it decided to forward the request based on the content of the
CIMObject
header. Additional securing of HTTP messages against modification
in transit (such as the encryption of the payload or appending of a
digital
signature thereto) would be required to provide a higher degree of
integrity.
Back to contents
3.3.8. CIMExportMethod
This header MUST be present in any CIM Export Request message that
contains
a Simple Export Request.
It MUST NOT be present in any CIM Export Response message, nor in
any
CIM Export Request message that is not a Simple Export Request. It MUST
NOT be present in any CIM
Operation Request or Response message.
The header identifies the name of the CIM export method to be
invoked,
encoded in an HTTP-safe representation. Firewalls and proxies may
use this header to carry out routing and
forwarding decisions based on the CIM export method to be invoked.
The name of the CIM export method within a Simple Export Request is
defined to be the value of the NAME attribute of the
<EXPMETHODCALL>
element.
CIMExportMethod = "CIMExportMethod" ":" ExportMethodName
ExportMethodName = CIMIdentifier
If a CIM Listener receives a CIM Export Request for which either
- The CIMExportMethod header is present but has an invalid value,
or;
- The CIMExportMethod header is not present but the Export Request
Message
is a Simple Export Request, or;
- The CIMExportMethod header is present but the Export Request
Message is
not a Simple Export Request, or;
- The CIMExportMethod header is present, the Export Request Message
is a
Simple Export Request, but the CIMIdentifier value (when unencoded)
does
not match the unique method name within
the
Simple Export Request,
then it MUST fail the request and return a status of "400 Bad Request"
(and MUST include a CIMError header in the response with a value of
header-mismatch),
subject to the
considerations specified in Errors.
Note that this verification provides a basic level of assurance that
any intermediate firewall or proxy was not acting on misleading
information
when it decided to forward the request based on the content of the
CIMExportMethod
header. Additional securing of HTTP messages against modification
in transit (such as the encryption of the payload or appending of a
digital
signature thereto) would be required to provide a higher degree of
integrity.
Back to contents
3.3.9. CIMBatch
This header MUST be present in any CIM
Operation Request message that contains a Multiple
Operation Request.
It MUST NOT be present in any CIM
Operation Response message, nor in any CIM
Operation Request message that is not a Multiple Operation
Request.
It MUST NOT be present
in any CIM Export Request or Response message.
The header identifies the encapsulated Operation Request Message as
containing multiple method invocations. Firewalls and proxies may
use this header to carry out routing and forwarding decisions for
batched
CIM method invocations.
| CIMBatch = "CIMBatch" ":" |
If a CIM Server receives a CIM
Operation
Request for which either:
- The CIMBatch header is present but has an invalid value, or:
- The CIMBatch header is not present but the Operation Request
Message is
a Multiple Operation Request, or;
- The CIMBatch header is present but the Operation Request Message
is not
a Multiple Operation Request,
then it MUST fail the request and return a status of "400 Bad Request"
(and MUST include a CIMError header in the
response
with a value of header-mismatch),
subject
to the considerations specified in Errors.
Note that this verification provides a basic level of
assurance
that any intermediate firewall or proxy was not acting on misleading
information
when it decided to forward the request based on the content of the
CIMBatch
header. Additional securing of HTTP messages against modification
in transit (such as the encryption of the payload or appending of a
digital
signature thereto) would be required to provide a higher degree of
integrity.
If a CIM Server receives a CIM Operation Request for which the
CIMBatch
header is present, but the Server does not support Multiple Operations,
then it MUST fail the request and return a status of "501 Not
Implemented".
Firewalls or Proxies MAY also employ this mechanism to compel a CIM
Client to use Simple Operation Requests rather than Multiple
Operation
Requests.
A CIM Client that receives a response of "501 Not Implemented" to a
Multiple Operation Request SHOULD resubmit that request as a series of
Simple Operation Requests.
Back to contents
3.3.10. CIMExportBatch
This header MUST be present in any CIM Export Request message that
contains
a Multiple Export Request.
It MUST NOT be present in any CIM Operation Request or Response
message.
It MUST NOT be present in any CIM Export Response Message, nor in any
CIM
Export Request message that is not a Multiple Export Request.
The header identifies the encapsulated Export Request Message as
containing
multiple export method invocations. Firewalls and proxies may use this
header to carry out routing and forwarding decisions for batched CIM
Export
method invocations.
CIMExportBatch = "CIMExportBatch" ":"
If a CIM Listener receives a CIM Export Request for which either:
- The CIMExportBatch header is present but has an invalid value, or:
- The CIMExportBatch header is not present but the Export Request
Message
is a Multiple Export Request, or;
- The CIMExportBatch header is present but the Export Request
Message is
not a Multiple Export Request,
then it MUST fail the request and return a status of "400 Bad Request"
(and MUST include a CIMError header in the response with a value of
header-mismatch),
subject to the considerations specified in Errors.
Note that this verification provides a basic level of assurance that
any intermediate firewall or proxy was not acting on misleading
information
when it decided to forward the request based on the content of the
CIMExportBatch
header. Additional securing of HTTP messages against modification in
transit
(such as the encryption of the payload or appending of a digital
signature
thereto) would be required to provide a higher degree of integrity.
If a CIM Listener receives a CIM Export Request for which the
CIMExportBatch
header is present, but the CIM Listener does not support Multiple
Exports,
then it MUST fail the request and return a status of "501 Not
Implemented".
Firewalls or Proxies MAY also employ this mechanism to compel a CIM
Client
to use Simple Export Requests rather than Multiple Export Requests.
A CIM Client that receives a response of "501 Not Implemented" to a
Multiple Export Request SHOULD resubmit that request as a series of
Simple
Export Requests.
Back to contents
3.3.11. CIMError
This header MAY be present in any HTTP response to a CIM Message
Request
that is not a CIM Message Response.
It MUST NOT be present in any CIM Message Response , nor in any CIM
Message request.
The header provides further CIM specific diagnostic information in
the
case that the CIM Server or CIM
Listener encountered a fundamental error during processing of the
CIM
Operation Request, and is intended to assist Clients to further
disambiguate
errors that have the same HTTP status code.
| CIMError = "CIMError" ":" cim-error
cim-error = "unsupported-protocol-version" |
"multiple-requests-unsupported" |
"unsupported-cim-version" |
"unsupported-dtd-version" |
"request-not-valid" |
"request-not-well-formed" |
"request-not-loosely-valid" |
"header-mismatch" |
"unsupported-operation"
|
Back to contents
3.3.12. CIMRoleAuthenticate
A CIM Server MAY return a CIMRoleAuthenticate header as part of the 401
Unauthorized response along with the WWW-Authenticate header. The
CIMRoleAuthenticate header has a challenge set to indicate what policy
the CIM Server has regarding role credentials.
challenge = "credentialrequired" |
"credentialoptional" | "credentialnotrequired"
- A challenge of credentialrequired indicates that the CIM
Server REQUIRES that if a CIM Client wants to assume a role, then a
credential
MUST be presented.
- A challenge of credentialoptional indicates that the
credential
is optional. In the case where a credential is not sent, the CIM Server
will allow the role assumption if permitted for the given user, however
it is possible that certain operations that require the role credential
may not succeed.
- A challenge of credentialnotrequired indicates that no
credential
is required to assume the role.
Absence of the CIMRoleAuthenticate header indicates that the CIM
Server does not support role assumption. A CIM Client SHOULD handle
each of these cases appropriately.
The challenge does not contain any authorization scheme, realm or
other information. A CIM Client should extract this information from
the WWW-Authenticate header. This implies that for any given request
the role
credentials should use the same scheme as those required for the user
credentials.
A CIM Server only allows role assumption to succeed if the user is
allowed to assume the role. This means that even if appropriate
credentials
are presented, role assumption could fail. If either the user
authentication
or role assumption fails, the entire authentication operation fails.
To maintain backward compatibility, a CIM Server which supports role
assumption MUST allow user authentication even if no role is specified.
Back to contents
3.3.13. CIMRoleAuthorization
This header is supplied along with the normal Authorization header that
the CIM Client populates to perform user authentication. If the CIM
Client wishes to perform role assumption and the server challenge is
credentialrequired, the CIMRoleAuthorization header MUST be supplied
with the appropriate credentials. The credentials that are supplied as
part of the CIMRoleAuthorization header MUST use the same scheme as
those specified for the Authorization header, as specified in IETF RFC
2617. In this way both Basic and Digest authentication are possible for
role credential.
If the CIM Client wishes to assume a role, but does not wish to
supply any role credentials for server challenge credentialoptional or
credentialnotrequired, the CIMRoleAuthorization header MUST set the
auth-scheme field as specified in IETF RFC 2617 to be "role". The
auth-param MUST contain the role name.
A CIM Server which supports roles MUST be capable of handling the
presence of credentials in the CIMRoleAuthorization header (that is
auth-scheme not set to "role") regardless of whether it is expecting
credentials or not. It MAY choose to ignore these credentials.
Back to contents
3.3.15.
CIMStatusCodeDescription
If a CIM Product includes the CIMStatusCode trailer, it MAY also
include the CIMStatusCodeDescription trailer. The value of this trailer
will be a string describing the nature of the error. A CIM Product MUST
NOT include this trailer if the CIMStatusCode trailer is not present.
Back to contents
3.3.16.
WBEMServerResponseTime
This header MAY be present in any CIM Response Message. If present,
the header MUST contain a measure, specified in microseconds, of the
elapsed time required by the CIM Server to process the request and
create a response. Specifically, WBEMServerResponseTime describes the
time that has elapsed since the CIM Server received the CIM Request
Message and the associated CIM Response Message was ready to be sent to
the CIM Client.
WBEMServerResponseTime = "WBEMServerResponseTime" ":" , where
MUST be representable as a 64-bit unsigned integer value. If the actual
elapse time exceeds the maximum representable value, then the maximum
value MUST be returned. If the actual elapse time is less than 1
microsecond, then a 0 MUST be returned.
Although a CIM Client MAY ignore the WBEMServerResponseTime header,
it MUST allow this header to be included in a response.
Back to contents
4. HTTP Requirements
& Usage
4.1. HTTP Support
It is RECOMMENDED that CIM Clients, CIM
Servers and CIM Listeners support
HTTP/1.1
[7]. CIM Clients, CIM Servers and CIM Listeners MAY support
HTTP/1.0.
CIM Clients, CIM Servers, and CIM Listeners MUST NOT be limited to any
version of HTTP earlier than 1.0.
It should be noted that the current revised draft [10] of RFC 2068
clarifies
and corrects ambiguities and errors in that RFC.
CIM Products that make use of extension headers as defined in this
specification
MUST conform to the requirements defined in [9] for their use.
Back to contents
4.2. Use of Standard Headers
Unless otherwise stated herein, CIM Products MUST comply with the
requirements
on the use of headers described in [6,7]. This section defines only any
additional
requirements
on CIM Products with respect to the use of standard HTTP headers [6,7]
within a CIM Message.
Note that headers defined in RFC 2068 [7] but deprecated from [10]
(e.g.
Public, Content-Base) SHOULD NOT be used by CIM Products.
4.2.1. Accept
If a CIM client includes an Accept header
in
a request, it MUST specify a value which allows the Server to return an
entity body of "text/xml" or "application/xml" in the response.
A CIM server or CIM
Listener MUST accept any value for this header which states that
"text/xml"
or "application/xml" is an acceptable type for an response
entity.
A CIM Server or CIM Listener SHOULD return "406 Not Acceptable" if the
Accept header indicates that neither of these content types are
acceptable.
If a CIM server or CIM Listener decides to accept a request to
return
an entity of type other than "text/xml" or "application/xml", the
nature
of the response is outside of the domain of this specification.
Back to contents
4.2.2. Accept-Charset
If a CIM client includes an
Accept-Charset
header in a request, it MUST specify a value which allows the CIM
Server or CIM Listener to return an entity body using the character set
"UTF-8".
A CIM server or CIM
Listener MUST accept any value for this header which asserts that
"UTF-8" is an acceptable character set for an response
entity. If
the Accept-Charset is not provided by the client, then "UTF-8" SHOULD
be assumed by the CIM server or CIM Listener.
A CIM Server or CIM Listener MUST return "406 Not Acceptable" if the
character set requested in the Accept-Charset header is not supported
If a CIM Server or CIM Listener decides to accept a request to
return an entity using a character set other than "UTF-8", the behavior
of the
subsequent CIM Client and CIM Server interaction is outside this
specification
See Internationalization
Considerations for more details.
Back to contents
4.2.3. Accept-Encoding
If a CIM client includes an
Accept-Encoding
header in a request, it MUST specify a value which allows the CIM
Server
or CIM Listener to use the "Identity" encoding. The q value MUST
be greater than 0 or not specified.
Accept-Encoding: Identity
Accept-Encoding: Identity; q=1.0
A CIM server or CIM Listener MUST accept any value for this
header which asserts that "Identity" is an acceptable encoding for the
response entity.
A CIM Server or CIM Listener MUST return "406 Not Acceptable" if the
Accept-Encoding header indicates that the requested encoding is not
acceptable.
Back to contents
4.2.4. Accept-Language
If a CIM Client includes an Accept-Language header in a request, it
MUST request a language-range, special-range, or both. The CIM
Client MUST also allow for any language to be returned if the requested
languages can not be supported. This is accomplished by including
the special-range, "*". The CIM Client may request multiple
languages. Each language has equal priority,
unless a qvalue is provided.
Accept-Language: zh, *
Accept-Language: zh;q=1.0, en;q=.7, *
Each CIM Element in the response SHOULD be localized in only
one language. A CIM Element MUST NOT be duplicated in the
response because it was localized in more than one language.
CIM Servers MAY support multiple languages. Use of the
special-range value, "*", MUST be interpreted by a CIM Product as a
request to return the response content using the default language
defined for the target processing the request. Multiple
targets, with different default language settings, MAY participate in
the construction of a response.
See RFC 2616, section 3.10. See ISO 639-1.
See Internationalization
Considerations for more details.
Back to contents
4.2.5. Accept-Ranges
CIM Clients MUST NOT include this header in
a request. A CIM Server or CIM
Listener MUST reject a request that includes an Accept-Range header
with a status of "406 Not Acceptable".
Back to contents
4.2.6. Allow
If a CIM Server or CIM
Listener is returning a "405 Method Not Allowed" response to
a CIM Message Request then the Allow header MUST include either M-POST
or POST. Whether it includes any other HTTP methods is outside
the
scope of this specification.
Back to contents
4.2.7. Authorization
See the section on Security
Considerations
for more details.
Back to contents
4.2.8. Cache-Control
In general a CIM Message Request may consist of a mixture of CIM method
invocations, some of which may be eminently cachable (e.g. the
Manufacturer
label on a Disk Drive), and some of which may be decidedly uncachable
(e.g.
format a Disk Drive).
Furthermore, the encapsulation of such multiple method invocations
within
an HTTP POST or M-POST means that if a CIM Message Request has any
effect
on an HTTP cache it is likely to be one of invalidating cached
responses
for the target CIM Server or CIM Listener. Indeed HTTP/1.1[7]
stipulates
that by default POST responses are not cachable unless the server
indicates
otherwise using an appropriate Cache-Control or Expires header.
For these reasons, CIM Message Responses SHOULD NOT be considered
cachable.
A CIM Server or CIM
Listener SHOULD NOT include a Cache-Control header in a CIM Message
response which might indicate to a cache that the response could be
cached.
If the CIM Server or CIM Listener is responding to a CIM Message
Request
conveyed within an M-POST request, then in accordance with [9] the CIM
Server or CIM Listener MUST include a no-cache control directive to
prevent
inadvertent caching of the "Ext" header. For example:
| HTTP/1.1 200 OK |
| Ext: |
| Cache-Control: no-cache |
| ... |
Back to contents
4.2.9. Connection
It is RECOMMENDED that
- CIM Clients should avoid the use of
the
"Connection:
close" header unless it is known in advance that this is the only
request
likely to be sent out on that connection.
- CIM Servers and CIM
Listener support persistent connections wherever possible.
Timeout mechanisms SHOULD be employed to remove idle connections on the
CIM Client, CIM Server and CIM Listener, the details of which are
outside
the domain of this specification. Clients SHOULD be cautious in
retrying
requests, especially if they are not idempotent (e.g. method
invocation).
CIM Clients, CIM Servers and CIM Listeners SHOULD support pipelining
[7, section 1.1.2.2] if possible, but be aware of the requirements
defined
in [7]. In particular, attention is drawn to the following
requirement
from [7]:
Clients SHOULD NOT pipeline
requests
using non-idempotent methods or non-idempotent sequences of
methods. A
client wishing to send a non-idempotent request SHOULD wait to send
that
request until it has received the response status for the previous
request.
Back to contents
4.2.10. Content-Encoding
If a CIM client includes a
Content-Encoding
header in a request, it SHOULD specify a value of "identity", unless it
has good reason to believe that the server or listener can accept
another
encoding.
Back to contents
4.2.11. Content-Language
The Content-Language entity-header field of a CIM Message describes
the natural language(s) of the intended audience of the content.
A CIM Message MAY contain a Content-Language header. The value of
the Content-Language header in a CIM Response Message MUST be
consistent with the Accept-Language values specified in the
corresponding CIM Request Message. If the CIM Server can not determine
one or more of the content
languages used to construct the response, then the Content-Language
entity MUST NOT be returned.
Multiple targets, using different Content-Language values, MAY
participate in the construction of a response. The
Content-Language field MUST reflect all Content-Language values used to
construct the response. The content of a CIM Message MAY contain
elements in languages not listed in the Content-Language field.
See Internationalization
Considerations for more details.
Back to contents
4.2.12. Content-Range
CIM clients, CIM
servers and CIM Listeners MUST NOT
use
this header.
Back to contents
4.2.13. Content-Type
CIM clients, CIM
servers
and CIM Listeners MUST specify
(and
accept) a value for this header of either "text/xml" or
"application/xml"
as defined in [18].
Back to contents
4.2.14. Expires
For the same reasons described in Cache-Control,
a CIM Server or CIM
Listener SHOULD NOT include an Expires header in a CIM Message
Response
which might indicate to a cache that the response could be cached.
Back to contents
4.2.15. If-Range
CIM Clients, CIM
Servers
and CIM Listeners MUST NOT use this
header.
Back to contents
4.2.16. Proxy-Authenticate
See the section on Security
Considerations
for more details.
Back to contents
4.2.17. Range
CIM Clients, CIM
Servers
and CIM Listeners MUST NOT use this
header.
Back to contents
4.2.18. WWW-Authenticate
See the section on Security
Considerations
for more details.
Back to contents
4.3. Errors and Status Codes
This section defines how CIM Servers and CIM
Listeners MUST handle errors that occur in the processing of a CIM
Message Request. This specification does not introduce any new HTTP
response
status codes.
If there is an error in processing the HTTP Request-Line or standard
HTTP Headers then the CIM Server or CIM Listener MUST take the
appropriate
action as dictated by its conformance to the relevant version of HTTP
[6,7].
Otherwise, if there are any mandatory extension declarations which
the
server does not support it MUST respond with a "510 Not Extended"
status
according to [9].
Otherwise, the request MUST be processed in accordance with the
relevant
version of HTTP [6,7] and the additional rules defined in this
document.
Assuming that the HTTP request is otherwise correct, the CIM Server
or CIM Listener MUST use the following status codes when processing the
CIM Extension Headers:
501 Not Implemented One
of
the following occurred:
- The CIMProtocolVersion
extension
header
specified in the request specifies a version of the CIM Mapping onto
HTTP
which is not supported by this CIM Server or CIM Listener. The CIM
Server
or CIM Listener MUST include a CIMError
header
in the response with a value of unsupported-protocol-version.
- The Client specified a Multiple
Operation Request (or Multiple Export Request) and the CIM Server
(or
CIM Listener) does not support such requests. The CIM Server or CIM
Listener
MUST include a CIMError header in the
response
with a value of multiple-requests-unsupported.
- The CIMVERSION attribute in the Message Request was not set to
a proper
value. The CIMVERSION attribute MUST be in the form of "M.N".
Where
M is the major revision of the specification in numeric form and N is
the
minor revision of the specification in numeric form. The version MUST
be
at "2.0" or greater. For example, "2.0" or "2.3". The CIM
Server
or CIM Listener MUST include a CIMError header in the response with a
value
of unsupported-cim-version.
- The DTDVERSION attribute in the Message Request was not set to
a proper
value. The DTDVERSION attribute MUST be in the form of "M.N". Where M
is
the major revision of the specification in numeric form and N is the
minor
revision of the specification in numeric form. The version MUST be at
"2.0"
or greater. For example, "2.0" or "2.1". The CIM Server or
CIM Listener MUST include a CIMError header in the response with a
value
of unsupported-dtd-version.
401 Unauthorized The CIM Server or CIM Listener is configured
to
require that a client authenticate itself before it can issue CIM
Message
Requests to the server or listener.
403 Forbidden The CIM Server or CIM Listener does not allow
the
client to perform issue CIM Message Requests. The CIM Server or
CIM
Listener MAY alternatively respond with a "404 Not Found" if it does
not
wish to reveal this information to the client.
407 Proxy Authentication Required The CIM Server or CIM
Listener
is configured to require that the proxy authenticate itself before it
can
issue CIM Message Requests on behalf of a CIM Client to the server or
listener.
Assuming that the CIM Extension Headers are correct, then a validating
CIM Server or CIM Listener (one which is enforcing validity of the CIM
Message Request with respect to the CIM XML DTD) MUST use the following
status code when processing the entity body containing the CIM Message
Request.
400 Bad Request The
entity
body defining the CIM Message Request was not well-formed or not valid
with respect to the CIM XML DTD. The CIM Server or CIM Listener MUST
include
a CIMError header in the response with a
value
of request-not-well-formed or request-not-valid
(as appropriate).
A loosely-validating CIM Server or CIM Listener (one that is only
enforcing
that the CIM Message Request be loosely
valid)
MAY reject an CIM Message Request that is not loosely valid with an
HTTP
status code of 400 (Bad Request) before further processing, in which
case
the CIM Server or CIM Listener MUST include a CIMError
header in the response with a value of request-not-loosely-valid.
A loosely-validating CIM Server or CIM Listener MUST reject an CIM
Message
Request that is not well-formed with an HTTP status code of 400 (Bad
Request),
in which case the CIM Server or CIM Listener MUST include a CIMError
header in the response with a value of request-not-well-formed.
A loosely-validating CIM Server or CIM Listener MUST NOT reject an
invalid
(in the XML sense) CIM Message Request that is loosely valid.
A loosely-validating CIM Server or CIM Listener MUST ultimately
signal
an error to the CIM Client if the CIM Message Request is not loosely
valid
(i.e. is missing required content, or for which the required content is
incorrect, such as an attribute with an invalid value according to the
CIM XML DTD). It is not mandated to reject a CIM Message Request
before processing, for to do otherwise would compel the server or
listener
into checking the complete request before processing could begin and
this
would be as expensive as requiring that the server or listener fully
validate
the request. Therefore a loosely-validating server or listener MAY
elect
to begin processing the request and issuing a response (with an HTTP
success
status code) before checking that the entire request is loosely valid.
A CIM Client may determine whether a CIM Server and CIM Listener is
validating or loosely-validating via the CIMValidation
header mechanism.
Assuming that the CIM Message Request was correctly formed (in the
manner
described above), the CIM Server or CIM Listener MUST process the
request
accordingly and return a CIM Message Response.
The entity body MUST be a correct CIM Message Response for that
request.
If the CIM Message Response contains an entity which is a Simple
Message
response then the response status MUST be 200 OK.
Otherwise
the response status MUST be 207 Multistatus .
Back to contents
4.4. Security
Considerations
CIM Clients, CIM
Servers
and CIM Listeners MAY elect not to use
authentication,
but only in environments where lack of security is not an issue.
Basic Authentication is described in [6,7]. Digest
Authentication
is defined in [12]. Both authentication schemes are covered in a
consolidated document [14] which also makes a number of improvements to
the original specification of Digest Authentication.
Basic Authentication provides a very rudimentary level of
authentication,
with the major weakness that the client password is sent over the wire
in unencrypted form.
For this reason CIM clients, CIM
servers and CIM Listeners MUST NOT
use
Basic Authentication other than in the context of a highly secure
environment
(for example, if used in conjunction with SSL, or in a physically
secure
private network). CIM Servers and CIM Listeners MUST NOT send
Basic
Authentication credentials in a WWW-Authenticate header other than in
the
context of a highly secure environment.
Conforming applications SHOULD support the Digest authentication
scheme.
Since Digest authentication verifies that both parties share a common
secret,
without having to send that secret in the clear, it is more secure than
Basic authentication. However, CIM Clients, CIM Servers and CIM
Listeners
that require more robust protection SHOULD use encryption mechanisms
such
as SSL or SHTTP.
CIM Clients, CIM Servers and CIM Listeners using Basic or Digest
Authentication
MUST comply with the requirements set forth in [6,7,12,14]. This
specification describes only additional requirements on CIM
Clients
and CIM Servers and CIM Listeners when using these authentication
schemes.
CIM Servers and CIM Listeners SHOULD require that CIM Clients
authenticate
themselves. This specification does not mandate this as it is
recognized
that in some circumstances the CIM Server and CIM Listener MAY NOT
require
or wish the overhead of employing authentication. CIM Servers and
CIM Listeners SHOULD consider carefully the performance/security
tradeoffs
in determining how often to issue challenges to CIM Clients.
A CIM Server or CIM Listener that returns a "401 Unauthorized"
response
to a CIM Message Request SHOULD include in the WWW-Authenticate
response-header
either the "Basic" or "Digest" authentication values (but not
both).
This specification does not mandate use of Basic or Digest
Authentication
as it is recognized that in some circumstances the CIM Server or CIM
Listener
MAY use bespoke authentication mechanisms not covered by
[14].
Similar considerations apply to the use of the Proxy-Authorization
header
in "407 Proxy Authentication Required".
Back to contents
4.5. Determining
CIM Server Capabilities
If a CIM Server is capable of returning capabilities information there
are two techniques for returning that information defined in this
specification.
The preferred technique is through the use of the classes defined in
section
4.5.1. Alternatively, the use of the HTTP OPTIONS method as defined in
section 4.5.2 is allowed because historically it was the original
technique
defined for requesting capabilities information. The use of the CIM
classes
defined in section 4.5.1 is strongly encouraged and it is expected that
this method will be enhanced and extended in the future to provide more
capabilities information. The use of the HTTP OPTIONS method to
determine
capabilities of CIM Servers is discouraged in the future. It will
probably
not be expanded significantly in the future and may be reviewed for
possible
deprecation in the next major revision of this specification.
4.5.1 Determining CIM Server Capabilities
through CIM
Classes
A set of CIM classes has been defined specifically to return CIM Server
capabilities information as follows:
CIM_ObjectManager - A type of
CIM_Service
that defines the capabilities of the target CIM Server
CIM_ObjectManagerCommunicationMechanism
- Class that describes access to the target CIM Server that defines the
capabilities of the CIM Server available through the target Object
Manager
Communication Mechanism. It is allowable for a CIM server to support
different
capabilities through different Communication Mechanisms.
CIM_CIMXMLCommunicationMechanism -
This
class specializes ObjectManagerCommunicationMechanism, adding
properties
specific to the CIM-XML encoding and protocol.
CIM_CommMechanismForManager -
Association
between CIM_ObjectManager and CIM_ObjectManagerCommunicationsMechanism
which defines the communications protocols (and corresponding
capabilities)
available on the target CIM Server through the
ObjectManagerCommunicationMechanism
instances.
Instances of these CIM classes MAY be used by a CIM Client to
determine
the CIM capabilities (if any) of the target CIM Server. A CIM server
that
supports capabilities determination through these classes MUST support
at least the Enumerate Instance and Get Instance operations for the
classed
defined above. The use of other methods of the basic read profile
is optional. A CIM Server that does not support the determination of
CIM
capabilities through these classes MUST return CIM_ERR_NOT_FOUND to any
instance or class request on these classes. These classes MUST NOT be
used
for reporting any other information than capabilities of the target CIM
Server.
To provide interoperability, the CIM Object Manager classes MUST
exist
in a well-known namespace. Because there is no discovery mechanism
defined
that could define this well-known namespace to a CIM Client, it MUST be
one or more predefined namespaces. Therefore, in this specification we
recommend that pending future extensions of the WBEM specifications to
include discovery tools that define a namespace for these classes in a
CIM Server, to insure interoperability these should exist in either the
root namespace or in the /root/CIMV2 namespace.
A CIM Server that supports capabilities reporting through these
classes
MUST report correctly the current actual capabilities of the target CIM
Server and MUST report on all of the capabilities defined. It is
allowable
for a CIM Server to report "none" if the capability does not exist or
"unknown"
if the status of the capability is unknown at the time of the request
for
those properties where these choices exist in the properties
definition.
Because the CIM_ObjectManager object provides information on the target
CIM Server only a single instance of this class may exist in a CIM
server.
The capabilities to be reported through
CIM_ObjectManagerCommunicationMechanism
are as follows:
CommunicationMechanism property which
defines the communication protocol for the CommunicationMechanism
object.
A compliant CIM Server MUST include the CIM-XML protocol for at least
one
ObjectManagerCommunicationMechanism instance.
ProfilesSupported property that
defines
the functional profiles supported as defined in section 2.6.All CIM
Servers
MUST support the basic-read functional group. All CIM Clients MAY
assume
that any CIM Server supports the basic-read functional group. The list
of functional groups returned by a CIM Server MUST contain the
basic-read
group, and MUST NOT contain any duplicates. CIM Clients MUST ignore any
duplicate entries in the functional-group list. If a functional group
is
included in the list, then the CIM Client MUST assume that all other
groups
on which it depends (according to the rules defined in Functional
Profiles)
are also supported. A CIM Server SHOULD NOT explicitly include a
functional
group in the list whose presence may be inferred implicitly by a
dependency.
Support for a functional group does not imply that any method from that
group will always succeed. Rather, the absence (whether explicit or
implied)
of the functional group from this list is an indication to the CIM
Client
that methods in that group will never succeed.
MultipleOperationsSupported property
which defines whether the target CIM Server supports multiple operation
requests as defined in section 2.3.2. TRUE in this property indicates
that
the Server can accept and process Multiple Operation Requests. FALSE
indicates
that the CIM Server can accept only Single Operation Requests.
AuthenticationMechanismsSupported
property
which defines the authentication mechanisms supported by the target CIM
Server as defined in section 4.4 of this specification.
Compliant CIM Servers may report additional capabilities for the
CommunicationMechanism
Functional Profiles, QueryLanguageSupported, and
AuthenticationMechanismSupported
by defining the "other" enumeration in the property and returning
additional
information in the associated "additional capabilities" property.
4.5.2 Determining CIM Server Capabilities
through the
HTTP Options
The OPTIONS method MAY be used by a client to determine the CIM
capabilities (if any) of the target server. A CIM
Server MAY support the OPTIONS method (for example, CIM Servers
supporting
only HTTP/1.0 would not support OPTIONS).
In order to support the ability for a Server to declare its CIM
capabilities
in a manner independent of HTTP, it is the intention of the DMTF to
publish
a CIM Schema (in a separate document) describing such capabilities. In
particular this mechanism would allow Servers that do not support the
OPTIONS
method to declare their capabilities to a Client.
If a CIM Server supports the OPTIONS method, it SHOULD:
- Return the CIM Extension Header CIMProtocolVersion
in the response. This provides a way for a client to discover the
version of the CIM HTTP mapping supported by the CIM Server.
- Return the CIM Extension Header CIMSupportedFunctionalGroups
in the response. This provides a way for a client to discover the
CIM Operations supported by the CIM Server.
- Return the CIM Extension Header CIMSupportsMultipleOperations
in the response. This provides a way for the client to discover
whether
the CIM Server can support Multiple
Operation Requests.
In addition, if the CIM Server supports one or more query languages, it
SHOULD:
- Return the CIM Extension Header CIMSupportedQueryLanguages
in the response. This allows the client to discover the query
languages
supported by the CIM Server.
In addition, if the CIM Server runs in a fixed validation mode, it
SHOULD:
- Return the CIM Extension Header CIMValidation
in the response. This allows the client to determine whether the
CIM Server is strictly validating or loosely validating.
If the CIMProtocolVersion,
CIMSupportedFunctionalGroups,
CIMSupportsMultipleOperations,
CIMValidation
or CIMSupportedQueryLanguages
extension headers are included in the response, the CIM Server MUST
declare
them as Optional extension headers using the "Opt" header defined in
[9].
The full format of the "Opt" header declaration for this
specification
is:
| Opt
= "Opt" ":" "http://www.dmtf.org/cim/mapping/http/v1.0" |
|
";" "ns" "=" header-prefix |
| header-prefix = 2*DIGIT |
This header-prefix SHOULD be generated at random on a per-HTTP
message
basis, and SHOULD NOT necessarily be a specific number.
For example the following is a fragment of a legitimate OPTIONS
response
from a CIM Server:
| HTTP/1.1 200 OK |
| Opt: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=77 |
| 77-CIMProtocolVersion: 1.0 |
| 77-CIMSupportedFunctionalGroups: basic-read |
| 77-CIMBatch |
| 77-CIMSupportedQueryLanguages: wql |
| ... |
Back to contents
4.5.2.1. CIMSupportedFunctionalGroups
The CIMSupportedFunctionalGroups extension header SHOULD be returned by
a CIM Server in any OPTIONS
response.
It MUST NOT be returned in any other scenario.
This header is defined as follows:
The functional group definitions correspond directly to those listed
in Functional Profiles. All
CIM Servers MUST support the basic-read functional group. All CIM
Clients MAY assume that any CIM Server supports the basic-read
functional
group.
The list of functional groups returned by a CIM Server MUST contain
the basic-read group, and MUST NOT contain any duplicates. CIM
Clients
MUST ignore any duplicate entries in the functional-group list.
If a functional group is included in the list, then the CIM Client
MUST
assume that all other groups on which it depends (according to the
rules
defined in Functional Profiles)
are
also supported. A CIM Server SHOULD NOT explicitly include a
functional
group in the list whose presence may be inferred implicitly by a
dependency.
For example the following HTTP response message indicates that the
CIM
Server supports instance-manipulation, association-traversal,
basic-write
and basic-read.
| HTTP/1.1 200 OK |
| Opt: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=77 |
| 77-CIMProtocolVersion: 1.0 |
| 77-CIMSupportedFunctionalGroups: association-traversal,
instance-manipulation |
| ... |
Support for a functional group does not imply that any
method
from that group will always succeed. Rather, the absence (whether
explicit or implied) of the functional group from this header is an
indication
to the CIM Client that methods in that group will never
succeed.
Back to contents
4.5.2.2.
CIMSupportsMultipleOperations
The CIMSupportsMultipleOperations extension header MUST be returned in
an OPTIONS response by any CIM Server that
supports Multiple Operation
Requests.
It MUST NOT be returned in any other circumstances.
This header is defined as follows:
| CIMSupportsMultipleOperations =
"CIMSupportsMultipleOperations" |
The presence of this header indicates that the Server can accept and
process Multiple Operation Requests. The absence of this header
indicates
that the Server can only accept and process Simple
Operation Requests.
Back to contents
4.5.2.3. CIMSupportedQueryLanguages
The CIMSupportedQueryLanguages extension header SHOULD be returned by a
CIM
Server that supports at least one query language in any OPTIONS
response.
It MUST NOT be returned in any other scenario.
This header is defined as follows (token
has the meaning conferred by [7, section 2.2]:
| CIMSupportedQueryLanguages =
"CIMSupportedQueryLanguages" ":"
1#query-language
query-language = token
|
The query-language value MUST be treated as case-insensitive. It is
anticipated that query languages will be submitted for approval to the
DMTF, and each submission will define a value for this token to enable
it to be specified in this header.
Back to contents
4.5.2.4. CIMValidation
The CIMValidation extension header MAY be returned by a CIM
Server to provide information concerning the level of validation of
CIM
Operation Request messages.
This header is defined as follows:
CIMValidation = "CIMValidation" ":"
validation-level
validation-level = "validating" |
"loosely-validating" |
A validation-level of validating
indicates
that the CIM Server will always apply strict validation of each CIM
Operation
Request. A validation-level of loosely-validating
indicates that the CIM Server will apply loose
validation of each CIM Operation Request.
In the absence of this header, a CIM Client SHOULD assume that the
CIM
Server operates in strict validation mode.
Back to contents
4.6. Other HTTP Methods
This specification does not in any way define or constrain the manner
in
which a CIM Client, CIM Server, or CIM Listener uses any HTTP
Method
other than those explicitly referred to herein.
Back to contents
4.7. Discovery and
Addressing
The target URI of the CIM Operation
Request
is defined to be the location of the CIM Server.
This specification does not constrain the format of this URI other than
it be a valid URI [13] for the purposes of describing an
HTTP-addressable
resource.
An HTTP Server which supports the CIM Mapping defined herein, and
which
supports the OPTIONS method, SHOULD include the following CIM extension
header in an OPTIONS response:
This header is defined as follows:
| CIMOM = "CIMOM" ":"
(absoluteURI
| relativeURI) |
The terms absoluteURI and relativeURI are taken from [7]; they
indicate
the location of the CIM Server for this HTTP Server.
If the CIMOM extension header is included in the response, the CIM
Server
MUST declare it an Optional extension header in an analogous fashion to
that described in the section on Determining
CIM Server Capabilities.
A CIM Client that wishes to communicate
with a CIM Server on an HTTP Server SHOULD try an OPTIONS request to
that
HTTP Server. If the OPTIONS request fails, or the response does
not
include the CIM-CIMOM extension header, then the CIM Client MAY assume
that the value of CIM-CIMOM is the relative URI cimom.
The DMTF recommends the use of the following well-known IP ports for
use in compliant CIM Servers. This is a recommendation and not a
requirement for compliance with this specification. These port
addresses
have been registered with IANA by the DMTF, so are for the exclusive
use
by the DMTF.
| CIM-XML (HTTP) |
5988/tcp |
| CIM-XML (HTTP) |
5988/udp |
| CIM-XML (HTTPS) |
5989/tcp |
| CIM-XML (HTTPS) |
5989/udp |
Other discovery mechanisms are outside the scope of this version of
the specification.
Example 1
This example shows an HTTP Server located at http://www.dmtf.org/
issuing an OPTIONS response to an HTTP client to indicate that its CIM
Server is located at http://www.dmtf.org/access/cimom.
| HTTP/1.1 200 OK |
| Opt: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=48 |
| 48-CIMOM: /access/cimom |
| ... |
Example 2
If an HTTP Server located at http://www.dmtf.org/
responds with a "501 Not Implemented" to an OPTIONS request from a CIM
Client, the CIM client may then try to contact the CIM Server at
http://www.dmtf.org/cimom.
Back to contents
4.8.
Internationalization Considerations
This section defines the capabilities of the CIM HTTP Mapping with
respect to IETF policy guidelines on character sets and languages [19].
In this specification, human-readable fields can be found within a
response or request entity body. In all cases, any human-readable
content is encoded using XML (which has explicit provisions for
character set
tagging and encoding) and requires that XML processors read XML
elements
encoded, at minimum, using the UTF-8 [15] encoding of the ISO 10646
multilingual
plane.
Properties that are not of type string or string array MUST
NOT be localized.
Since keys are only writeable on instantiation, key values
MUST NOT be localized. See the
CIM Specification, v 2.2 for further details.
XML examples in this specification demonstrate use of the
charset parameter of the Content-Type header, as defined in [10], as
well as the XML attribute on the <?xml> processing instruction,
which together provide charset identification information for MIME and
XML processors. This specification
mandates that conforming applications MUST support at least the "UTF-8"
charset encoding [19] in the Content-Type header, and the "UTF-8" value
for the XML encoding attribute.
XML also provides a language tagging capability for specifying
the language of the contents of a particular XML element, based on use
of IANA
registered
language tags [20] in combination with
ISO 639-1
in the xml:lang attribute of an XML element to identify the language of
its content and attributes. Section 3.10 of RFC 2616 defines how
the two character language code, ISO 639-1 is used
as the primary-tag. The language-tag MUST be registered by IANA.
The XML CIM DTD [2,11] declares this attribute on any of the XML
elements, and therefore conforming applications SHOULD use this
attribute when specifying the language a particular element is encoded
in, string and string array attributes and qualifiers. See the
usage rules
on this element defines by the World Wide Web Consortium, XML 1.0, second
edition. The attribute MAY be scoped by the instance or a
class and SHOULD NOT by a property because instances or classes SHOULD
be localized in a one language.
This specification defines a number of names of HTTP headers
and their values. These are constructed using standard encoding
practices so as to always have an HTTP-safe ASCII representation.
Since these headers are not in general visible to users they do not
need to support encoding in multiple character sets.
The XML DTD for CIM [2,11] introduces a number of XML element
names. Similarly these are not visible to an end user and do not
need to
support multiple character set encodings.
The CIM model [1] defines the subset of the Unicode character
set that can be used to name CIM elements (Classes, Instances, Methods,
Properties, Qualifiers and Method Parameters). In general these
appear as the
value of XML attributes or as element content, and in general would not
be displayed to end users.
Negotiation and notification of language settings is effected
in this mapping using the standard Accept-Language
and Content-Language
headers defined in [7].
5. References
- "Common Information Model (CIM)
Specification", Version
2.3, DMTF, (http://www.dmtf.org/standards/cim_schema_v22.php)
- "Specification for the Representation of CIM in XML", Version
2.2,
DMTF,
(http://www.dmtf.org/standards/wbem/)
- "Extensible Markup Language (XML)", Version 1.0, W3C
Recommendation (http://www.w3.org/TR/REC-xml)
- "Namespaces in XML", 14th
January
1999, W3C Recommendation (http://www.w3.org/TR/REC-xml-names)
- "XML as a Representation for Management
Information
- A White Paper", Version 1.0, DMTF, September 15th 1998 (http://www.dmtf.org/standards/xmlw.php)
- "Hypertext Transfer Protocol --
HTTP/1.0",
IETF RFC
1945, May 1996 (http://www.ietf.org/rfc/rfc1945.txt)
- "Hypertext Transfer Protocol --
HTTP/1.1",
IETF RFC
2068, January 1997 (http://www.ietf.org/rfc/rfc2068.txt)
- "Key words for use in RFCs to Indicate
Requirement
Levels", IETF RFC 2119, March 1997 (http://www.ietf.org/rfc/rfc2119.txt)
- "HTTP Extension Framework", IETF Internet
Draft, June
1999 (http://www.ietf.org/rfc/rfc2774.txt)
- "Hypertext Transfer Protocol --
HTTP/1.1",
IETF June
1999 (http://www.ietf.org/rfc/rfc2616.txt
)
- "CIM XML DTD", Version 2.0, DMTF, 20th July 1999 (http://www.dmtf.org/download/spec/xmls/CIM_DTD_V20.txt)
- "An Extension to HTTP : Digest Access Authentication", IETF RFC
2069,
January
1997 (http://www.ietf.org/rfc/rfc1945.txt)
- "Uniform Resource Identifiers (URI): Generic Syntax", IETF RFC
2396, 12th
August 1998 (http://www.ietf.org/rfc/rfc2396.txt)
- "HTTP Authentication: Basic and Digest Access Authentication",
IETF
Internet
Draft, June 1999 (http://www.ietf.org/rfc/rfc2617.txt)
- "UTF-8, a transformation format of Unicode and ISO 10646", RFC
2279,
January
1998 (http://www.ietf.org/rfc/rfc2279.txt)
- "Uniform Resource Identifiers (URI): Generic Syntax", IETF RFC
2396, 12th
August 1998 (http://www.ietf.org/rfc/rfc2396.txt)
- "XSL Transformations (XSLT)", Version 1.0, W3C Working Draft, 21st
April 1999 (http://www.w3.org/TR/WD-xsltl)
- "XML Media Types", IETF Informational RFC 2376, July 1998 (http://www.ietf.org/rfc/rfc2376.txt)
- "IETF Policy on Character Sets and Languages", IETF Best Current
Practice
RFC 2277, January 1998 (http://www.ietf.org/rfc/rfc2277.txt)
- "Tags for the Identification of Languages", IETF Standards Track
RFC
1766,
March 1995 (http://www.ietf.org/rfc/rfc1766.txt)
- "XML Schema Part 1: Structures", W3C Working Draft 6th
May
1999
(http://www.w3.org/TR/xmlschema-1/)
Back to contents
Appendix A: Change History
| 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
CIMFunctionalGroups OPTIONS header renamed to
CIMSupportedFunctionalGroups
501 returned by server if it does not support multiple
requests and
receives such a request
Added some operation parameters and allowed them to take
default values
|
| Version 1.0 |
June 2nd, 1999 |
Clarified meaning of default intrinsic parameter
value
Resolved ambiguity over server response to protocol version that is
not supported
Clarified use of property list in Associators and References intrinsic
methods |
|
July 6th, 1999 |
Updated examples to reflect DTD changes
QueryExecution based on BasicRead, not BasicWrite |
|
July 20th, 1999 |
Remove IncludeClassOrigin and IncludeQualifiers
parameters
from ExecQuery.
Parameters to Associators, AssociaftorNames, References and
ReferenceNames
which express class names are modeled as <className> rather than
string.
NewValue parameter to SetProperty is now OPTIONAL
Clarified semantics of optional parameters, and the distinction between
a default parameter value and a NULL parameter value.
Clarified Create and Modify operational semantics.
Clarified validation requirements and introduced CIMValidation header
for OPTIONS response.
Introduced CIMError response header to disambiguate fundamental
CIM-specific
errors that map to the same HTTP status code. |
| Version 1.1a |
November 23, 2001 |
CR604: Add information regarding well known ports (Section
4.7)
CR605: CIM-XML Indication Delivery Support
CR611: Determining CIM Server Capabilities through CIM Classes (Section
4.5)
CR627: Add CIM_ERR_NO_SUCH_PROPERTY to list returned from
ModifyInstance
CR628: Deprecate __Namespace and add CIM_Namespace behavior (Section
2.3.3)
CR646: Clarify handling of unsupported and optional parameters (Section
2.3.2)
CR649: Add optional propertyList support to ModifyInstance
(2.3.2.8)
CR653: Add Indication Delivery Example (Appendix 11)
Remove participant list since many new companies involved. |
| Version 1.1b |
January 16, 2002 |
Incorporate Errata 01
CR666: Fix Error in 3.3.10. CIMBatch
CR667: Remove Determining CIM Listener Capabilities
CR669: Move Change Histroy Table to Appendix
CR708: Subscription Example
CR711: Modify definition of EXPMETHODCALL to be more extensible. |
| Version 1.1c |
April 24, 2002 |
CR737: CIM Operations Over HTTP 1.0 – Remove reference to
OPTIONAL
qualifier
CR741: Add additional wording to DeleteInstance
CR742: Add additional description for what “associator” operations
return
CR743: Update PropertyList descriptions
CR744: 4.5.1. Determining CIM Server Capabilities
CR808: Appendix C: EnumerateInstance Example
CR809: Clarify semantics of the DeepInheritance and LocalOnly
flags on EnumerateInstances.
CR810: Update wording related to DeepInheritance property for Enum
CR815: Update wording for LocalOnly |
| Version 1.1d |
May 02, 2002 |
Add DMTF Copyright |
| Version 1.1 |
January 06, 2003 |
Final 1.1 Version
CR924: Correct missing object in the object mapping table (ObjectPath)
CR925: Update DTD & HTTP Operations version information to
match latest spec
Update copyright, date, status |
| Version 1.2a |
January 28, 2004 |
Changed status to Draft
Changed version to 1.2a and date to January 28, 2004
Added 2004 to copyright notice
CR870: Clarified wording describing Client handling of optional
parameters.
CR872: Add support for Asynchronous Operations.
CR878: Added new HTTP CIM extension headers CIMRoleAuthenticate and
CIMRoleAuthorization.
CR879: Make use of HTTP Extensions optional.
CR880: Clarified the scope of objects returns by EnumerateInstances
and EnumerateInstanceNames.
CR911: Clarified the definition of InstanceNames returns by
EnumerateInstanceNames.
|
| Version 1.2b |
February 7, 2004 |
Changed version to 1.2b and date to February 7, 2004
CR912: Add support for HTTP Chunking
CR1254: Clarify escape character handling of “\” character in
CR1251: Allow return of multiple instances of CIM_Error to be returned
on error.
CR1277: Updates to CR912 (“Add Chunking Support”)
CR1309: Clarify handling of CIM_Error.CIMStatusCode |
| Version 1.2c |
March 2, 2004 |
Changed version to 1.2c and date to March 1, 2004
CR1261: Added A.14. Multiple Operation Example
CR1262: Fixed “Content-CIMType” Typo in HTTP Example
CR1271: Added missing Status Code for CIM_ERR_NAMESPACE_NOT_EMPTY
CR1272: Corrected wording of status code descriptions
CR1274: Added new HTTP Extension Header, WBEMServerResponseTime
|
| Version 1.2d |
April 6, 2004 |
Changed version to 1.2d and date to April 6, 2004
CR1310: Allow deletion of non-empty namespace.
CR1373: Deprecate LocalOnly flag on Instance Operations
|
| Version 1.2e |
June 5, 2004 |
Changed version to 1.2e and date to June 5, 2004
CR1381: Clarify and enhance internationalization support.
CR1409: Clarify handling of "*" in Accept-Language header.
CR1410: Corrections to CR1381 (Internationalization Support).
CR1413: Deprecate TOINSTANCE Qualifier.
CR1414: Correct wording in createInstance.
CR1415: Correction to Content-Language wording in CR1381.
CR1416: Correct inconsistencies in examples in Appendix.
CR1417/CR1418: Deprecate and clarify IncludeQualifier parameter usage. |
| Version 1.2f |
June 9, 2004 |
Changed version to 1.2f and date to June 9, 2004
Additional CR1409 changes based on TC review.
Additional CR1415 changes based on TC review.
Approved for Company Review |
| Version 1.2g |
November 24, 2004 |
Changed status to Preliminary.
Changed version to 1.2g and date to November 25, 2004
CR1534: Add CQL Support
CR1537: Company Review comments/corrections to CIM Ops 1.2
Specification.
CR1538: Clarify IncludeQualifier usage for GetInstance &
EnumerateInstances |
Version 1.2h
|
January 09, 2007
|
Changed status to Final, version
1.2, updated date and copyright year
Remove application of CR872
Remove application of CR912
Remove application of CR1277
Remove application of CR1534
Add sentence before examples to state examples are for illustration only
WIPCR0239
|
Back to contents
Appendix B - Examples of Message
Exchanges
This section illustrates the protocol defined in this document by
providing
examples of valid HTTP request/response exchanges. The examples are for
illustration purposes only are not considered part of the specification.
For the purposes of clarity additional white space has been included
in the examples, but such white space is not an intrinsic part of such
XML documents.
A.1. Retrieval
of a
Single Class Definition
The following HTTP request illustrates how a client would request the
class
CIM_VideoBIOSElement.
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: GetClass |
| 73-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="GetClass"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE
NAME="ClassName"><CLASSNAME
NAME="CIM_VideoBIOSElement"/></IPARAMVALUE> |
| <IPARAMVALUE
NAME="LocalOnly"><VALUE>FALSE</VALUE></IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the requested operation. For clarity of exposition the
complete
definition of the returned <CLASS> element has not been shown.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="GetClass"> |
| <IRETURNVALUE> |
| <CLASS
NAME="CIM_VideoBIOSElement"
SUPERCLASS="CIM_SoftwareElement"> |
| ... |
| </CLASS> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.2.
Retrieval of
a Single Instance Definition
The following HTTP request illustrates how a client would request the
instance
MyClass.MyKey="S3".
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: GetInstance |
| 73-CIMObject: root%2FmyNamespace |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="1.1"> |
| <MESSAGE ID="87855" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="GetInstance"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="myNamespace"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="InstanceName"> |
| <INSTANCENAME
CLASSNAME="MyClass"> |
| <KEYBINDING
NAME="MyKey"><KEYVALUE>S3</KEYVALUE></KEYBINDING> |
| </INSTANCENAME> |
| </IPARAMVALUE> |
| <IPARAMVALUE
NAME="LocalOnly"><VALUE>FALSE</VALUE></IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating an
error due to the specified instance not being found.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87885" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="GetInstance"> |
| <ERROR CODE="6" DESCRIPTION="Instance
of MyClass
not found"/> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.3. Deletion of
a Single
Class Definition
The following HTTP request illustrates how a client would delete the
class
CIM_VideoBIOSElement.
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: DeleteClass |
| 73-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="DeleteClass"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE
NAME="ClassName"><CLASSNAME
NAME="CIM_VideoBIOSElement"/></IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
failure
of the above operation due to the inability to delete instances of the
Class.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="DeleteClass"> |
| <ERROR CODE="9" DESCRIPTION="Class has
non-deletable
instances"/> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.4. Deletion
of a
Single Instance Definition
The following HTTP request illustrates how a client would delete the
instance
MyClass.MyKey="S3".
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: DeleteInstance |
| 73-CIMObject: root%2FmyNamespace |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="DeleteInstance"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="myNamespace"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="InstanceName"> |
| <INSTANCENAME
CLASSNAME="MyClass"> |
| <KEYBINDING
NAME="MyKey"> |
|
<KEYVALUE>S3</KEYVALUE> |
| </KEYBINDING> |
| </INSTANCENAME> |
| </IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/operation ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="DeleteInstance"/> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.5. Creation of
a Single
Class Definition
The following HTTP request illustrates how a client would create the
class
MySchema_VideoBIOSElement as a subclass of CIM_VideoBIOSElement.
For clarity of exposition most of the submitted <CLASS> element
is omitted
from the example.
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: CreateClass |
| 73-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="CreateClass"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="NewClass"> |
| <CLASS
NAME="MySchema_VideoBIOSElement"
SUPERCLASS="CIM_VideoBIOSElement"> |
| ... |
| </CLASS> |
| </IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="CreateClass"/> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.6. Creation
of a
Single Instance Definition
The following HTTP request illustrates how a client would create an
instance
of the class MySchema_VideoBIOSElement. For clarity of exposition most
of the submitted <INSTANCE> element is omitted from the example.
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: CreateInstance |
| 73-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="CreateInstance"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="NewInstance"> |
| <INSTANCE
CLASSNAME="CIM_VideoBIOSElement"> |
| ... |
| </INSTANCE> |
| </IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="CreateInstance"> |
| <IRETURNVALUE> |
| <INSTANCENAME
CLASSNAME="MySchema_VideoBIOSElement"> |
| <KEYBINDING
NAME="Name"> |
|
<KEYVALUE>S4</KEYVALUE> |
| </KEYBINDING> |
| </INSTANCENAME> |
| </IRETURNVALUE> |
| </IRETURNVALUE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.7. Enumeration of Class Names
The following HTTP request illustrates how a client would enumerate the
names of all subclasses of the class CIM_SoftwareElement.
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: EnumerateClassNames |
| 73-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="EnumerateClassNames"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE
NAME="ClassName"><CLASSNAME
NAME="CIM_SoftwareElement"/></IPARAMVALUE> |
| <IPARAMVALUE
NAME="DeepInheritance"><VALUE>FALSE</VALUE></IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation, and returning the names of the requested
subclasses.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE
NAME="EnumerateClassNames"> |
| <IRETURNVALUE> |
| <CLASSNAME
NAME="CIM_BIOSElement"/> |
| <CLASSNAME
NAME="CIM_VideoBOISElement"/> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.8. Enumeration of Instances
The following HTTP request illustrates how a client would enumerate all
instances of the class CIM_LogicalDisk. For clarity of exposition most
of the returned Instances are omitted from the example.
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/operation ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: EnumerateInstances |
| 73-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="EnumerateInstances"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE
NAME="ClassName"><CLASSNAME
NAME="CIM_LogicalDisk"/></IPARAMVALUE> |
| <IPARAMVALUE
NAME="LocalOnly"><VALUE>TRUE</VALUE></IPARAMVALUE> |
| <IPARAMVALUE
NAME="DeepInheritance"><VALUE>TRUE</VALUE></IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation, returning the requested instances.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="EnumerateInstances"> |
| <IRETURNVALUE> |
| <VALUE.NAMEDINSTANCE> |
| <INSTANCENAME
CLASSNAME="Erewhon_LogicalDisk"> |
| ... |
| </INSTANCENAME> |
| <INSTANCE
CLASSNAME="Erewhon_LogicalDisk"> |
| ... |
| </INSTANCE> |
| </VALUE.NAMEDINSTANCE> |
| ... |
| <VALUE.NAMEDINSTANCE> |
| <INSTANCENAME
CLASSNAME="Foobar_LogicalDisk"> |
| ... |
| </INSTANCENAME> |
| <INSTANCE
CLASSNAME="Foobar_LogicalDisk"> |
| ... |
| </INSTANCE> |
| </VALUE.NAMEINSTANCE> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.9. Retrieval of
a Single
Property
The following HTTP request illustrates how a client would retrieve the
FreeSpace property from the Instance MyDisk.DeviceID="C:".
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/operation ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: GetProperty |
| 73-CIMObject: root%2FmyNamespace |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="GetProperty"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="myNamespace"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="InstanceName"> |
| <INSTANCENAME
CLASSNAME="MyDisk"> |
| <KEYBINDING
NAME="DeviceID"><KEYVALUE>C:</KEYVALUE></KEYBINDING> |
| </INSTANCENAME> |
| </IPARAMVALUE> |
| <IPARAMVALUE
NAME="PropertyName"><VALUE>FreeSpace</VALUE></IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation, returning the requested value.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="GetProperty"> |
| <IRETURNVALUE> |
| <VALUE>6752332</VALUE> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.10. Execution
of an
Extrinsic Method
The following HTTP request illustrates how a client would execute the
SetPowerState
method on the Instance MyDisk.DeviceID="C:".
| M-POST /cimom HTTP/1.1 |
| HOST: http://www.myhost.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodCall |
| 73-CIMMethod: SetPowerState |
| 73-CIMObject: root%2FmyNamespace%3AMyDisk.Name%3D%22C%3A%22 |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <METHODCALL NAME="SetPowerState"> |
| <LOCALINSTANCEPATH> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE
NAME="myNamespace"/> |
| </LOCALNAMESPACEPATH> |
| <INSTANCENAME
CLASSNAME="MyDisk"> |
| <KEYBINDING
NAME="Name"><KEYVALUE>C:</KEYVALUE></KEYBINDING> |
| </INSTANCENAME> |
| </LOCALINSTANCEPATH> |
| <PARAMVALUE
NAME="PowerState"><VALUE>1</VALUE></PARAMVALUE> |
| <PARAMVALUE
NAME="Time"><VALUE>00000001132312.000000:000</VALUE></PARAMVALUE> |
| </METHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: xxxx |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73 |
| 73-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="87872" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <METHODRESPONSE NAME="SetPowerState"> |
| <RETURNVALUE> |
| <VALUE>0</VALUE> |
| </RETURNVALUE> |
| </METHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.11. Indication Delivery Example
The following HTTP request illustrates the format used to send an
indication of type CIM_AlertIndication to a CIM Listener.
| M-POST /cimlistener/browser HTTP/1.1 |
| HOST: http://www.acme.com/ |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXX |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=40 |
| 40-CIMExport: MethodRequest |
| 40-CIMExportMethod: ExportIndication |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="1007" PROTOCOLVERSION="1.0"> |
| <SIMPLEEXPREQ> |
| <EXPMETHODCALL
NAME="ExportIndication"> |
| <EXPPARAMVALUE
NAME="NewIndication"> |
| <INSTANCE
CLASSNAME="CIM_AlertIndication"
> |
| <PROPERTY
NAME="Description"
TYPE="string"> |
|
<VALUE>Sample
CIM_AlertIndication indication</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="AlertType"
TYPE="uint16"> |
|
<VALUE>1</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="PerceivedSeverity"
TYPE="uint16"> |
|
<VALUE>3</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="ProbableCause"
TYPE="uint16"> |
|
<VALUE>2</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="IndicationTime"
TYPE="datetime"> |
|
<VALUE>20010515104354.000000:000</VALUE> |
| </PROPERTY> |
| </INSTANCE> |
| </EXPPARAMVALUE> |
| </EXPMETHODCALL> |
| </SIMPLEEXPREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating a
successful receipt, by the CIM Listener, of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: 267 |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0; ns=40 |
| 40-CIMExport: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="1007" PROTOCOLVERSION="1.0"> |
| <SIMPLEEXPRSP> |
| <EXPMETHODRESPONSE
NAME="ExportIndication"> |
|
<IRETURNVALUE> |
|
</IRETURNVALUE> |
| </EXPMETHODRESPONSE> |
| </SIMPLEEXPRSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.12. Subscription Example
A CIM client application activates a subscription by creating an
instance of the CIM_IndicationSubscription class. A
CIM_IndicationSubscription
instance defines an association between a CIM_IndicationFilter (a
Filter)
instance and a CIM_IndicationHandler (a Handler) instance. The
CIM_IndicationFilter
instance defines the filter criteria and data project list that
describe
the desired Indication stream. The CIM_IndicationHandler instance
defines
the desired Indication encoding, destination location and protocol for
delivery of the Indication stream.
The following HTTP request illustrates how a client would create an
instance of the class CIM_IndicationFilter. Note that the exact
syntax
of the WQL Query Language is still under review and subject to change.
| M-POST /cimom HTTP/1.1 |
| Host: bryce |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXXX |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0;ns=20 |
| 20-CIMProtocolVersion: 1.0 |
| 20-CIMOperation: MethodCall |
| 20-CIMMethod: CreateInstance |
| 20-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8"?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="53000" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="CreateInstance"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="NewInstance"> |
| <INSTANCE
CLASSNAME="CIM_IndicationFilter"> |
| <PROPERTY
NAME="SystemCreationClassName"
TYPE="string"> |
|
<VALUE>CIM_UnitaryComputerSystem</VALUE> |
| </PROPERTY> |
| <PROPERTY NAME="SystemName"
TYPE="string"> |
|
<VALUE>server001.acme.com</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="CreationClassName"
TYPE="string"> |
|
<VALUE>CIM_IndicationFilter</VALUE> |
| </PROPERTY> |
| <PROPERTY NAME="Name"
TYPE="string"> |
|
<VALUE>ACMESubscription12345</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="SourceNamespace"
TYPE="string"> |
|
<VALUE>root/cimv2</VALUE> |
| </PROPERTY> |
| <PROPERTY NAME="Query"
TYPE="string"> |
| <VALUE> |
| SELECT Description,
AlertType,
PerceivedSeverity, ProbableCause, IndicationTime |
| FROM
CIM_AlertIndication |
| WHERE
PerceivedSeverity
= 3 |
| </VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="QueryLanguage" TYPE="string"> |
|
<VALUE>WQL</VALUE> |
| </PROPERTY> |
| </INSTANCE> |
| </IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXX |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0; ns=28 |
| 28-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="53000" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE
NAME="CreateInstance"> |
| <IRETURNVALUE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationFilter"> |
| <KEYBINDING
NAME="SystemCreationClassName"> |
| <KEYVALUE
VALUETYPE="string"> |
|
CIM_UnitaryComputerSystem |
| </KEYVALUE> |
| </KEYBINDING> |
| <KEYBINDING
NAME="SystemName"> |
| <KEYVALUE
VALUETYPE="string"> |
|
server001.acme.com |
| </KEYVALUE> |
| </KEYBINDING> |
| <KEYBINDING
NAME="CreationClassName"> |
| <KEYVALUE
VALUETYPE="string"> |
|
CIM_IndicationFilter |
| </KEYVALUE> |
| </KEYBINDING> |
| <KEYBINDING
NAME="Name"> |
| <KEYVALUE
VALUETYPE="string"> |
|
ACMESubscription12345 |
| </KEYVALUE> |
| </KEYBINDING> |
| </INSTANCENAME> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
The following HTTP request illustrates how a client would create an
instance of the class CIM_IndicationHandlerCIMXML.
| M-POST /cimom HTTP/1.1 |
| Host: bryce |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXX |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0;ns=20 |
| 20-CIMProtocolVersion: 1.0 |
| 20-CIMOperation: MethodCall |
| 20-CIMMethod: CreateInstance |
| 20-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8"?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="54000" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="CreateInstance"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="NewInstance"> |
| <INSTANCE
CLASSNAME="CIM_IndicationHandlerCIMXML"> |
| <PROPERTY
NAME="SystemCreationClassName"
TYPE="string"> |
|
<VALUE>CIM_UnitaryComputerSystem</VALUE> |
| </PROPERTY> |
| <PROPERTY NAME="SystemName"
TYPE="string"> |
|
<VALUE>server001.acme.com</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="CreationClassName"
TYPE="string"> |
|
<VALUE>CIM_IndicationHandlerCIMXML</VALUE> |
| </PROPERTY> |
| <PROPERTY NAME="Name"
TYPE="string"> |
|
<VALUE>ACMESubscription12345</VALUE> |
| </PROPERTY> |
| <PROPERTY NAME="Owner"
TYPE="string"> |
|
<VALUE>ACMEAlertMonitoringConsole</VALUE> |
| </PROPERTY> |
| <PROPERTY
NAME="Destination" TYPE="string"> |
|
<VALUE>HTTP://www.acme.com/cimlistener/browser</VALUE> |
| </PROPERTY> |
| </INSTANCE> |
| </IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXX |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0; ns=27 |
| 27-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="54000" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE
NAME="CreateInstance"> |
| <IRETURNVALUE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationHandlerCIMXML"> |
| <KEYBINDING
NAME="SystemCreationClassName"> |
| <KEYVALUE
VALUETYPE="string"> |
|
CIM_UnitaryComputerSystem |
| </KEYVALUE> |
| </KEYBINDING> |
| <KEYBINDING
NAME="SystemName"> |
| <KEYVALUE
VALUETYPE="string"> |
|
server001.acme.com |
| </KEYVALUE> |
| </KEYBINDING> |
| <KEYBINDING
NAME="CreationClassName"> |
| <KEYVALUE
VALUETYPE="string"> |
|
CIM_IndicationHandlerCIMXML |
| </KEYVALUE> |
| </KEYBINDING> |
| <KEYBINDING NAME="Name"> |
| <KEYVALUE
VALUETYPE="string"> |
|
ACMESubscription12345 |
| </KEYVALUE> |
| </KEYBINDING> |
| </INSTANCENAME> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
The following HTTP request illustrates how a client would create an
instance of the class CIM_IndicationSubscription.
| M-POST /cimom HTTP/1.1 |
| Host: bryce |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXXX |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0;ns=55 |
| 55-CIMProtocolVersion: 1.0 |
| 55-CIMOperation: MethodCall |
| 55-CIMMethod: CreateInstance |
| 55-CIMObject: root/cimv2 |
|
| <?xml version="1.0" encoding="utf-8"?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="55000" PROTOCOLVERSION="1.0"> |
| <SIMPLEREQ> |
| <IMETHODCALL NAME="CreateInstance"> |
| <LOCALNAMESPACEPATH> |
| <NAMESPACE NAME="root"/> |
| <NAMESPACE NAME="cimv2"/> |
| </LOCALNAMESPACEPATH> |
| <IPARAMVALUE NAME="NewInstance"> |
| <INSTANCE
CLASSNAME="CIM_IndicationSubscription"> |
| <PROPERTY.REFERENCE
NAME="Filter"
REFERENCECLASS="CIM_IndicationFilter"> |
| <VALUE.REFERENCE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationFilter"> |
|
<KEYBINDING NAME="SystemCreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_UnitaryComputerSystem |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="SystemName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
server001.acme.com |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="CreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_IndicationFilter |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="Name"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
ACMESubscription12345 |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
</INSTANCENAME> |
| </VALUE.REFERENCE> |
|
</PROPERTY.REFERENCE> |
| <PROPERTY.REFERENCE
NAME="Handler"
REFERENCECLASS="CIM_IndicationHandler"> |
|
<VALUE.REFERENCE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationHandlerCIMXML"> |
|
<KEYBINDING NAME="SystemCreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_UnitaryComputerSystem |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="SystemName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
server001.acme.com |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="CreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_IndicationHandlerCIMXML |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="Name"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
ACMESubscription12345 |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
</INSTANCENAME> |
| </VALUE.REFERENCE> |
| </PROPERTY.REFERENCE> |
| </INSTANCE> |
| </IPARAMVALUE> |
| </IMETHODCALL> |
| </SIMPLEREQ> |
| </MESSAGE> |
| </CIM> |
The following is an HTTP response to the above request indicating
success
of the above operation.
| HTTP/1.1 200 OK |
| Content-Type: application/xml; charset="utf-8" |
| Content-Length: XXXX |
| Ext: |
| Cache-Control: no-cache |
| Man: http://www.dmtf.org/cim/mapping/http/v1.0; ns=75 |
| 75-CIMOperation: MethodResponse |
|
| <?xml version="1.0" encoding="utf-8" ?> |
| <CIM CIMVERSION="2.0" DTDVERSION="2.0"> |
| <MESSAGE ID="55000" PROTOCOLVERSION="1.0"> |
| <SIMPLERSP> |
| <IMETHODRESPONSE NAME="CreateInstance"> |
| <IRETURNVALUE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationSubscription"> |
| <KEYBINDING
NAME="Filter"> |
| <VALUE.REFERENCE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationFilter"> |
|
<KEYBINDING NAME="SystemCreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_UnitaryComputerSystem |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="SystemName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
server001.acme.com |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="CreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_IndicationFilter |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="Name"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
ACMESubscription12345 |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
</INSTANCENAME> |
| </VALUE.REFERENCE> |
| </KEYBINDING> |
| <KEYBINDING
NAME="Handler"> |
| <VALUE.REFERENCE> |
| <INSTANCENAME
CLASSNAME="CIM_IndicationHandlerCIMXML"> |
|
<KEYBINDING NAME="SystemCreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_UnitaryComputerSystem |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="SystemName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
server001.acme.com |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="CreationClassName"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
CIM_IndicationHandlerCIMXML |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
<KEYBINDING NAME="Name"> |
|
<KEYVALUE
VALUETYPE="string"> |
|
ACMESubscription12345 |
|
</KEYVALUE> |
|
</KEYBINDING> |
|
</INSTANCENAME> |
| </VALUE.REFERENCE> |
| </KEYBINDING> |
| </INSTANCENAME> |
| </IRETURNVALUE> |
| </IMETHODRESPONSE> |
| </SIMPLERSP> |
| </MESSAGE> |
| </CIM> |
Back to contents
A.13. Multiple Operations Example
The following HTTP request illustrates how a client would perform
Multiple Operations. The example below batches a GetClass,
an
EnumerateInstanceNames, and an
EnumerateInstance operation on
CIM_ObjectManagerAdapter.
POST /CIMOM1 HTTP/1.1
Authorization: Basic Z3Vlc3Q6Z3Vlc3Q=
Content-Length: XXX
Host: localhost:5988
CIMOperation: MethodCall
CIMProtocolVersion: 1.0
Content-Type: text/xml;charset=UTF-8
CIMBatch: CIMBatch
<?xml version="1.0" encoding="UTF-8"?>
<CIM DTDVERSION="2.0" CIMVERSION="2.0">
<MESSAGE ID="2004:2:5:1:1:11:41:1" PROTOCOLVERSION="1.0">
<MULTIREQ>
<SIMPLEREQ>
<IMETHODCALL
NAME="GetClass">
<LOCALNAMESPACEPATH>
<NAMESPACE NAME="interop" />
</LOCALNAMESPACEPATH>
<IPARAMVALUE
NAME="ClassName">
<CLASSNAME NAME="CIM_ObjectManagerAdapter" />
</IPARAMVALUE>
<IPARAMVALUE
NAME="LocalOnly">
<VALUE>FALSE</VALUE>
</IPARAMVALUE>
<IPARAMVALUE
NAME="IncludeClassOrigin">
<VALUE>TRUE</VALUE>
</IPARAMVALUE>
</IMETHODCALL>
</SIMPLEREQ>
<SIMPLEREQ>
<IMETHODCALL
NAME="Associators">
<LOCALNAMESPACEPATH>
<NAMESPACE NAME="interop" />
</LOCALNAMESPACEPATH>
<IPARAMVALUE
NAME="ObjectName">
<CLASSNAME NAME="CIM_ObjectManagerAdapter" />
</IPARAMVALUE>
<IPARAMVALUE
NAME="IncludeQualifiers">
<VALUE>TRUE</VALUE>
</IPARAMVALUE>
<IPARAMVALUE
NAME="IncludeClassOrigin">
<VALUE>TRUE</VALUE>
</IPARAMVALUE>
</IMETHODCALL>
</SIMPLEREQ>
<SIMPLEREQ>
<IMETHODCALL
NAME="EnumerateInstanceNames">
<LOCALNAMESPACEPATH>
<NAMESPACE NAME="interop" />
</LOCALNAMESPACEPATH>
<IPARAMVALUE
NAME="ClassName">
<CLASSNAME NAME="CIM_ObjectManagerAdapter" />
</IPARAMVALUE>
</IMETHODCALL>
</SIMPLEREQ>
<SIMPLEREQ>
<IMETHODCALL
NAME="EnumerateInstances">
<LOCALNAMESPACEPATH>
<NAMESPACE NAME="interop" />
</LOCALNAMESPACEPATH>
<IPARAMVALUE
NAME="ClassName">
<CLASSNAME NAME="CIM_ObjectManagerAdapter" />
</IPARAMVALUE>
<IPARAMVALUE
NAME="LocalOnly">
<VALUE>FALSE</VALUE>
</IPARAMVALUE>
</IMETHODCALL>
</SIMPLEREQ>
</MULTIREQ>
</MESSAGE>
</CIM>
|
The following is the HTTP response to the above request indicating
success of the above operation.
HTTP/1.1 200 OK
CIMOperation: MethodResponse
Content-Length: XXX
<?xml version="1.0" encoding="UTF-8"?>
<CIM DTDVERSION="2.0" CIMVERSION="2.0">
<MESSAGE ID="2004:2:5:1:1:11:41:1" PROTOCOLVERSION="1.0">
<MULTIRSP>
<SIMPLERSP>
<IMETHODRESPONSE
NAME="GetClass">
<IRETURNVALUE>
<CLASS SUPERCLASS="CIM_WBEMService"
NAME="CIM_ObjectManagerAdapter">
...
</CLASS>
</IRETURNVALUE>
</IMETHODRESPONSE>
</SIMPLERSP>
<SIMPLERSP>
<IMETHODRESPONSE
NAME="Associators">
<IRETURNVALUE>
<VALUE.OBJECTWITHPATH>
...
</VALUE.OBJECTWITHPATH>
<VALUE.OBJECTWITHPATH>
...
</VALUE.OBJECTWITHPATH>
...
</IRETURNVALUE>
</IMETHODRESPONSE>
</SIMPLERSP>
<SIMPLERSP>
<IMETHODRESPONSE
NAME="EnumerateInstanceNames">
<IRETURNVALUE>
<INSTANCENAME CLASSNAME="WBEMSolutions_ObjectManagerAdapter">
...
</INSTANCENAME>
<INSTANCENAME CLASSNAME="WBEMSolutions_ObjectManagerAdapter">
...
</INSTANCENAME>
...
</IRETURNVALUE>
</IMETHODRESPONSE>
</SIMPLERSP>
<SIMPLERSP>
<IMETHODRESPONSE
NAME="EnumerateInstances">
<IRETURNVALUE>
<VALUE.NAMEDINSTANCE>
...
</VALUE.NAMEDINSTANCE>
<VALUE.NAMEDINSTANCE>
...
</VALUE.NAMEDINSTANCE>
...
</IRETURNVALUE>
</IMETHODRESPONSE>
</SIMPLERSP>
</MULTIRSP>
</MESSAGE>
</CIM> |
Back to contents
Appendix C – LocalOnly Parameter Discussion
This section contains a discussion of the issues associated with the
1.1 definition of the LocalOnly parameter for the GetInstance and
EnumerateInstances
operations.
Explanation of the Deprecated 1.1 Interpretation
In April 2002, two DMTF Change Requests(CRs), CR809
(EnumerateInstances) and CR815 (GetInstance), were approved and
incorporated into the 1.1 version of this specification, to clarify the
interpretation of the LocalOnly flag for the GetInstance and
EnumerateInstances operations. With these CRs, the definition of the
LocalOnly flag for these operations was modified to align with the
interpretation of this flag for the GetClass and EnumerateClasses
operations. This change was incorrect, resulted in reduced
functionality and introduced a number of backward compatibility issues.
To further clarify the difference between the 1.0 Interpretation
and the 1.1 Interpretation (CR815), consider the following example:
class A {
[Key]
string name;
uint32 counter = 3;
};
class B : A {
uint32 moreData = 4;
};
instance of A {
name = "Roger";
};
instance of B {
name = "Karl";
counter = 3;
moreData = 5;
};
instance of B {
name = "Denise";
counter = 5;
};
Assuming PropertyList = NULL and LocalOnly = TRUE, the following
table shows the properties that would be returned by a GetInstance
operation.
| Instance |
1.0 Interpretation |
1.1 Interpretation |
| "Roger" |
name |
name, counter |
| "Karl" |
name, counter, moreData |
moreData |
| "Denise" |
name, counter |
moreData |
Note that the properties returned using the 1.0 Interpretation are
consistent with the properties specified in the MOF instance
definitions, while the properties returned using the 1.1 Interpretation
are consistent with the properties defined in the class definitions.
Risks associated with the use of the 1.1 Interpretation
(1) Within the DMTF, promoting a property from a class to one of its
superclasses is defined as a backward compatible change and therefore
can be made in a minor revision of the CIM Schema.
With the 1.1 Interpretation, promoting a property to a superclass
can cause backward incompatible changes.
Suppose, for example, version 1.0 of the Schema includes the
following definitions:
class A {
[Key]
string name;
uint32 counter = 3;
};
class B : A {
uint32 moreData = 4;
};
Now suppose that the Schema is modified in version 1.1 to promote
the property moreData from class B to class A.
class A {
[Key]
string name;
uint32 counter = 3;
uint32 moreData = 4;
};
class B : A {
};
Using the above example, the following table shows the properties
that would be returned by a call to GetInstance with PropertyList =
NULL and LocalOnly = TRUE. Note that, with the 1.1 Interpretation, this
Schema change would affect the list of properties returned. When
dealing with a CIM Server that complies with the 1.1 Interpretation,
applications need to be designed to treat “promoting properties” as a
backward compatible change.
| Instance |
Schema Version 1.0 |
Schema Version 1.1 |
| of A |
name, counter |
name, counter, moreData |
| of B |
moreData |
none |
(2) The 1.1 Interpretation promotes a use model that encourages
application developers to use multiple operations to retrieve the
properties of an instance.
I.e., a commonly stated use model for the 1.1 Interpretation is to
selectively traverse subclasses getting additional properties of an
instance. This practice significantly increases the risk that a client
will construct an instance that is inconsistent. With both
Interpretations, applications should be designed to ensure that
dependent properties are retrieved together.
Techniques for differentiating between the 1.0 Interpretation
and 1.1 Interpretation
For concrete classes, 1.0 Interpretation compliant CIM Servers will
return the value of all KEY properties that are not explicitly excluded
using the
PropertyList parameter, while 1.1 Interpretation compliant CIM Servers
will only return the value of KEY properties that are explicitly
defined in the
class. Application can use this difference to detect which
Interpretation is supported by a CIM Server.