1 mike 1.1 Specification for CIM Operations over HTTPDistributed Management Task Force,
2 Inc.
3 Specification for CIM Operations over HTTP
4 Version 1.0
5 August 11th, 1999
6 Technical inquiries and editorial comments should be directed in writing to:
7 Distributed Management Task Force, Inc. (DMTF)
8 c/o MacKenzie Kesselring, Inc.
9 200 SW Market Street, Suite 450,
10 Portland, OR 97201
11 (503) 225-0725
12 (503) 225-0765 (fax)
13 email: dmtf-info@dmtf.org
14 Participants
15 This list shows the names of the companies and organizations that have
16 participated in the Distributed Management Task Force - CIM TC XML
17 Sub-Committee whose contributions made this document possible.
18 Agranat Systems
19 Hewlett-Packard Company
20 IBM Corporation
21 Microsoft Corporation
22 mike 1.1 Tivoli Systems, Inc.
23 Customer Support Consortium
24 Sun Microsystems, Inc.
25 Intel Corporation
26 Change History
27 Version 1.0aMay 1st, 1999First Draft Release
28 Version 1.0bMay 7th, 1999Updates after first Working Group Review
29 Version 1.0cMay 11th, 1999Further updates
30 Version 1.0dMay 25th, 1999Changed LOCAL to PROPAGATED
31 Added VALUETYPE attribute to KEYVALUE
32 Version 1.0eMay 28th, 1999AssociationTraversal dependent on BasicRead.
33 not BasicWrite
34
35 CIMFunctionalGroups OPTIONS header renamed to
36 CIMSupportedFunctionalGroups
37
38 501 returned by server if it does not support multiple requests and
39 receives such a request
40
41 Added some operation parameters and allowed them to take default values
42 Version 1.0June 2nd, 1999Clarified meaning of default intrinsic
43 mike 1.1 parameter value
44 Resolved ambiguity over server response to protocol version that is not
45 supported
46 Clarified use of property list in Associators and References intrinsic
47 methods
48 July 6th, 1999Updated examples to reflect DTD changes
49 QueryExecution based on BasicRead, not BasicWrite
50 July 20th, 1999Remove IncludeClassOrigin and IncludeQualifiers
51 parameters from ExecQuery.
52 Parameters to Associators, AssocitorNames, References and ReferenceNames
53 which express class names are modelled as <className> rather than
54 string.
55 NewValue parameter to SetProperty is now OPTIONAL
56 Clarified semantics of optional parameters, and the distinction between
57 a default parameter value and a NULL parameter value.
58 Clarified Create and Modify operational semantics.
59 Clarified validation requirements and introduced CIMValidation header
60 for OPTIONS response.
61 Introduced CIMError response header to disambiguate fundamental
62 CIM-specific errors that map to the same HTTP status code.
63
64 mike 1.1 Contents
65 Abstract
66 1. Introduction
67
68 1.1. Requirements
69
70 1.2. Terminology
71
72 1.3. Style
73
74 2. CIM Operation Syntax and Semantics
75
76 2.1. Overview
77 2.1.1. Well-Formed, Valid and Loosely Valid
78 2.2. Operational Semantics
79 2.3. Method Invocations
80 2.3.1. Simple Operations
81 2.3.2. Multiple Operations
82 2.3.3. Status Codes
83 2.4. Intrinsic Methods
84 2.4.1. GetClass
85 mike 1.1 2.4.2. GetInstance
86 2.4.3. DeleteClass
87 2.4.4. DeleteInstance
88 2.4.5. CreateClass
89 2.4.6. CreateInstance
90 2.4.7. ModifyClass
91 2.4.8. ModifyInstance
92 2.4.9. EnumerateClasses
93 2.4.10. EnumerateClassNames
94 2.4.11. EnumerateInstances
95 2.4.12. EnumerateInstanceNames
96 2.4.13. ExecQuery
97 2.4.14. Associators
98 2.4.15. AssociatorNames
99 2.4.16. References
100 2.4.17. ReferenceNames
101 2.4.18. GetProperty
102 2.4.19. SetProperty
103 2.4.20. GetQualifier
104 2.4.21. SetQualifier
105 2.4.22. DeleteQualifier
106 mike 1.1 2.4.23. EnumerateQualifiers
107 2.5. Namespace Manipulation
108 2.6. Functional Profiles
109 2.7. Extrinsic Method Invocation
110 3. Encapsulation of CIM Operations
111
112 3.1. CIM Clients and Servers
113
114 3.2. Use of M-POST and POST
115
116 3.2.1. Use of the Ext Header
117
118 3.3. Extension Headers Defined for CIM Operation Requests and Responses
119
120 3.3.1. Naming of Extension Headers
121
122 3.3.2. Encoding of CIM Names within HTTP Headers
123
124 3.3.3. Encoding of CIM Object Paths within HTTP Headers
125 3.3.4. CIMOperation
126 3.3.5. CIMProtocolVersion
127 mike 1.1
128 3.3.6. CIMMethod
129
130 3.3.7. CIMObject
131
132 3.3.8. CIMBatch
133 3.3.9. CIMError
134 4. HTTP Requirements & Usage
135
136 4.1. HTTP Support
137
138 4.2. Use of Standard Headers
139
140 4.2.1. Accept
141
142 4.2.2. Accept-Charset
143
144 4.2.3. Accept-Encoding
145
146 4.2.4. Accept-Language
147
148 mike 1.1 4.2.5. Accept-Ranges
149
150 4.2.6. Allow
151
152 4.2.7. Authorization
153
154 4.2.8. Cache-Control
155
156 4.2.9. Connection
157
158 4.2.10. Content-Encoding
159
160 4.2.11. Content-Language
161
162 4.2.12. Content-Range
163
164 4.2.13. Content-Type
165
166 4.2.14. Expires
167
168 4.2.15. If-Range
169 mike 1.1
170 4.2.16. Proxy-Authenticate
171
172 4.2.17. Range
173
174 4.2.18. WWW-Authenticate
175
176 4.3. Errors and Status Codes
177
178 4.4. Security Considerations
179
180 4.5. Determining CIM Server Capabilities
181
182 4.5.1. CIMSupportedFunctionalGroups
183 4.5.2. CIMSupportsMultipleOperations
184 4.5.3. CIMSupportedQueryLanguages
185 4.5.4. CIMValidation
186 4.6. Other HTTP Methods
187
188 4.7. Discovery and Addressing
189
190 mike 1.1 4.8. Internationalization Considerations
191
192 5. References
193 Appendix A - Examples of Message Exchanges
194
195 A.1. Retrieval of a Single Class Definition
196 A.2. Retrieval of a Single Instance Definition
197 A.3. Deletion of a Single Class Definition
198 A.4. Deletion of a Single Instance Definition
199 A.5. Creation of a Single Class Definition
200 A.6. Creation of a Single Instance Definition
201 A.7. Enumeration of Class Names
202 A.8. Enumeration of Instances
203 A.9. Retrieval of a Single Property
204 A.10. Execution of an Extrinsic Method
205
206
207 Abstract
208 The Common Information Model (CIM) [1] is an object-oriented information model
209 defined by the Distributed Management Task Force (DMTF) which provides a
210 conceptual framework for describing management data.
211 mike 1.1 The Hypertext Transfer Protocol (HTTP) [6,7,10] is an application-level protocol
212 for distributed, collaborative, hypermedia information systems. It is a generic
213 stateless protocol which can be used for many tasks through extension of its
214 request methods, error codes and headers.
215 The Extensible Markup Language (XML) [3] is a simplified subset of SGML that
216 offers powerful and extensible data modeling capabilities. An XML Document is a
217 collection of data represented in XML. An XML Schema is a grammar that describes
218 the structure of an XML Document.
219 This document defines a mapping of CIM Operations onto HTTP that allows
220 implementations of CIM to interoperate in an open, standardized manner. It
221 utilizes the CIM XML DTD [2,11] that defines the XML Schema for CIM objects and
222 messages.
223 Back to contents
224 1. Introduction
225 This document defines a mapping of CIM operations onto HTTP that allows
226 implementations of CIM to operate in an open, standardized manner. It also
227 defines the notion of conformance in the context of this mapping, and describes
228 what behavior an implementation of CIM must exhibit in order to be described as
229 a conforming CIM implementation.
230 The remainder of this document is structured as follows.
231 Section 2 describes the CIM Operations which form the HTTP payload, using XML.
232 mike 1.1 It specifies the syntax and semantics of the operation requests and their
233 corresponding responses.
234 Section 3 describes the encapsulation of these messages in HTTP request and
235 response messages, with examples of each. It describes the extension headers
236 used to convey additional CIM-specific semantics in the HTTP Header.
237 Section 4 describes in more detail other aspects of the encapsulation:
238 HTTP Version Support
239 The use of standard HTTP Headers
240 HTTP Error codes
241 Security Considerations
242 Back to contents
243 1.1. Requirements
244 There are potentially many different ways in which CIM operations could be
245 represented within XML, and those operations encapsulated within HTTP messages.
246 In the interests of interoperability between different implementations of CIM
247 there is an obvious requirement for standardization of both the XML
248 representation and the HTTP encapsulation. The XML representation is defined in
249 [2,11]. This document utilizes that representation to defines the HTTP
250 encapsulation.
251 The following criteria have been applied to the representation of CIM Operations
252 in XML [2,11]:
253 mike 1.1 Each CIM Operation is described completely in XML; completeness is favored
254 over conciseness.
255 The set of CIM Operations provide sufficient functionality to enable
256 implementations of CIM to communicate effectively for the purposes of
257 management. It is not a goal of the first release of this mapping to provide a
258 complete set of operations. It is a goal to define the mapping so as to admit
259 straightfoward extension (addition of further features) in future versions.
260 The set of CIM Operations are classified into functional profiles so that a
261 range of implementations (varying from complete support of all operations to
262 support of a minimal subset) is allowed. The number of functional profiles is
263 kept as small as possible to encourage interoperability, and mechanisms
264 provided by which CIM implementations can declare their level of support.
265 The following criteria have been applied to the HTTP encapsulation of CIM
266 Operations herein:
267 In recognition of the large installed base of HTTP/1.0 systems, the
268 encapsulation is designed to support both HTTP/1.0 and HTTP/1.1
269 The encapsulation does not introduce any requirements which are in conflict
270 with those stated in HTTP/1.0 or HTTP/1.1
271 The encapsulation should be straightforwardly usable over the current base
272 HTTP infrastructures. Some features are intended to anticipate and exploit
273 enhancements to this base, but no aspects of the encapsulation require any
274 mike 1.1 such enhancements as mandatory.
275 The encapsulation avoids the use of pure HTTP Tunnelling or URL munging (e.g.
276 the use of the "?" character) in favor of a mechanism which allows existing
277 HTTP infrastructures to safely control content.
278 The encapsulation exposes key CIM operation information in Headers to allow
279 efficient firewall/proxy handling. The information is limited to that which
280 is considered essential, in order not to have significant impact on the size
281 of the Header. No CIM-specific information appears in a Header that does not
282 also appear within the CIM Operation.
283 There is a clear and unambiguous encapsulation of the CIM Operation payload
284 within the HTTP Message. Conciseness of the encapsulation is of secondary
285 importance.
286 Back to contents
287 1.2. Terminology
288 The key phrases and words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD,
289 SHOULD NOT, RECOMMENDED, MAY and OPTIONAL in this document are to be interpreted
290 as described in RFC 2119 [8].
291 This specification uses the same notational conventions and basic parsing
292 constructs as defined in [7].
293 Back to contents
294 1.3. Style
295 mike 1.1 This document uses a number of stylistic conventions to highlight examples and
296 definitions.
297 Examples are displayed in this fashion:
298 This is an example
299
300 Definitions are illustrated thusly:
301 This is a definition
302
303 Back to contents
304 2. CIM Operation Syntax and Semantics
305 2.1. Overview
306 This specification defines all interactions between CIM entities as Operations.
307 CIM Operations belong to a larger category known as CIM Messages (currently all
308 Messages are Operations, but in future this may not be true).
309 This section describes the syntax and semantics of CIM Operations in a manner
310 independent of the encapsulation of such operations within a particular protocol
311 (such as HTTP).
312 XML is used as the basis for this description, and in particular the CIM XML DTD
313 [2,11].
314 Back to contents
315 2.1.1. Well-Formed, Valid and Loosely Valid
316 mike 1.1 Where this document makes reference to the concept of a Well-formed or Valid XML
317 documents, the meaning intended is the standard one defined in [3].
318 XML DTDs are restricted to these terms to describe XML documents, but this
319 document requires a further classification of an XML document with respect to a
320 DTD. Henceforth the term loosely valid is defined to apply to an XML Document
321 with the following characteristics:
322 If any attributes or elements in the XML document which do not appear in the
323 CIM XML DTD are removed, then the resulting document is valid with respect to
324 the CIM XML DTD.
325 In effect, a loosely valid document is one which is valid with respect to the
326 CIM XML DTD apart from having additional attributes or elements not defined by
327 that DTD. The concept is very similar to that of an open content model as
328 defined by the working draft on XML Schemas [21], expressed within the more
329 limited scope of DTDs. One corollary of this definition is that any XML document
330 that is valid with respect to the CIM XML DTD is also loosely valid.
331 The motivation for introducing this class of XML Documents is to relax the
332 restrictions on a CIM Client or a CIM Server when parsing received XML documents
333 defined within the scope of this mapping. It is recognized that not all Clients
334 (respectively, Servers) should be required to validate each received Operation
335 Response Message (respectively, Operation Request Message) as this would place
336 too great a processing burden on the validating entity at the expense of
337 mike 1.1 footprint and performance, most notably in communication between robust and
338 conformant implementations of this mapping.
339 Instead the following requirements are made by this specification:
340 A CIM Client (respectively, CIM Server) MAY include a DOCTYPE element in an
341 Operation Request Message (respectively, Operation Response Message). If so,
342 an External declaration SHOULD be used (in-lining of the complete DTD within a
343 message is discouraged).
344 A CIM Client (respectively, CIM Server) MAY elect to validate a received
345 Operation Response Message (respectively, Operation Request Message).
346 If a CIM Client (respectively, CIM Server) elects not to validate a received
347 Operation Response Message (respectively, Operation Request Message), then
348 loose validation MUST be enforced.
349 The behavior of a CIM Server with respect to a received Operation Request
350 Message is covered in detail in the section on Errors and Status Codes .
351 2.2. Operational Semantics
352 The CIM XML DTD [2,11] defines a subelement under the root <CIM> element called
353 <MESSAGE>, which contains one of the following subelements:
354 <SIMPLEREQ>
355 <SIMPLERSP>
356 <MULTIREQ>
357 <MULTIRSP>
358 mike 1.1 In the remainder of this document:
359 The term Operation Request Message denotes an XML document that is loosely
360 valid with respect to the CIM XML DTD, which contains under the root <CIM>
361 node a <MESSAGE> subelement, under which there is a <MULTIREQ> or <SIMPLEREQ>
362 subelement, and;
363 The term Operation Response Message denotes an XML document that is loosely
364 valid with respect to the CIM XML DTD, which contains under the root <CIM>
365 node a <MESSAGE> subelement, under which there is a <MULTIRSP> or <SIMPLERSP>
366 subelement.
367 An Operation Request Message MUST contain a non-empty value for the ID attribute
368 of the <MESSAGE> element. The corresponding Operation Response Message MUST
369 supply the same value for that attribute. Clients SHOULD employ a message ID
370 scheme that minimizes the chance of receiving a stale Operation Response
371 Message.
372 Any Operation Request Message or Operation Response Message conforming to this
373 specification MUST specify a value of "1.0" for the PROTOCOLVERSION attribute of
374 the <MESSAGE> element.
375 An Operation Response Message sent in response to an Operation Request Message
376 MUST:
377 specify the same value for the ID attribute of the <MESSAGE> element as
378 appeared in the Operation Request Message, and
379 mike 1.1 contain a <MULTIRSP> subelement if the Operation Request Message contained a
380 <MULTIREQ> subelement, or
381 contain a <SIMPLERSP> subelement if the Operation Request Message contained
382 a <SIMPLEREQ> subelement.
383 A Simple Operation Request is an Operation Request Message that contains a
384 <SIMPLEREQ> subelement. A Simple Operation Response is an Operation Response
385 Message that contains a <SIMPLERSP> subelement.
386 A Multiple Operation Request is an Operation Request Message that contains a
387 <MULTIREQ> subelement. A Multiple Operation Response is an Operation Response
388 Message that contains a <MULTIRSP> subelement.
389 Back to contents
390 2.3. Method Invocations
391 All CIM Operation requests defined for this mapping are defined as invocations
392 of one or more methods. A method may be either:
393 Intrinsic, which means that it is defined by this specification for the
394 purposes of modelling a CIM operation, or;
395 Extrinsic, which means that it is defined as a method on a CIM Class in some
396 Schema.
397 Intrinsic methods are further characterized by the fact that they are made
398 against a CIM Namespace. Extrinsic methods are invoked on a CIM Class (if
399 static) or Instance (otherwise). Intrinsic methods are defined in the section
400 mike 1.1 Intrinsic Methods
401 An extrinsic method call is represented in XML by the <METHODCALL> element, and
402 the response to that call represented by the <METHODRESPONSE> element.
403 An intrinsic method call is represented in XML by the <IMETHODCALL> element, and
404 the response to that call represented by the <IMETHODRESPONSE> element.
405 An Input parameter is one with an IN Qualifier (with value true) in the Method
406 definition. An Output parameter is one with an OUT Qualifier (with value true)
407 in the Method definition. An Optional parameter is one with an OPTIONAL
408 Qualifier in the Method definition. A parameter may be both an Input and Output
409 parameter.
410 The <METHODCALL> or <IMETHODCALL> element serves to name the method to be
411 invoked and supply any Input parameters to the method call. Note that:
412 Each Input parameter MUST be named using the name assigned in the method
413 definition.
414 The Input parameters MAY be supplied in any order.
415 Each Input parameter of the method, and no others, MUST be present in the
416 call, unless it was defined as Optional.
417 The <METHODRESPONSE> or <IMETHODRESPONSE> element defines either an <ERROR> or a
418 (possibly optional) return value and output parameters (i.e. one decorated with
419 the OUT Qualifier in the method definition). In the latter case:
420 Each Output parameter MUST be named using the name assigned in the method
421 mike 1.1 definition.
422 The Output parameters MAY be supplied in any order.
423 Each Output parameter of the method, and no others, MUST be present in the
424 response, unless it was defined as Optional.
425 The method invocation process may be thought of as:
426 The binding of the input parameter values specified as subelements of the
427 <METHODCALL> or <IMETHODCALL> element to the input parameters of the Method,
428 followed by;
429 The attempted execution of the method using the bound input parameters, and;
430 If attempt to call the method is successful, the binding of the the return
431 value and output parameters to the subelements of the <METHODRESPONSE> or
432 <IMETHODRESPONSE> element, or;
433 If the attempt to call the method is unsuccesful, the binding of an error
434 code and (optional) human-readable description of that code to the
435 <METHODRESPONSE> or <IMETHODRESPONSE> element.
436 Back to contents
437 2.3.1. Simple Operations
438 A simple operation is defined as one that requires the invocation of a single
439 method. A simple operation request is represented by a <SIMPLEREQ> element, and
440 a simple operation response by a <SIMPLERSP> element.
441 If the method is intrinsic then the <SIMPLEREQ> MUST contain a <IMETHODCALL>
442 mike 1.1 element, which in turn contains a <LOCALNAMESPACEPATH> subelement identifying
443 the local CIM Namespace against which the method is to be executed. If the
444 method is extrinsic then the <SIMPLEREQ> element MUST contain a <METHODCALL>
445 element which in turn contains either:
446 A <LOCALCLASSPATH> subelement identifying the CIM Class on which the method is
447 to be invoked, in the case that the method is static, or;
448 An <LOCALINSTANCEPATH> subelement identifying the CIM Instance on which the
449 method is to be invoked, otherwise.
450 Back to contents
451 2.3.2. Multiple Operations
452 A multiple operation is defined as one that requires the invocation of more than
453 one method. A multiple operation request is represented by a <MULTIREQ>
454 element, and a multiple operation response by a <MULTIRSP> element.
455 A <MULTIREQ> (respectively, <MULTIRSP>) element is a sequence of two or more
456 <SIMPLEREQ> (respectively, <SIMPLERSP>) elements.
457 A <MULTIRSP> element MUST contain a <SIMPLERSP> element for every <SIMPLEREQ>
458 element in the corresponding Multiple Operation Response, and these <SIMPLERSP>
459 elements MUST be in the same order as their <SIMPLEREQ> counterparts (so the
460 first <SIMPLERSP> in the response corresponds to the first <SIMPLEREQ> in the
461 request, and so forth).
462 Multiple Operations provide a convenient mechanism whereby multiple method
463 mike 1.1 invocations may be batched into a single HTTP Message, thereby reducing the
464 number of roundtrips between a CIM Client and a CIM Server and allowing the CIM
465 Server to make certain internal optimizations should it choose so to do. Note
466 that Multiple Operations do not confer any transactional capabilities in the
467 processing of the request (for example, there is no requirement that the CIM
468 Server guarantee that the constituent method calls either all failed or all
469 succeeded, only that the entity make a "best effort" to process the operation).
470 Not all CIM Servers support Multiple Operations; the means by which they declare
471 support for this feature is defined in the section on Determining CIM Server
472 Capabilities.
473 Back to contents
474 2.3.3. Status Codes
475 This section defines the status codes that may be returned by a conforming CIM
476 Server application as the value of the CODE attribute of an <ERROR> subelement
477 within a <METHODRESPONSE> or <IMETHODRESPONSE> element.
478 The symbolic names defined in the table below do not appear on the wire. They
479 are used here solely as a convenient way to refer to an error in other parts of
480 this specification.
481 Not all methods would be expected to return all the status codes listed below.
482 For intrinsic methods, the relevant section on each method in this specification
483 defines the expected error codes to be returned. For extrinsic methods the
484 mike 1.1 specification of which of the following codes can be used is described in the
485 section on Extrinsic Method Invocation .
486 Symbolic NameCODEDefinition
487 CIM_ERR_FAILED1A general error occured that is not covered by a more
488 specific error code
489 CIM_ERR_ACCESS_DENIED2Access to a CIM resource was not available to the
490 client
491 CIM_ERR_INVALID_NAMESPACE3The target namespace does not exist
492 CIM_ERR_INVALID_PARAMETER4One or more parameter values passed to the
493 method were invalid
494 CIM_ERR_INVALID_CLASS5The specified Class does not exist
495 CIM_ERR_NOT_FOUND6The requested object could not be found
496 CIM_ERR_NOT_SUPPORTED7The requested operation is not supported
497 CIM_ERR_CLASS_HAS_CHILDREN8Operation cannot be carried out on this class
498 since it has subclasses
499 CIM_ERR_CLASS_HAS_INSTANCES9Operation cannot be carried out on this class
500 since it has instances
501 CIM_ERR_INVALID_SUPERCLASS10Operation cannot be carried out since the
502 specified superclass does not exist
503 CIM_ERR_ALREADY_EXISTS11Operation cannot be carried out because an object
504 already exists
505 mike 1.1 CIM_ERR_NO_SUCH_PROPERTY12The specified Property does not exist
506 CIM_ERR_TYPE_MISMATCH13The value supplied is incompatible with the type
507 CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED14The query language is not recognized
508 or supported
509 CIM_ERR_INVALID_QUERY15The query is not valid for the specified query
510 language
511 CIM_ERR_METHOD_NOT_AVAILABLE16The extrinsic Method could not be executed
512 CIM_ERR_METHOD_NOT_FOUND17The specified extrinsic Method does not exist
513
514 Back to contents
515 2.4. Intrinsic Methods
516 This section describes the Intrinsic methods that are defined outside of schema
517 for the purposes of CIM operations. These methods can only be called on a CIM
518 Namespace, rather than a CIM Class or CIM Instance.
519 The following intrinsic methods are defined by this specification:
520 Get a CIM Class
521 Get a CIM Instance
522 Delete a CIM Class
523 Delete a CIM Instance
524 Create a CIM Class
525 Create a CIM Instance
526 mike 1.1 Modify a CIM Class
527 Modify a CIM Instance
528 Enumerate subclasses of a CIM Class
529 Enumerate subclass names of a CIM Class
530 Enumerate instances of a CIM Class
531 Enumerate instance names of a CIM Class
532 Delete a CIM Qualifier definition
533 Create a CIM Qualifier definition
534 Enumerate CIM Qualifier definitions
535 Execute a Query
536 Enumerate associators of a CIM Object
537 Enumerate names of associators of a CIM Object
538 Enumerate references to a CIM Object
539 Enumerate names of references to a CIM Object
540 Get a CIM Property value from a CIM Instance
541 Set a CIM Property value from a CIM Instance
542 Get a Qualifier declaration
543 Set a Qualifier declaration
544 Delete a Qualifier declaration
545 Enumerate Qualifier declarations
546 The convention used in the following subsections to define the signatures of the
547 mike 1.1 intrinsic methods is a pseudo-MOF notation that extends the standard MOF BNF [1]
548 for describing CIM Methods with a number of pseudo parameter types (which are
549 indicated by being placed within "<" and ">" characters).
550 This notation admits of the decoration of parameters with a number of
551 pseudo-qualifiers (IN, OPTIONAL and NULL) to define their invocation semantics.
552 It is important to understand that these qualifiers are used for descriptional
553 purposes only within the scope of this specification, and in particular a CIM
554 Client MUST NOT specify them in intrinsic method invocations.
555 This notation uses the IN qualifier to denote that the parameter is an input
556 parameter.
557 This notation uses the OPTIONAL qualifier to indicate paramaters whose presence
558 is not mandatory, and declares default values for optional method parameters
559 using similar notation employed for default property values in MOF.
560 A CIM Client MAY omit an optional parameter in the case that the required value
561 is the specified default, by not specifying an <IPARAMVALUE> element for that
562 parameter. It MUST NOT omit any parameter that is not marked as optional.
563 This notation uses the NULL qualifier to indicate parameters whose values may be
564 be specified as NULL in a method call. A NULL (unassigned) value for a parameter
565 is specified by an <IPARAMVALUE> element with no subelement. For parameters
566 which do not possess the NULL qualifier, the CIM Client MUST specify a value for
567 the parameter by including a suitable subelement for the <IPARAMVALUE> element
568 mike 1.1 for that parameter.
569 All parameters MUST be named uniquely, and MUST correspond to a valid parameter
570 name for that method as described by this specification. The order of the
571 parameters is not significant.
572 The non-NULL values of intrinsic method parameters or return values which are
573 modelled as standard CIM types (such as string and boolean, or arrays thereof)
574 are represented as follows:
575 Simple values MUST be represented using the <VALUE> subelement within an
576 <IPARAMETER> element (for method parameters) or within an <IRETURNVALUE>
577 element (for method return values).
578 Array values MUST be represented using the <VALUE.ARRAY> subelement within an
579 <IPARAMETER> element (for method parameters) or within an <IRETURNVALUE>
580 element (for method return values).
581 The following table describes how each of the pseudo-types used by the intrinsic
582 methods MUST be mapped to an XML element described in [2] in the context of both
583 a parameter value (subelement of <IPARAMVALUE>) and a return value (subelement
584 of <IRETURNVALUE>).
585 TypeXML Element
586 <object>(VALUE.OBJECT|VALUE.OBJECTWITHLOCALPATH|VALUE.OBJECTWITHPATH)
587 <class>CLASS
588 <instance>INSTANCE
589 mike 1.1 <className>CLASSNAME
590 <namedInstance>VALUE.NAMEDINSTANCE
591 <instanceName>INSTANCENAME
592 <objectWithPath>VALUE.OBJECTWITHPATH
593 <objectName>(CLASSNAME|INSTANCENAME)
594 <propertyValue>(VALUE|VALUE.ARRAY|VALUE.REFERENCE)
595 <qualifierDecl>QUALIFIER.DECLARATION
596
597 Back to contents
598 2.4.1. GetClass
599 This operation is used to return a single CIM Class from the target Namespace.
600 GetClass
601 <class> GetClass (
602 [IN] <className> ClassName,
603 [IN,OPTIONAL] boolean LocalOnly = true,
604 [IN,OPTIONAL] boolean IncludeQualifiers = true,
605 [IN,OPTIONAL] boolean IncludeClassOrigin = false,
606 [IN,OPTIONAL,NULL] string PropertyList [] = NULL
607 )
608
609 The ClassName input parameter defines the name of the Class to be retrieved.
610 mike 1.1 If the LocalOnly input parameter is true, this specifies that only CIM Elements
611 (properties, methods and qualifiers) overriden within the definition of the
612 Class are returned [1]. If false, all elements are returned. This parameter
613 therefore effects a CIM Server-side mechanism to filter certain elements of the
614 returned object based on whether or not they have been propagated from the
615 parent Class (as defined by the PROPAGATED attribute).
616 If the IncludeQualifiers input parameter is true, this specifies that all
617 Qualifiers for that Class (including Qualifiers on the Class and on any returned
618 Properties, Methods or Method Parameters) MUST be included as <QUALIFIER>
619 elements in the response. If false no <QUALIFIER> elements are present in the
620 returned Class.
621 If the IncludeClassOrigin input parameter is true, this specifies that the
622 CLASSORIGIN attribute MUST be present on all appropriate elements in the
623 returned Class. If false, no CLASSORIGIN attributes are present in the returned
624 Class.
625 If the PropertyList input parameter is not NULL, the members of the array define
626 one or more Property names. The returned Class MUST NOT include elements for
627 any Properties missing from this list. Note that if LocalOnly is specified as
628 true this acts as an additional filter on the set of Properties returned (for
629 example, if Property A is included in the PropertyList but LocalOnly is set to
630 true and A is not local to the requested Class, then it will not be included in
631 mike 1.1 the response). If the PropertyList input parameter is an empty array this
632 signifies that no Properties are included in the response. If the PropertyList
633 input parameter is NULL this specifies that all Properties (subject to the
634 conditions expressed by the other parameters) are included in the response.
635 If the PropertyList contains duplicate elements, the Server MUST ignore the
636 duplicates but otherwise process the request normally. If the PropertyList
637 contains elements which are invalid Property names for the target Class, the
638 Server MUST ignore such entries but otherwise process the request normally.
639 If successful, the return value is a single CIM Class.
640 If unsuccessful, one of the following status codes MUST be returned by this
641 method, where the first applicable error in the list (starting with the first
642 element of the list, and working down) is the error returned. Any additional
643 method-specific interpretation of the error in is given in parentheses.
644 CIM_ERR_ACCESS_DENIED
645 CIM_ERR_INVALID_NAMESPACE
646 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
647 otherwise incorrect parameters)
648 CIM_ERR_NOT_FOUND (the request CIM Class does not exist in the specified
649 namespace)
650 CIM_ERR_FAILED (some other unspecified error occurred)
651 Back to contents
652 mike 1.1 2.4.2. GetInstance
653 This operation is used to return a single CIM Instance from the target
654 Namespace.
655 GetInstance
656 <instance> GetInstance (
657 [IN] <instanceName> InstanceName,
658 [IN,OPTIONAL] boolean LocalOnly = true,
659 [IN,OPTIONAL] boolean IncludeQualifiers = false,
660 [IN,OPTIONAL] boolean IncludeClassOrigin = false,
661 [IN,OPTIONAL,NULL] string PropertyList [] = NULL
662 )
663
664 The InstanceName input parameter defines the name of the Instance to be
665 retrieved.
666 If the LocalOnly input parameter is true, this specifies that only elements
667 (properties and qualifiers) overriden within the definition of the Instance are
668 returned [1]. If false, all elements are returned. This parameter therefore
669 effects a CIM Server-side mechanism to filter certain elements of the returned
670 object based on whether or not they have been propagated from the parent Class
671 (as defined by the PROPAGATED attribute).
672 If the IncludeQualifiers input parameter is true, this specifies that all
673 mike 1.1 Qualifiers for that Instance (including Qualifiers on the Instance and on any
674 returned Properties) MUST be included as <QUALIFIER> elements in the response.
675 If false no <QUALIFIER> elements are present in the returned Instance.
676 If the IncludeClassOrigin input parameter is true, this specifies that the
677 CLASSORIGIN attribute MUST be present on all appropriate elements in the
678 returned Instance. If false, no CLASSORIGIN attributes are present in the
679 returned Instance.
680 If the PropertyList input parameter is not NULL, the members of the array define
681 one or more Property names. The returned Instance MUST NOT include elements for
682 any Properties missing from this list. Note that if LocalOnly is specified as
683 true this acts as an additional filter on the set of Properties returned (for
684 example, if Property A is included in the PropertyList but LocalOnly is set to
685 true and A is not local to the requested Instance, then it will not be included
686 in the response). If the PropertyList input parameter is an empty array this
687 signifies that no Properties are included in the response. If the PropertyList
688 input parameter is NULL this specifies that all Properties (subject to the
689 conditions expressed by the other parameters) are included in the response.
690 If the PropertyList contains duplicate elements, the Server MUST ignore the
691 duplicates but otherwise process the request normally. If the PropertyList
692 contains elements which are invalid Property names for the target Instance, the
693 Server MUST ignore such entries but otherwise process the request normally.
694 mike 1.1 If successful, the return value is a single CIM Instance.
695 If unsuccessful, one of the following status codes MUST be returned by this
696 method, where the first applicable error in the list (starting with the first
697 element of the list, and working down) is the error returned. Any additional
698 method-specific interpretation of the error in is given in parentheses.
699 CIM_ERR_ACCESS_DENIED
700 CIM_ERR_INVALID_NAMESPACE
701 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
702 otherwise incorrect parameters)
703 CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
704 namespace)
705 CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested CIM Instance
706 does not exist in the specified namespace)
707 CIM_ERR_FAILED (some other unspecified error occurred)
708 Back to contents
709 2.4.3. DeleteClass
710 This operation is used to delete a single CIM Class from the target Namespace.
711 DeleteClass
712 void DeleteClass (
713 [IN] <className> ClassName
714 )
715 mike 1.1
716 The ClassName input parameter defines the name of the Class to be deleted.
717 If successful, the specified Class (including any subclasses and any instances)
718 MUST have been removed by the CIM Server. The operation MUST fail if any one of
719 these objects cannot be deleted.
720 If unsuccessful, one of the following status codes MUST be returned by this
721 method, where the first applicable error in the list (starting with the first
722 element of the list, and working down) is the error returned. Any additional
723 method-specific interpretation of the error in is given in parentheses.
724 CIM_ERR_ACCESS_DENIED
725 CIM_ERR_NOT_SUPPORTED
726 CIM_ERR_INVALID_NAMESPACE
727 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
728 otherwise incorrect parameters)
729 CIM_ERR_NOT_FOUND (the CIM Class to be deleted does not exist)
730 CIM_ERR_CLASS_HAS_CHILDREN (the CIM Class has one or more subclasses which
731 cannot be deleted)
732 CIM_ERR_CLASS_HAS_INSTANCES (the CIM Class has one or more instances which
733 cannot be deleted)
734 CIM_ERR_FAILED (some other unspecified error occurred)
735 Back to contents
736 mike 1.1 2.4.4. DeleteInstance
737 This operation is used to delete a single CIM Instance from the target
738 Namespace.
739 DeleteInstance
740 void DeleteInstance (
741 [IN] <instanceName> InstanceName
742 )
743
744 The InstanceName input parameter defines the name (model path) of the Instance
745 to be deleted.
746 If successful, the specified Instance MUST have been removed by the CIM Server.
747 If unsuccessful, one of the following status codes MUST be returned by this
748 method, where the first applicable error in the list (starting with the first
749 element of the list, and working down) is the error returned. Any additional
750 method-specific interpretation of the error in is given in parentheses.
751 CIM_ERR_ACCESS_DENIED
752 CIM_ERR_NOT_SUPPORTED
753 CIM_ERR_INVALID_NAMESPACE
754 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
755 otherwise incorrect parameters)
756 CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
757 mike 1.1 namespace)
758 CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested CIM Instance
759 does not exist in the specified namespace)
760 CIM_ERR_FAILED (some other unspecified error occurred)
761 Back to contents
762 2.4.5. CreateClass
763 This operation is used to create a single CIM Class in the target Namespace.
764 The Class MUST NOT already exist.
765 CreateClass
766 void CreateClass (
767 [IN] <class> NewClass
768 )
769
770 The NewClass input parameter defines the new Class. The proposed definition
771 MUST be a correct Class definition according to the CIM specification [1].
772 In processing the creation of the new Class, the following rules MUST be
773 conformed to by the CIM Server:
774 Any CLASSORIGIN and PROPAGATED attributes in the NewClass MUST be ignored by
775 the Server.
776 If the new Class has no Superclass, the NewClass parameter defines a new base
777 Class. The Server MUST ensure that all Properties and Methods of the new Class
778 mike 1.1 have a CLASSORIGIN attribute whose value is the name of the new Class.
779 If the new Class has a Superclass, the NewClass parameter defines a new
780 Subclass of that Superclass. The Superclass MUST exist. The Server MUST ensure
781 that:
782 Any Properties, Methods or Qualifiers in the Subclass not defined in the
783 Superclass are created as new elements of the Subclass. In particular the
784 Server MUST set the CLASSORIGIN attribute on the new Properties and Methods
785 to the name of the Subclass, and ensure that all other Properties and
786 Methods preserve their CLASSORIGIN attribute value from that defined in the
787 Superclass.
788 If a Property is defined in the Superclass and in the Subclass, the value
789 assigned to that property in the Subclass (including NULL) becomes the
790 default value of the property for the Subclass.
791 If a Property or Method of the Superclass is not specified in the Subclass,
792 then that Property or Method is inherited without modification by the
793 Subclass.
794 Any Qualifiers defined in the Superclass with a TOSUBCLASS attribute value
795 of true MUST appear in the resulting Subclass. Qualifiers in the Superclass
796 with a TOSUBCLASS attribute value of false MUST NOT be propagated to the
797 Subclass.
798 Any Qualifier propagated from the Superclass cannot be modified in the
799 mike 1.1 Subclass if the OVERRIDABLE attribute of that Qualifier was set to false in
800 the Superclass. It is a Client error to specify such a Qualifier in the
801 NewClass with a different definition to that in the Superclass (where
802 definition encompasses the name, type and flavor attribute settings of the
803 <QUALIFIER> element, and the value of the Qualifier).
804 If successful, the specified Class MUST have been created by the CIM Server.
805 If unsuccessful, one of the following status codes MUST be returned by this
806 method, where the first applicable error in the list (starting with the first
807 element of the list, and working down) is the error returned. Any additional
808 method-specific interpretation of the error in is given in parentheses.
809 CIM_ERR_ACCESS_DENIED
810 CIM_ERR_NOT_SUPPORTED
811 CIM_ERR_INVALID_NAMESPACE
812 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
813 otherwise incorrect parameters)
814 CIM_ERR_ALREADY_EXISTS (the CIM Class already exists)
815 CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a non-existent
816 superclass)
817 CIM_ERR_FAILED (some other unspecified error occurred)
818 Back to contents
819 2.4.6. CreateInstance
820 mike 1.1 This operation is used to create a single CIM Instance in the target Namespace.
821 The Instance MUST NOT already exist.
822 CreateInstance
823 <instanceName> CreateInstance (
824 [IN] <instance> NewInstance
825 )
826
827 The NewInstance input parameter defines the new Instance. The proposed
828 definition MUST be a correct Instance definition for the underlying CIM Class
829 according to the CIM specification [1].
830 In processing the creation of the new Instance, the following rules MUST be
831 conformed to by the CIM Server:
832 Any CLASSORIGIN and PROPAGATED attributes in the NewInstance MUST be ignored
833 by the Server.
834 The Server MUST ensure that:
835 Any Qualifiers in the Instance not defined in the Class are created as new
836 elements of the Instance.
837 All Properties of the Instance preserve their CLASSORIGIN attribute value
838 from that defined in the Class.
839 If a Property is specified in the ModifiedInstance parameter, the value
840 assigned to that property in the Instance (including NULL) becomes the value
841 mike 1.1 of the property for the Instance. Note that it is a Client error to specify
842 a Property that does not belong to the Class.
843 If a Property of the Class is not specified in the Instance, then that
844 Property is inherited without modification by the Instance.
845 Any Qualifiers defined in the Class with a TOINSTANCE attribute value of
846 true appear in the Instance. Qualifiers in the Class with a TOINSTANCE
847 attribute value of false MUST NOT be propagated to the Instance.
848 Any Qualifier propagated from the Class cannot be modified in the Instance
849 if the OVERRIDABLE attribute of that Qualifier was set to false in the
850 Class. It is a Client error to specify such a Qualifier in the NewInstance
851 with a different definition to that in the Class (where definition
852 encompasses the name, type and flavor attribute settings of the <QUALIFIER>
853 element, and the value of the Qualifier).
854 If successful, the return value defines the object path of the new CIM Instance
855 relative to the target Namespace (i.e. the Model Path as defined by [1]),
856 created by the CIM Server. It is returned in case one or more of the new keys
857 of the Instance are allocated dynamically during the creation process rather
858 than specified in the request.
859 If unsuccessful, one of the following status codes MUST be returned by this
860 method, where the first applicable error in the list (starting with the first
861 element of the list, and working down) is the error returned. Any additional
862 mike 1.1 method-specific interpretation of the error in is given in parentheses.
863 CIM_ERR_ACCESS_DENIED
864 CIM_ERR_NOT_SUPPORTED
865 CIM_ERR_INVALID_NAMESPACE
866 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
867 otherwise incorrect parameters)
868 CIM_ERR_INVALID_CLASS (the CIM Class of which this is to be a new Instance
869 does not exist)
870 CIM_ERR_ALREADY_EXISTS (the CIM Instance already exists)
871 CIM_ERR_FAILED (some other unspecified error occurred)
872 Back to contents
873 2.4.7. ModifyClass
874 This operation is used to modify an existing CIM Class in the target Namespace.
875 The Class MUST already exist.
876 ModifyClass
877 void ModifyClass (
878 [IN] <class> ModifiedClass
879 )
880
881 The ModifiedClass input parameter defines the set of changes (which MUST be
882 correct amendments to the CIM Class as defined by the CIM Specification [1]) to
883 mike 1.1 be made to the current class definition.
884 In processing the modifcation of the Class, the following rules MUST be
885 conformed to by the CIM Server:
886 Any CLASSORIGIN and PROPAGATED attributes in the ModifiedClass MUST be ignored
887 by the Server.
888 If the modified Class has no Superclass, the ModifiedClass parameter defines
889 modifications to a base Class. The Server MUST ensure that:
890 All Properties and Methods of the modified Class have a CLASSORIGIN
891 attribute whose value is the name of this Class.
892 Any Properties, Methods or Qualifiers in the existing Class definition which
893 do not appear in the ModifiedClass parameter are removed from the resulting
894 modified Class.
895 If the modified Class has a Superclass, the ModifiedClass parameter defines
896 modifications to a Subclass of that Superclass. The Superclass MUST exist, and
897 the Client MUST NOT change the name of the Superclass in the modified
898 Subclass. The Server MUST ensure that:
899 Any Properties, Methods or Qualifiers in the Subclass not defined in the
900 Superclass are created as elements of the Subclass. In particular the Server
901 MUST set the CLASSORIGIN attribute on the new Properties and Methods to the
902 name of the Subclass, and MUST ensure that all other Properties and Methods
903 preserve their CLASSORIGIN attribute value from that defined in the
904 mike 1.1 Superclass.
905 Any Property, Method or Qualifier previously defined in the Subclass but not
906 defined in the Superclass, and which is not present in the ModifiedClass
907 parameter, is removed from the Subclass.
908 If a Property is specified in the ModifiedClass parameter, the value
909 assigned to that property therein (including NULL) becomes the default value
910 of the property for the Subclass.
911 If a Property or Method of the Superclass is not specified in the Subclass,
912 then that Property or Method is inherited without modification by the
913 Subclass (so that any previous changes to such an Element in the Subclass
914 are lost).
915 If a Qualifier in the Superclass is not specified in the Subclass, and the
916 Qualifier is defined in the Superclass with a TOSUBCLASS attribute value of
917 true, then the Qualifier MUST still be present in the resulting modified
918 Subclass (it is not possible to remove a propagated Qualifier from a
919 Subclass).
920 Any Qualifier propagated from the Superclass cannot be modified in the
921 Subclass if the OVERRIDABLE attribute of that Qualifier was set to false in
922 the Superclass. It is a Client error to specify such a Qualifier in the
923 ModifiedClass with a different definition to that in the Superclass (where
924 definition encompasses the name, type and flavor attribute settings of the
925 mike 1.1 <QUALIFIER> element, and the value of the Qualifier).
926 Any Qualifiers defined in the Superclass with a TOSUBCLASS attribute value
927 of false MUST NOT be propagated to the Subclass.
928 If successful, the specified Class MUST have been updated by the CIM Server.
929 The request to modify the Class MUST fail if the Server cannot update any
930 existing Subclasses or Instances of that Class in a consistent manner.
931 If unsuccessful, one of the following status codes MUST be returned by this
932 method, where the first applicable error in the list (starting with the first
933 element of the list, and working down) is the error returned. Any additional
934 method-specific interpretation of the error in is given in parentheses.
935 CIM_ERR_ACCESS_DENIED
936 CIM_ERR_NOT_SUPPORTED
937 CIM_ERR_INVALID_NAMESPACE
938 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
939 otherwise incorrect parameters)
940 CIM_ERR_NOT_FOUND (the CIM Class does not exist)
941 CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a non-existent or
942 incorrect superclass)
943 CIM_ERR_CLASS_HAS_CHILDREN (the modification could not be performed because it
944 was not possible to update the subclasses of the Class in a consistent
945 fashion)
946 mike 1.1 CIM_ERR_CLASS_HAS_INSTANCES (the modification could not be performed because
947 it was not possible to update the instances of the Class in a consistent
948 fashion)
949 CIM_ERR_FAILED (some other unspecified error occurred)
950 Back to contents
951 2.4.8. ModifyInstance
952 This operation is used to modify an existing CIM Instance in the target
953 Namespace. The Instance MUST already exist.
954 ModifyInstance
955 void ModifyInstance (
956 [IN] <namedInstance> ModifiedInstance
957 )
958
959 The ModifiedInstance input parameter identifies the name of the Instance to be
960 modified, and defines the set of changes (which MUST be correct amendments to
961 the Instance as defined by the CIM Specification [1]) to be made to the current
962 Instance definition.
963 In processing the modifcation of the Instance, the following rules MUST be
964 conformed to by the CIM Server:
965 Any CLASSORIGIN and PROPAGATED attributes in the ModifiedInstance MUST be
966 ignored by the Server.
967 mike 1.1 The Class MUST exist, and the Client MUST NOT change the name of the Class in
968 the modified Instance. The Server MUST ensure that:
969 Any Qualifiers in the Instance not defined in the Class are created as new
970 elements of the Instance.
971 All Properties of the Instance preserve their CLASSORIGIN attribute value
972 from that defined in the Class.
973 Any Qualifier previously defined in the Instance but not defined in the
974 Class, and which is not present in the ModifiedInstance parameter, is
975 removed from the Instance.
976 If a Property is specified in the ModifiedInstance parameter, the value
977 assigned to that property therein (including NULL) becomes the value of the
978 property for the Instance. Note that it is a Client error to specify a
979 Property that does not belong to the Class.
980 If a Property of the Class is not specified in the Instance, then that
981 Property is inherited without modification by the Instance (so that any
982 previous changes to that Property in the Instance are lost).
983 Any Qualifiers defined in the Class with a TOINSTANCE attribute value of
984 true appear in the Instance (it is not possible remove a propagated
985 Qualifier from an Instance. Qualifiers in the Class with a TOINSTANCE
986 attribute value of false MUST NOT be propagated to the Instance.
987 Any Qualifier propagated from the Class cannot be modified by the Server if
988 mike 1.1 the OVERRIDABLE attribute of that Qualifier was set to false in the Class.
989 It is a Client error to specify such a Qualifier in the ModifiedInstance
990 with a different definition to that in the Class (where definition
991 encompasses the name, type and flavor attribute settings of the <QUALIFIER>
992 element, and the value of the Qualifier).
993 Any Qualifier propagated from the Class cannot be modified in the Instance
994 if the OVERRIDABLE attribute of that Qualifier was set to false in the
995 Class. It is a Client error to specify such a Qualifier in the
996 ModifiedInstance with a different definition to that in the Class (where
997 definition encompasses the name, type and flavor attribute settings of the
998 <QUALIFIER> element, and the value of the Qualifier).
999 If successful, the specified Instance MUST have been updated by the CIM Server.
1000
1001 If unsuccessful, one of the following status codes MUST be returned by this
1002 method, where the first applicable error in the list (starting with the first
1003 element of the list, and working down) is the error returned. Any additional
1004 method-specific interpretation of the error in is given in parentheses.
1005 CIM_ERR_ACCESS_DENIED
1006 CIM_ERR_NOT_SUPPORTED
1007 CIM_ERR_INVALID_NAMESPACE
1008 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1009 mike 1.1 otherwise incorrect parameters)
1010 CIM_ERR_INVALID_CLASS (the CIM Class of which this is to be a new Instance
1011 does not exist)
1012 CIM_ERR_NOT_FOUND (the CIM Instance does not exist)
1013 CIM_ERR_FAILED (some other unspecified error occurred)
1014 Back to contents
1015 2.4.9. EnumerateClasses
1016 This operation is used to enumerate subclasses of a CIM Class in the target
1017 Namespace.
1018 EnumerateClasses
1019 <class>* EnumerateClasses (
1020 [IN,OPTIONAL,NULL] <className> ClassName=NULL,
1021 [IN,OPTIONAL] boolean DeepInheritance = false,
1022 [IN,OPTIONAL] boolean LocalOnly = true,
1023 [IN,OPTIONAL] boolean IncludeQualifiers = true,
1024 [IN,OPTIONAL] boolean IncludeClassOrigin = false
1025 )
1026
1027 The ClassName input parameter defines the Class that is the basis for the
1028 enumeration.
1029 If the DeepInheritance input parameter is true, this specifies that all
1030 mike 1.1 subclasses of the specified Class should be returned (if the ClassName input
1031 parameter is absent, this implies that all Classes in the target Namespace
1032 should be returned). If false, only immediate child subclasses are returned (if
1033 the ClassName input parameter is NULL, this implies that all base Classes in the
1034 target Namespace should be returned).
1035 If the LocalOnly input parameter is true, it specifies that, for each returned
1036 Class, only elements (properties, methods and qualifiers) overriden within the
1037 definition of that Class are included [1]. If false, all elements are returned.
1038 This parameter therefore effects a CIM Server-side mechanism to filter certain
1039 elements of the returned object based on whether or not they have been
1040 propagated from the parent Class (as defined by the PROPAGATED attribute).
1041 If the IncludeQualifiers input parameter is true, this specifies that all
1042 Qualifiers for each Class (including Qualifiers on the Class and on any returned
1043 Properties, Methods or Method Parameters) MUST be included as <QUALIFIER>
1044 elements in the response. If false no <QUALIFIER> elements are present in each
1045 returned Class.
1046 If the IncludeClassOrigin input parameter is true, this specifies that the
1047 CLASSORIGIN attribute MUST be present on all appropriate elements in each
1048 returned Class. If false, no CLASSORIGIN attributes are present in each returned
1049 Class.
1050 If successful, the method returns zero or more Classes that meet the required
1051 mike 1.1 criteria.
1052 If unsuccessful, one of the following status codes MUST be returned by this
1053 method, where the first applicable error in the list (starting with the first
1054 element of the list, and working down) is the error returned. Any additional
1055 method-specific interpretation of the error in is given in parentheses.
1056 CIM_ERR_ACCESS_DENIED
1057 CIM_ERR_NOT_SUPPORTED
1058 CIM_ERR_INVALID_NAMESPACE
1059 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1060 otherwise incorrect parameters)
1061 CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this enumeration
1062 does not exist)
1063 CIM_ERR_FAILED (some other unspecified error occurred)
1064 Back to contents
1065 2.4.10. EnumerateClassNames
1066 This operation is used to enumerate the names of subclasses of a CIM Class in
1067 the target Namespace.
1068 EnumerateClassNames
1069 <className>* EnumerateClassNames (
1070 [IN,OPTIONAL,NULL] <className> ClassName = NULL,
1071 [IN,OPTIONAL] boolean DeepInheritance = false
1072 mike 1.1 )
1073
1074 The ClassName input parameter defines the Class that is the basis for the
1075 enumeration.
1076 If the DeepInheritance input parameter is true, this specifies that the names of
1077 all subclasses of the specified Class should be returned (if the ClassName input
1078 parameter is absent, this implies that the names of all Classes in the target
1079 Namespace should be returned). If false, only the names of immediate child
1080 subclasses are returned (if the ClassName input parameter is NULL, this implies
1081 that the names of all base Classes in the target Namespace should be returned).
1082 If successful, the method returns zero or more names of Classes that meet the
1083 requested criteria.
1084 If unsuccessful, one of the following status codes MUST be returned by this
1085 method, where the first applicable error in the list (starting with the first
1086 element of the list, and working down) is the error returned. Any additional
1087 method-specific interpretation of the error in is given in parentheses.
1088 CIM_ERR_ACCESS_DENIED
1089 CIM_ERR_NOT_SUPPORTED
1090 CIM_ERR_INVALID_NAMESPACE
1091 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1092 otherwise incorrect parameters)
1093 mike 1.1 CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this enumeration
1094 does not exist)
1095 CIM_ERR_FAILED (some other unspecified error occurred)
1096 Back to contents
1097 2.4.11. EnumerateInstances
1098 This operation is used to enumerate instances of a CIM Class in the target
1099 Namespace.
1100 EnumerateInstances
1101 <namedInstance>* EnumerateInstances (
1102 [IN] <className> ClassName,
1103 [IN,OPTIONAL] boolean LocalOnly = true,
1104 [IN,OPTIONAL] boolean DeepInheritance = true,
1105 [IN,OPTIONAL] boolean IncludeQualifiers = false,
1106 [IN,OPTIONAL] boolean IncludeClassOrigin = false,
1107 [IN,OPTIONAL,NULL] string PropertyList [] = NULL
1108 )
1109
1110 The ClassName input parameter defines the Class that is the basis for the
1111 enumeration.
1112 If the LocalOnly input parameter is true, this specifies that, for each returned
1113 Instance, only elements (properties and qualifiers) overriden within the
1114 mike 1.1 definition of that Instance are included [1]. If false, all elements are
1115 returned. This parameter therefore effects a CIM Server-side mechanism to
1116 filter certain elements of the returned object based on whether or not they have
1117 been propagated from the parent Class (as defined by the PROPAGATED attribute).
1118 If the DeepInheritance input parameter is true, this specifies that, for each
1119 returned Instance of the Class, all properties of the Instance MUST be present
1120 (subject to constraints imposed by the other parameters), including any which
1121 were added by subclassing the specified Class. If false, each returned Instance
1122 includes only properties defined for the specified Class.
1123 If the IncludeQualifiers input parameter is true, this specifies that all
1124 Qualifiers for each Instance (including Qualifiers on the Instance and on any
1125 returned Properties) MUST be included as <QUALIFIER> elements in the response.
1126 If false no <QUALIFIER> elements are present in each returned Instance.
1127 If the IncludeClassOrigin input parameter is true, this specifies that the
1128 CLASSORIGIN attribute MUST be present on all appropriate elements in each
1129 returned Instance. If false, no CLASSORIGIN attributes are present in each
1130 returned Instance.
1131 If the PropertyList input parameter is not NULL, the members of the array define
1132 one or more Property names. Each returned Instance MUST NOT include elements
1133 for any Properties missing from this list. Note that if LocalOnly is specified
1134 as true (or DeepInheritance is specified as false) this acts as an additional
1135 mike 1.1 filter on the set of Properties returned (for example, if Property A is included
1136 in the PropertyList but LocalOnly is set to true and A is not local to a
1137 returned Instance, then it will not be included in that Instance). If the
1138 PropertyList input parameter is an empty array this signifies that no Properties
1139 are included in each returned Instance. If the PropertyList input parameter is
1140 NULL this specifies that all Properties (subject to the conditions expressed by
1141 the other parameters) are included in each returned Instance.
1142 If the PropertyList contains duplicate elements, the Server MUST ignore the
1143 duplicates but otherwise process the request normally. If the PropertyList
1144 contains elements which are invalid Property names for any target Instance, the
1145 Server MUST ignore such entries but otherwise process the request normally.
1146 If successful, the method returns zero or more named Instances that meet the
1147 required criteria.
1148 If unsuccessful, one of the following status codes MUST be returned by this
1149 method, where the first applicable error in the list (starting with the first
1150 element of the list, and working down) is the error returned. Any additional
1151 method-specific interpretation of the error in is given in parentheses.
1152 CIM_ERR_ACCESS_DENIED
1153 CIM_ERR_NOT_SUPPORTED
1154 CIM_ERR_INVALID_NAMESPACE
1155 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1156 mike 1.1 otherwise incorrect parameters)
1157 CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this enumeration
1158 does not exist)
1159 CIM_ERR_FAILED (some other unspecified error occurred)
1160 Back to contents
1161 2.4.12. EnumerateInstanceNames
1162 This operation is used to enumerate the names (model paths) of the instances of
1163 a CIM Class in the target Namespace.
1164 EnumerateInstanceNames
1165 <instanceName>* EnumerateInstanceNames (
1166 [IN] <className> ClassName
1167 )
1168
1169 The ClassName input parameter defines the Class that is the basis for the
1170 enumeration.
1171 If successful, the method returns zero or more names of Instances (model paths)
1172 that meet the requsted criteria.
1173 If unsuccessful, one of the following status codes MUST be returned by this
1174 method, where the first applicable error in the list (starting with the first
1175 element of the list, and working down) is the error returned. Any additional
1176 method-specific interpretation of the error in is given in parentheses.
1177 mike 1.1 CIM_ERR_ACCESS_DENIED
1178 CIM_ERR_NOT_SUPPORTED
1179 CIM_ERR_INVALID_NAMESPACE
1180 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1181 otherwise incorrect parameters)
1182 CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this enumeration
1183 does not exist)
1184 CIM_ERR_FAILED (some other unspecified error occurred)
1185 Back to contents
1186 2.4.13. ExecQuery
1187 This operation is used to execute a query against the target Namespace.
1188 ExecQuery
1189 <object>* ExecQuery (
1190 [IN] string QueryLanguage,
1191 [IN] string Query
1192 )
1193
1194 The QueryLanguage input parameter defines the query language in which the Query
1195 parameter is expressed.
1196 The Query input parameter defines the query to be executed.
1197 Neither the Query language nor the format of the Query are defined by this
1198 mike 1.1 specification. It is anticipated that Query languages will be submitted to the
1199 DMTF as separate proposals.
1200 A mechanism whereby CIM Servers can declare which query languages they support
1201 (if any) is defined in Determining CIM Server Capabilities.
1202 If successful, the method returns zero or more CIM Classes or Instances that
1203 correspond to the results set of the query.
1204 If unsuccessful, one of the following status codes MUST be returned by this
1205 method, where the first applicable error in the list (starting with the first
1206 element of the list, and working down) is the error returned. Any additional
1207 method-specific interpretation of the error in is given in parentheses.
1208 CIM_ERR_ACCESS_DENIED
1209 CIM_ERR_NOT_SUPPORTED
1210 CIM_ERR_INVALID_NAMESPACE
1211 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1212 otherwise incorrect parameters)
1213 CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED (the requested query language is not
1214 recognized)
1215 CIM_ERR_INVALID_QUERY (the query is not a valid query in the specified query
1216 language)
1217 CIM_ERR_FAILED (some other unspecified error occurred)
1218 Back to contents
1219 mike 1.1 2.4.14. Associators
1220 This operation is used to enumerate CIM Objects (Classes or Instances) that are
1221 associated to a particular source CIM Object.
1222 Associators
1223 <objectWithPath>* Associators (
1224 [IN] <objectName> ObjectName,
1225 [IN,OPTIONAL,NULL] <className> AssocClass = NULL,
1226 [IN,OPTIONAL,NULL] <className> ResultClass = NULL,
1227 [IN,OPTIONAL,NULL] string Role = NULL,
1228 [IN,OPTIONAL,NULL] string ResultRole = NULL,
1229 [IN,OPTIONAL] boolean IncludeQualifiers = false,
1230 [IN,OPTIONAL] boolean IncludeClassOrigin = false,
1231 [IN,OPTIONAL,NULL] string PropertyList [] = NULL
1232 )
1233
1234 The ObjectName input parameter defines the source CIM Object whose associated
1235 Objects are to be returned. This may be either a Class name or Instance name
1236 (model path).
1237 The AssocClass input parameter, if not NULL, MUST be a valid CIM Association
1238 Class name. It acts as a filter on the returned set of Objects by mandating that
1239 each returned Object MUST be associated to the source Object via an Instance of
1240 mike 1.1 this Class or one of its subclasses.
1241 The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It
1242 acts as a filter on the returned set of Objects by mandating that each returned
1243 Object MUST be either an Instance of this Class (or one of its subclasses) or be
1244 this Class (or one of its subclasses).
1245 The Role input parameter, if not NULL, MUST be a valid Property name. It acts as
1246 a filter on the returned set of Objects by mandating that each returned Object
1247 MUST be associated to the source Object via an Association in which the source
1248 Object plays the specified role (i.e. the name of the Property in the
1249 Association Class that refers to the source Object MUST match the value of this
1250 parameter).
1251 The ResultRole input parameter, if not NULL, MUST be a valid Property name. It
1252 acts as a filter on the returned set of Objects by mandating that each returned
1253 Object MUST be associated to the source Object via an Association in which the
1254 returned Object plays the specified role (i.e. the name of the Property in the
1255 Association Class that refers to the returned Object MUST match the value of
1256 this parameter).
1257 If the IncludeQualifiers input parameter is true, this specifies that all
1258 Qualifiers for each Object (including Qualifiers on the Object and on any
1259 returned Properties) MUST be included as <QUALIFIER> elements in the response.
1260 If false no <QUALIFIER> elements are present in each returned Object.
1261 mike 1.1 If the IncludeClassOrigin input parameter is true, this specifies that the
1262 CLASSORIGIN attribute MUST be present on all appropriate elements in each
1263 returned Object. If false, no CLASSORIGIN attributes are present in each
1264 returned Object.
1265 If the PropertyList input parameter is not NULL, the members of the array define
1266 one or more Property names. Each returned Object MUST NOT include elements for
1267 any Properties missing from this list. Note that if LocalOnly is specified as
1268 true (or DeepInheritance is specified as false) this acts as an additional
1269 filter on the set of Properties returned (for example, if Property A is included
1270 in the PropertyList but LocalOnly is set to true and A is not local to a
1271 returned Instance, then it will not be included in that Instance). If the
1272 PropertyList input parameter is an empty array this signifies that no Properties
1273 are included in each returned Object. If the PropertyList input parameter is
1274 NULL this specifies that all Properties (subject to the conditions expressed by
1275 the other parameters) are included in each returned Object.
1276 If the PropertyList contains duplicate elements, the Server MUST ignore the
1277 duplicates but otherwise process the request normally. If the PropertyList
1278 contains elements which are invalid Property names for any target Object, the
1279 Server MUST ignore such entries but otherwise process the request normally.
1280 Clients SHOULD NOT explicitly specify properties in the PropertyList parameter
1281 unless they have specified a non-NULL value for the ResultClass parameter.
1282 mike 1.1 If successful, the method returns zero or more CIM Classes or Instances meeting
1283 the requested criteria. Since it is possible for CIM Objects from different
1284 hosts or namespaces to be associated, each returned Object includes location
1285 information.
1286 If unsuccessful, one of the following status codes MUST be returned by this
1287 method, where the first applicable error in the list (starting with the first
1288 element of the list, and working down) is the error returned. Any additional
1289 method-specific interpretation of the error in is given in parentheses.
1290 CIM_ERR_ACCESS_DENIED
1291 CIM_ERR_NOT_SUPPORTED
1292 CIM_ERR_INVALID_NAMESPACE
1293 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1294 otherwise incorrect parameters)
1295 CIM_ERR_FAILED (some other unspecified error occurred)
1296 Back to contents
1297 2.4.15. AssociatorNames
1298 This operation is used to enumerate the names of CIM Objects (Classes or
1299 Instances) that are associated to a particular source CIM Object.
1300 AssociatorNames
1301 <objectPath>* AssociatorNames (
1302 [IN] <objectName> ObjectName,
1303 mike 1.1 [IN,OPTIONAL,NULL] <className> AssocClass = NULL,
1304 [IN,OPTIONAL,NULL] <className> ResultClass = NULL,
1305 [IN,OPTIONAL,NULL] string Role = NULL,
1306 [IN,OPTIONAL,NULL] string ResultRole = NULL
1307 )
1308
1309 The ObjectName input parameter defines the source CIM Object whose associated
1310 names are to be returned. This is either a Class name or Instance name (model
1311 path).
1312 The AssocClass input parameter, if not NULL, MUST be a valid CIM Association
1313 Class name. It acts as a filter on the returned set of names by mandating that
1314 each returned name identifies an Object that MUST be associated to the source
1315 Object via an Instance of this Class or one of its subclasses.
1316 The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It
1317 acts as a filter on the returned set of names by mandating that each returned
1318 name identifies an Object that MUST be either an Instance of this Class (or one
1319 of its subclasses) or be this Class (or one of its subclasses).
1320 The Role input parameter, if not NULL, MUST be a valid Property name. It acts as
1321 a filter on the returned set of names by mandating that each returned name
1322 identifies an Object that MUST be associated to the source Object via an
1323 Association in which the source Object plays the specified role (i.e. the name
1324 mike 1.1 of the Property in the Association Class that refers to the source Object MUST
1325 match the value of this parameter).
1326 The ResultRole input parameter, if not NULL, MUST be a valid Property name. It
1327 acts as a filter on the returned set of names by mandating that each returned
1328 name identifies an Object that MUST be associated to the source Object via an
1329 Association in which the named returned Object plays the specified role (i.e.
1330 the name of the Property in the Association Class that refers to the returned
1331 Object MUST match the value of this parameter).
1332 If successful, the method returns zero or more full CIM Class paths or Instance
1333 paths of Objects meeting the requested criteria. Since it is possible for CIM
1334 Objects from different hosts or namespaces to be associated, each returned path
1335 is an absolute path that includes host and namespace information.
1336 If unsuccessful, one of the following status codes MUST be returned by this
1337 method, where the first applicable error in the list (starting with the first
1338 element of the list, and working down) is the error returned. Any additional
1339 method-specific interpretation of the error in is given in parentheses.
1340 CIM_ERR_ACCESS_DENIED
1341 CIM_ERR_NOT_SUPPORTED
1342 CIM_ERR_INVALID_NAMESPACE
1343 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1344 otherwise incorrect parameters)
1345 mike 1.1 CIM_ERR_FAILED (some other unspecified error occurred)
1346 Back to contents
1347 2.4.16. References
1348 This operation is used to enumerate the association objects that refer to a
1349 particular target CIM Object (Class or Instance).
1350 References
1351 <objectWithPath>* References (
1352 [IN] <objectName> ObjectName,
1353 [IN,OPTIONAL,NULL] <className> ResultClass = NULL,
1354 [IN,OPTIONAL,NULL] string Role = NULL,
1355 [IN,OPTIONAL] boolean IncludeQualifiers = false,
1356 [IN,OPTIONAL] boolean IncludeClassOrigin = false,
1357 [IN,OPTIONAL,NULL] string PropertyList [] = NULL
1358 )
1359
1360 The ObjectName input parameter defines the target CIM Object whose referring
1361 Objects are to be returned. This is either a Class name or Instance name (model
1362 path).
1363 The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It
1364 acts as a filter on the returned set of Objects by mandating that each returned
1365 Object MUST be an Instance of this Class (or one of its subclasses), or this
1366 mike 1.1 Class (or one of its subclasses).
1367 The Role input parameter, if not NULL, MUST be a valid Property name. It acts as
1368 a filter on the returned set of Objects by mandating that each returned Objects
1369 MUST refer to the target Object via a Property whose name matches the value of
1370 this parameter.
1371 If the IncludeQualifiers input parameter is true, this specifies that all
1372 Qualifiers for each Object (including Qualifiers on the Object and on any
1373 returned Properties) MUST be included as <QUALIFIER> elements in the response.
1374 If false no <QUALIFIER> elements are present in each returned Object.
1375 If the IncludeClassOrigin input parameter is true, this specifies that the
1376 CLASSORIGIN attribute MUST be present on all appropriate elements in each
1377 returned Object. If false, no CLASSORIGIN attributes are present in each
1378 returned Object.
1379 If the PropertyList input parameter is not NULL, the members of the array define
1380 one or more Property names. Each returned Object MUST NOT include elements for
1381 any Properties missing from this list. Note that if LocalOnly is specified as
1382 true (or DeepInheritance is specified as false) this acts as an additional
1383 filter on the set of Properties returned (for example, if Property A is included
1384 in the PropertyList but LocalOnly is set to true and A is not local to a
1385 returned Instance, then it will not be included in that Instance). If the
1386 PropertyList input parameter is an empty array this signifies that no Properties
1387 mike 1.1 are included in each returned Object. If the PropertyList input parameter is
1388 NULL this specifies that all Properties (subject to the conditions expressed by
1389 the other parameters) are included in each returned Object.
1390 If the PropertyList contains duplicate elements, the Server MUST ignore the
1391 duplicates but otherwise process the request normally. If the PropertyList
1392 contains elements which are invalid Property names for any target Object, the
1393 Server MUST ignore such entries but otherwise process the request normally.
1394 Clients SHOULD NOT explicitly specify properties in the PropertyList parameter
1395 unless they have specified a non-NULL value for the ResultClass parameter.
1396 If successful, the method returns zero or more CIM Classes or Instances meeting
1397 the requested criteria. Since it is possible for CIM Objects from different
1398 hosts or namespaces to be associated, each returned Object includes location
1399 information.
1400 If unsuccessful, one of the following status codes MUST be returned by this
1401 method, where the first applicable error in the list (starting with the first
1402 element of the list, and working down) is the error returned. Any additional
1403 method-specific interpretation of the error in is given in parentheses.
1404 CIM_ERR_ACCESS_DENIED
1405 CIM_ERR_NOT_SUPPORTED
1406 CIM_ERR_INVALID_NAMESPACE
1407 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1408 mike 1.1 otherwise incorrect parameters)
1409 CIM_ERR_FAILED (some other unspecified error occurred)
1410 Back to contents
1411 2.4.17. ReferenceNames
1412 This operation is used to enumerate the association objects that refer to a
1413 particular target CIM Object (Class or Instance).
1414 ReferenceNames
1415 <objectPath>* ReferenceNames (
1416 [IN] <objectName> ObjectName,
1417 [IN,OPTIONAL,NULL] <className> ResultClass = NULL,
1418 [IN,OPTIONAL,NULL] string Role = NULL
1419 )
1420
1421 The ObjectName input parameter defines the target CIM Object whose referring
1422 object names are to be returned. It may be either a Class name or an Instance
1423 name (model path).
1424 The ResultClass input parameter, if not NULL, MUST be a valid CIM Class name. It
1425 acts as a filter on the returned set of Object Names by mandating that each
1426 returned Object Name MUST identify an Instance of this Class (or one of its
1427 subclasses), or this Class (or one of its subclasses).
1428 The Role input parameter, if not NULL, MUST be a valid Property name. It acts as
1429 mike 1.1 a filter on the returned set of Object Names by mandating that each returned
1430 Object Name MUST identify an Object that refers to the target Instance via a
1431 Property whose name matches the value of this parameter.
1432 If successful, the method returns the names of zero or more full CIM Class paths
1433 or Instance paths of Objects meeting the requested criteria. Since it is
1434 possible for CIM Objects from different hosts or namespaces to be associated,
1435 each returned path is an absolute path that includes host and namespace
1436 information.
1437 If unsuccessful, one of the following status codes MUST be returned by this
1438 method, where the first applicable error in the list (starting with the first
1439 element of the list, and working down) is the error returned. Any additional
1440 method-specific interpretation of the error in is given in parentheses.
1441 CIM_ERR_ACCESS_DENIED
1442 CIM_ERR_NOT_SUPPORTED
1443 CIM_ERR_INVALID_NAMESPACE
1444 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1445 otherwise incorrect parameters)
1446 CIM_ERR_FAILED (some other unspecified error occurred)
1447 Back to contents
1448 2.4.18. GetProperty
1449 This operation is used to retrieve a single property value from a CIM Instance
1450 mike 1.1 in the target Namespace.
1451 GetProperty
1452 <propertyValue>? GetProperty (
1453 [IN] <instanceName> InstanceName,
1454 [IN] string PropertyName
1455 )
1456
1457 The InstanceName input parameter specifies the name of the Instance (model path)
1458 from which the Property value is requested.
1459 The PropertyName input parameter specifies the name of the Property whose value
1460 is to be returned.
1461 If successful, the return value specifies the value of the requested Property.
1462 If the value is NULL then no element is returned.
1463 If unsuccessful, one of the following status codes MUST be returned by this
1464 method, where the first applicable error in the list (starting with the first
1465 element of the list, and working down) is the error returned. Any additional
1466 method-specific interpretation of the error in is given in parentheses.
1467 CIM_ERR_ACCESS_DENIED
1468 CIM_ERR_INVALID_NAMESPACE
1469 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1470 otherwise incorrect parameters)
1471 mike 1.1 CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
1472 namespace)
1473 CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested CIM Instance
1474 does not exist in the specified namespace)
1475 CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the requested
1476 Property does not)
1477 CIM_ERR_FAILED (some other unspecified error occurred)
1478 Back to contents
1479 2.4.19. SetProperty
1480 This operation is used to set a single property value in a CIM Instance in the
1481 target Namespace.
1482 SetProperty
1483 void SetProperty (
1484 [IN] <instanceName> InstanceName,
1485 [IN] string PropertyName,
1486 [IN,OPTIONAL,NULL] <propertyValue> NewValue = NULL
1487 )
1488
1489 The InstanceName input parameter specifies the name of the Instance (model path)
1490 for which the Property value is to be updated.
1491 The PropertyName input parameter specifies the name of the Property whose value
1492 mike 1.1 is to be updated.
1493 The NewValue input parameter specifies the new value for the Property (which may
1494 be NULL).
1495 If unsuccessful, one of the following status codes MUST be returned by this
1496 method, where the first applicable error in the list (starting with the first
1497 element of the list, and working down) is the error returned. Any additional
1498 method-specific interpretation of the error in is given in parentheses.
1499 CIM_ERR_ACCESS_DENIED
1500 CIM_ERR_NOT_SUPPORTED
1501 CIM_ERR_INVALID_NAMESPACE
1502 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1503 otherwise incorrect parameters)
1504 CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
1505 namespace)
1506 CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested CIM Instance
1507 does not exist in the specified namespace)
1508 CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the requested
1509 Property does not)
1510 CIM_ERR_TYPE_MISMATCH (the supplied value is incompatible with the type of the
1511 Property)
1512 CIM_ERR_FAILED (some other unspecified error occurred)
1513 mike 1.1 Back to contents
1514 2.4.20. GetQualifier
1515 This operation is used to retrieve a single Qualifier declaration from the
1516 target Namespace.
1517 GetQualifier
1518 <qualifierDecl> GetQualifier (
1519 [IN] string QualifierName
1520 )
1521
1522 The QualifierName input parameter identifies the Qualifier whose declaration to
1523 be retrieved.
1524 If successful, the method returns the Qualifier declaration for the named
1525 Qualifier.
1526 If unsuccessful, one of the following status codes MUST be returned by this
1527 method, where the first applicable error in the list (starting with the first
1528 element of the list, and working down) is the error returned. Any additional
1529 method-specific interpretation of the error in is given in parentheses.
1530 CIM_ERR_ACCESS_DENIED
1531 CIM_ERR_NOT_SUPPORTED
1532 CIM_ERR_INVALID_NAMESPACE
1533 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1534 mike 1.1 otherwise incorrect parameters)
1535 CIM_ERR_NOT_FOUND (the requested Qualifier declaration did not exist)
1536 CIM_ERR_FAILED (some other unspecified error occurred)
1537 Back to contents
1538 2.4.21. SetQualifier
1539 This operation is used to create or update a single Qualifier declaration in the
1540 target Namespace. If the Qualifier declaration already exists it is
1541 overwritten.
1542 SetQualifier
1543 void SetQualifier (
1544 [IN] <qualifierDecl> QualifierDeclaration
1545 )
1546
1547 The QualifierDeclaration input parameter defines the Qualifier Declaration to be
1548 added to the Namespace.
1549 If successful, the Qualifier declaration MUST have been added to the target
1550 Namespace. If a Qualifier declaration with the same Qualifier name already
1551 existed, then it MUST have been replaced by the new declaration.
1552 If unsuccessful, one of the following status codes MUST be returned by this
1553 method, where the first applicable error in the list (starting with the first
1554 element of the list, and working down) is the error returned. Any additional
1555 mike 1.1 method-specific interpretation of the error in is given in parentheses.
1556 CIM_ERR_ACCESS_DENIED
1557 CIM_ERR_NOT_SUPPORTED
1558 CIM_ERR_INVALID_NAMESPACE
1559 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1560 otherwise incorrect parameters)
1561 CIM_ERR_FAILED (some other unspecified error occurred)
1562 Back to contents
1563 2.4.22. DeleteQualifier
1564 This operation is used to delete a single Qualifier declaration from the target
1565 Namespace.
1566 DeleteQualifier
1567 void DeleteQualifier (
1568 [IN] string QualifierName
1569 )
1570
1571 The QualifierName input parameter identifies the Qualifier whose declaration to
1572 be deleted.
1573 If successful, the specified Qualifier declaration MUST have been deleted from
1574 the Namespace.
1575 If unsuccessful, one of the following status codes MUST be returned by this
1576 mike 1.1 method, where the first applicable error in the list (starting with the first
1577 element of the list, and working down) is the error returned. Any additional
1578 method-specific interpretation of the error in is given in parentheses.
1579 CIM_ERR_ACCESS_DENIED
1580 CIM_ERR_NOT_SUPPORTED
1581 CIM_ERR_INVALID_NAMESPACE
1582 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1583 otherwise incorrect parameters)
1584 CIM_ERR_NOT_FOUND (the requested Qualifier declaration did not exist)
1585 CIM_ERR_FAILED (some other unspecified error occurred)
1586 Back to contents
1587 2.4.23. EnumerateQualifiers
1588 This operation is used to enumerate Qualifier declarations from the target
1589 Namespace.
1590 EnumerateQualifiers
1591 <qualifierDecl>* EnumerateQualifiers (
1592 )
1593
1594 If successful, the method returns zero or more Qualifier declarations.
1595 If unsuccessful, one of the following status codes MUST be returned by this
1596 method, where the first applicable error in the list (starting with the first
1597 mike 1.1 element of the list, and working down) is the error returned. Any additional
1598 method-specific interpretation of the error in is given in parentheses.
1599 CIM_ERR_ACCESS_DENIED
1600 CIM_ERR_NOT_SUPPORTED
1601 CIM_ERR_INVALID_NAMESPACE
1602 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1603 otherwise incorrect parameters)
1604 CIM_ERR_FAILED (some other unspecified error occurred)
1605 Back to contents
1606 2.5. Namespace Manipulation
1607 There are no intrinsic methods defined specifically for the purpose of
1608 manipulating CIM Namespaces. However, the modelling of a CIM Namespace using the
1609 class __Namespace, together with the requirement that the root Namespace MUST be
1610 supported by all CIM Servers, implies that all Namespace operations can be
1611 supported.
1612 For example:
1613 Enumeration of all child Namespaces of a particular Namespace is realized by
1614 calling the intrinsic method EnumerateInstanceNames against the parent
1615 Namespace, specifying a value for the ClassName parameter of __Namespace.
1616 Creation of a child Namespace is realized by calling the intrinsic method
1617 CreateInstance against the parent Namespace, specifying a value for the
1618 mike 1.1 NewInstance parameter which defines a valid instance of the class __Namespace
1619 and whose Name property is the desired name of the new Namespace.
1620 2.6. Functional Profiles
1621 This section partitions the intrinsic methods into functional groups for the
1622 purpose of establishing conformance.
1623 Support for a particular group does not guarantee that all invocations of any
1624 method in that group will succeed. Rather, the exclusion of a group is a
1625 declaration that any attempt to call a method in that group will always return
1626 CIM_ERR_NOT_SUPPORTED.
1627 Mechanisms by which a CIM Server may declare the functional groups that it
1628 supports are defined in the section on Determining CIM Server Capabilities.
1629 In order to limit the number of different profiles that may be supported by a
1630 CIM Server, each functional group has a dependency on another group (with the
1631 exception of the Basic Read functional group). If functional group G1 has a
1632 dependency on functional group G2, then a CIM Server which supports G1 MUST also
1633 support G2.
1634 The dependency relation is transitive, so that if G1 depends on G2, and G2
1635 depends on G3, then G1 depends on G3. It is also anti-symmetric, so that if G1
1636 depends on G2 then G2 cannot depend on G1.
1637 Using these rules, the table below defines a rooted directed tree of
1638 dependencies with the Basic Read dependency representing the root node.
1639 mike 1.1 For example, a CIM Server which supports the Schema Manipulation functional
1640 group MUST also support the Instance Manipulation, Basic Write and Basic Read.
1641 Functional Group DependencyMethods
1642 Basic ReadnoneGetClass
1643 EnumerateClasses
1644 EnumerateClassNames
1645 GetInstance
1646 EnumerateInstances
1647 EnumerateInstanceNames
1648 GetProperty
1649 Basic WriteBasic ReadSetProperty
1650 Schema ManipulationInstance ManipulationCreateClass
1651 ModifyClass
1652 DeleteClass
1653 Instance ManipulationBasic WriteCreateInstance
1654 ModifyInstance
1655 DeleteInstance
1656 Association TraversalBasic ReadAssociators
1657 AssociatorNames
1658 References
1659 ReferenceNames
1660 mike 1.1 Query ExecutionBasic ReadExecQuery
1661 Qualifier DeclarationSchema ManipulationGetQualifier
1662 SetQualifier
1663 DeleteQualifier
1664 EnumerateQualifiers
1665
1666 Back to contents
1667 2.7. Extrinsic Method Invocation
1668 Any CIM Server is assumed to support extrinsic methods. Extrinsic methods are
1669 defined by the Schema supported by the Cim Server. If a Cim Server does not
1670 support extrinsic method invocations, it MUST (subject to the considerations
1671 described in the rest of this section) return the error code
1672 CIM_ERR_NOT_SUPPORTED to any request to execute an extrinsic method. This allows
1673 a CIM client to determine that all attempts to execute extrinsic methods will
1674 fail.
1675 If the Cim Server is unable to perform the extrinsic method invocation, one of
1676 the following status codes MUST be returned by the CimServer, where the first
1677 applicable error in the list (starting with the first element of the list, and
1678 working down) is the error returned. Any additional specific interpretation of
1679 the error is given in parentheses.
1680 CIM_ERR_ACCESS_DENIED
1681 mike 1.1 CIM_ERR_NOT_SUPPORTED (the CimServer does not support extrinsic method
1682 invocations)
1683 CIM_ERR_INVALID_NAMESPACE
1684 CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized or
1685 otherwise incorrect parameters)
1686 CIM_ERR_NOT_FOUND (the target CIM Class or instance does not exist in the
1687 specified namespace)
1688 CIM_ERR_METHOD_NOT_FOUND
1689 CIM_ERR_METHOD_NOT_AVAILABLE (the CimServer is unable to honor the invocation
1690 request)
1691 CIM_ERR_FAILED (some other unspecified error occurred)
1692 Back to contents
1693 3. Encapsulation of CIM Operations
1694 All CIM Operation requests MUST be made using either an HTTP M-POST or POST
1695 message, with the preferred mechanism being the use of M-POST. The use of other
1696 HTTP Methods to invoke CIM Operations is outside the scope of this
1697 specification.
1698 All CIM Operation responses are carried in the corresponding HTTP Response
1699 message to the M-POST or POST request.
1700 In the remainder of this document:
1701 the term CIM Operation Request is a convenient shorthand for an HTTP M-POST or
1702 mike 1.1 POST request message that includes an XML entity body which defines an
1703 Operation Request Message, and;
1704 the term CIM Operation Response is a convenient shorthand for an HTTP response
1705 message, issued in response to a CIM Operation Request, that includes an
1706 entity body which defines an Operation Response Message. Note that an HTTP
1707 response to a CIM Operation Request is not always a CIM Operation Response;
1708 for example a "505 HTTP Version Not Supported" response would not be a CIM
1709 Operation Response.
1710 Where it is necessary to distinguish requirements between the use of M-POST and
1711 POST, these will be explicitly defined.
1712 The extension mechanism used in this document is based on the HTTP Extension
1713 Framework [9]. A goal of the framework is to allow a decentralized naming
1714 mechanism whereby parties can introduce additional HTTP Headers without fear of
1715 conflicting interpretation of a given Header name.
1716 It is not the intention of this document to replicate information in that
1717 document concerning the required behavior of entities that implement this
1718 framework; suffice it to say that conforming CIM implementations of this
1719 specification protocol MUST abide by all requirements in that document.
1720 Back to contents
1721 3.1. CIM Clients and Servers
1722 The following definitions are used throughout the remainder of this document:
1723 mike 1.1 A CIM client is an HTTP client that issues CIM Operation Requests and receives
1724 and processes CIM Operation Responses.
1725 A CIM server is an an HTTP server that receives and processes CIM Operation
1726 Requests and issues CIM Operation Responses.
1727 An HTTP client/server MAY be capable of acting as both a CIM client and a CIM
1728 server.
1729 Back to contents
1730 3.2. Use of M-POST and POST
1731 A CIM client attempting a CIM Operation invocation conformant to this
1732 specification MUST first try the invocation using the HTTP method "M-POST".
1733 If the M-POST invocation fails with an HTTP status of "501 Not Implemented" or
1734 "510 Not Extended", then the client SHOULD retry the request using the HTTP
1735 method “POST” with the appropriate modifications (described in Naming of
1736 Extension Headers). The intention is that POST should only be used as a
1737 fallback mechanism in environments where firewalls or proxies do not yet have
1738 the ability to understand M-POST requests.
1739 If the M-POST invocation fails with an HTTP status of "405 Method Not
1740 Allowed", then the client SHOULD fail the request.
1741 For all other status codes the client MUST act in accordance with standard
1742 HTTP [6,7].
1743 This extended invocation mechanism allows Internet proxies & firewalls greater
1744 mike 1.1 filtering control and administrative flexibility over CIM Operation invocations.
1745 In the case of a client receiving a 501 or 510 status in response to an M-POST
1746 request, then in subsequent invocations to the same HTTP server, the client MAY
1747 omit the attempt at M-POST invocations for a suitable period, thus avoiding the
1748 need for an extra round trip on each and every method invocation. The details
1749 of the caching strategy employed by the client are outside of the scope of this
1750 specification.
1751 Given this algorithm, firewalls can if they wish effectively force the use of
1752 M-POST for CIM Operation invocations by prohibiting POST invocations containing
1753 the Extension Header CIMOperation.
1754 3.2.1. Use of the Ext Header
1755 If a CIM Server receives a valid M-POST request, and has fulfilled all mandatory
1756 extension header declarations in the request, then it MUST include in the
1757 response the "Ext" header defined by [9]. This must be protected by the
1758 appropriate Cache-Control directive.
1759 Back to contents
1760 3.3. Extension Headers Defined for CIM Operation Requests and Responses
1761 This section describes the extension headers used to specify CIM operational
1762 semantics in the HTTP Header of an M-POST or POST message.
1763 Any CIM Operation Request or CIM Operation Response MUST include the following
1764 CIM extension header:
1765 mike 1.1 CIMOperation
1766 Any CIM Operation Request MUST include one and only one of the following CIM
1767 extension header sets:
1768 CIMMethod and CIMObject, or
1769 CIMBatch
1770 An HTTP reponse with an error status code to a CIM Operation Request MAY include
1771 the following CIM extension header:
1772 CIMError
1773 All CIM Operation Requests and Responses MAY include the following CIM extension
1774 header:
1775 CIMProtocolVersion
1776 Back to contents
1777 3.3.1. Naming of Extension Headers
1778 In M-POST request messages (and their responses), CIM extension headers MUST be
1779 declared using the name space prefix allotted by the "Man" extension header (in
1780 accordance with [9]) that refers to the name space
1781 "http://www.dmtf.org/cim/mapping/http/v1.0".
1782 The full format of the "Man" header declaration for this specification is:
1783 Man = "Man" ":" "http://www.dmtf.org/cim/mapping/http/v1.0"
1784 ";" "ns" "=" header-prefix
1785 header-prefix = 2*DIGIT
1786 mike 1.1
1787 This header-prefix SHOULD be generated at random on a per-HTTP message basis,
1788 and SHOULD NOT necessarily be a specific number.
1789 In accordance with [9], all POST request messages (and their responses) MUST NOT
1790 include such a mandatory extension declaration. In POST request messages (and
1791 their responses), name space prefixes MUST NOT be used.
1792 Example 1
1793 Using M-POST:
1794 M-POST /cimom HTTP/1.1
1795 Man: http://www.dmtf.org./cim/mapping/http/v1.0 ; ns=23
1796 23-CIMOperation: MethodCall
1797 ...
1798
1799 Example 2
1800 Using POST:
1801 POST /cimom HTTP/1.1
1802 CIMOperation: MethodCall
1803 ...
1804
1805 Back to contents
1806 3.3.2. Encoding of CIM Element Names within HTTP Headers
1807 mike 1.1 CIM element (class, property, qualifier, method or method parameter) names are
1808 natively Unicode, and may use UCS-2 characters unsuitable for inclusion within
1809 an HTTP message header. In order to encode CIM element names represented in
1810 Unicode to values within HTTP Headers, the following mapping MUST be used:
1811 Encode the full Unicode CIM element name using UTF-8 [15], and then;
1812 Apply the standard URI [16, section 2] escaping mechanism to the resulting
1813 string to escape any characters that are unsafe within an HTTP Header, using
1814 the ""%" HEX HEX" convention).
1815 The token CIMIdentifier, where used in this document, represents a CIM element
1816 name to which this transformation has been applied.
1817 One characteristic of this mapping is that CIM elements that are named with an
1818 ASCII representation will appear in ASCII in the resultant URL.
1819 Examples
1820 CIM_LogicalElement is unchanged under this transformation
1821 The class named using the UCS-2 sequence representing the Hangul
1822 characters for the Korean word "hangugo" (D55C, AD6D, C5B4) becomes
1823 %ED%95%9C%EA%B5%AD%EC%96%B4=10
1824 after UTF-8 transformation and escaping all characters with their % HEX
1825 HEX equivalent.
1826
1827 Back to contents
1828 mike 1.1 3.3.3. Encoding of CIM Object Paths within HTTP Headers
1829 This section describes the mapping that MUST be applied in order to represent
1830 CIM object paths, as described within an Operation Request Message using the
1831 <LOCALNAMESPACEPATH>, <LOCALCLASSPATH> or <LOCALINSTANCEPATH> elements, in a
1832 format that is safe for representation within an HTTP header.
1833 If the element to be transformed is a <LOCALNAMESPACEPATH> element, the
1834 algorithm is as follows:
1835 For the first NAMESPACE subelement, output the textual content of that
1836 element.
1837 For each subsequent NAMESPACE subelement, output the forward slash character
1838 (/) followed by the textual content of that NAMESPACE element.
1839 If the element to be transformed is a <LOCALCLASSPATH> element, the algorithm is
1840 as follows:
1841 Transform the <LOCALNAMESPACEPATH> subelement using the rules described above,
1842 and output a colon character (:).
1843 Output the value of the NAME attribute of the <CLASSNAME> subelement.
1844 If the element to be transformed is an <LOCALINSTANCEPATH> element, the
1845 algorithm is as follows:
1846 Transform the <LOCALNAMESPACEPATH> subelement using the rules described above,
1847 and output a colon character (:).
1848 Output the value of the CLASSNAME attribute of the <INSTANCENAME> subelement.
1849 mike 1.1 If there is at least one <KEYBINDING> subelement under the <INSTANCENAME>
1850 subelement, then for each such subelement:
1851 Output a period character (.) if this is the first <KEYBINDING> subelement,
1852 and a comma (,) otherwise.
1853 Output the value of the NAME attribute, followed by an equals character (=).
1854
1855 If there is a <KEYVALUE> subelement, output the textual element content of
1856 that element, subject to the following transformation:
1857 If the VALUETYPE attribute is numeric or boolean, the output is identical
1858 to the content of the element.
1859 If the VALUETYPE attribute is string, the output is obtained by enclosing
1860 the content of the element in double quote (") characters, and escaping
1861 any double quote characters within the value with a preceding backslash
1862 (\) character.
1863 If there is a <VALUE.REFERENCE> subelement
1864 output a double quote character (").
1865 apply the process recursively to the <CLASSPATH> or <INSTANCEPATH>
1866 subelement of the <VALUE.REFERENCE> element, escaping any double quote
1867 character or backslash character thereby generated with a preceding
1868 backslash (\) character.
1869 output a closing double quote character (").
1870 mike 1.1 If there is no <KEYBINDING> subelement but there is a <KEYVALUE> or
1871 <VALUE.REFERENCE> subelement under the <INSTANCENAME> subelement, then:
1872 Output an equals character (=).
1873 Output the transformed value of the <KEYVALUE> or <VALUE.REFERENCE>, using
1874 the same rules as described above.
1875 If there were no <KEYBINDING> subelements, or no <KEYVALUE> or
1876 <VALUE.REFERENCE> subelement, under the <INSTANCENAME> subelement then output
1877 the string "=@" to indicate a singleton instance.
1878 Finally, after applying the above rules to the <LOCALNAMESPACEPATH>,
1879 <LOCALCLASSPATH> or <LOCALINSTANCEPATH> element, transform the entire output
1880 string into URI-safe format as follows:
1881 Encode the string using UTF-8 [15] if it is not already in this format, and
1882 then;
1883 Apply the standard URI [16, section 2] escaping mechanism to the resulting
1884 string to escape any characters that are unsafe within an HTTP Header, using
1885 the ""%" HEX HEX" convention).
1886 The token CIMObjectPath, where used in this document, represents a
1887 <LOCALNAMESPACEPATH>, <LOCALCLASSPATH> or <LOCALINSTANCEPATH> element to which
1888 the above transformation has been applied.
1889 Back to contents
1890 3.3.4. CIMOperation
1891 mike 1.1 This header MUST be present in all CIM Operation Request and CIM Operation
1892 Response messages. It identifies the HTTP message as carrying a CIM Operation
1893 request or response.
1894 CIMOperation = "CIMOperation" ":" ("MethodCall" | "MethodResponse")
1895
1896 A CIM Client MUST include this header, with the value "MethodCall", in all CIM
1897 Operation Requests that it issues. A CIM Server MUST include this header in all
1898 CIM Operation Responses, with the value "MethodResponse", that it issues.
1899 If a CIM Server receives CIM Operation request with this header, but with a
1900 missing value or a value that is not "MethodCall", then it MUST fail the request
1901 with status "400 Bad Request". The CIM Server MUST include a CIMError header in
1902 the response with a value of unsupported-operation.
1903 If a CIM Server receives a CIM Operation request without this header, it MUST
1904 NOT process it as if it were a CIM Operation Request. The status code returned
1905 by the CIM Server in response to such a request is outside of the scope of this
1906 specification.
1907 If a CIM Client receives a response to a CIM Operation Request without this
1908 header (or if this header has a value which is not "MethodResponse"), it SHOULD
1909 discard the response, and take appropriate measures to publicize the fact that
1910 it has received an incorrect response. The details as to how this is done are
1911 outside of the scope of this specification.
1912 mike 1.1 This header affords a simple mechanism by which firewall or proxy administrators
1913 can make global administrative decisions on all CIM Operations.
1914 Back to contents
1915 3.3.5. CIMProtocolVersion
1916 This header MAY be present in any CIM Operation Request or CIM Operation
1917 Response message. The header identifies the version of the CIM mapping onto
1918 HTTP being used by the sending entity.
1919 CIMProtocolVersion = "CIMProtocolVersion" ":" 1*DIGIT "." 1*DIGIT
1920
1921 If the header is omitted, then a value of 1.0 MUST be assummed.
1922 The major and minor numbers MUST be treated as independent integers which MAY be
1923 incremented higher than a single digit. Therefore version x1.y1 is lower than
1924 x2.y2 if and only if:
1925 x1 is less than x2, or;
1926 x1 equals x2, and y1 is less than y2
1927 If a CIM Server receives an CIM Operation Request for which the value of this
1928 header indicates a version that it does not support, then it MUST respond in the
1929 manner defined in the section on Errors.
1930 Otherwise, if a CIM Server receives an CIM Operation Request for which the value
1931 of this header does not match the value of the PROTOCOLVERSION attribute of the
1932 <MESSAGE> element within the Operation Request, then it MUST fail the request
1933 mike 1.1 and return a status of "400 Bad Request" (and MUST include a CIMError header in
1934 the response with a value of unsupported-protocol-version), subject to the
1935 considerations specified in Errors.
1936 Back to contents
1937 3.3.6. CIMMethod
1938 This header MUST be present in any CIM Operation Request message that contains a
1939 Simple Operation Request.
1940 It MUST NOT be present in any CIM Operation Response message, nor in any CIM
1941 Operation Request message that is not a Simple Operation Request.
1942 The header identifies the name of the CIM method to be invoked, encoded in an
1943 HTTP-safe representation. Firewalls and proxies may use this header to carry
1944 out routing and forwarding decisions based on the CIM method to be invoked.
1945 The name of the CIM method within a Simple Operation Request is defined to be
1946 the value of the NAME attribute of the <METHODCALL> or <IMETHODCALL> element.
1947 CIMMethod = "CIMMethod" ":" MethodName
1948 MethodName = CIMIdentifier
1949
1950 If a CIM Server receives a CIM Operation Request for which either:
1951 The CIMMethod header is present but has an invalid value, or;
1952 The CIMMethod header is not present but the Operation Request Message is a
1953 Simple Operation Request, or;
1954 mike 1.1 The CIMMethod header is present but the Operation Request Message is not a
1955 Simple Operation Request, or;
1956 The CIMMethod header is present, the Operation Request Message is a Simple
1957 Operation Request, but the CIMIdentifier value (when unencoded) does not match
1958 the unique method name within the Simple Operation Request,
1959 then it MUST fail the request and return a status of "400 Bad Request" (and MUST
1960 include a CIMError header in the response with a value of header-mismatch),
1961 subject to the considerations specified in Errors.
1962 Note that this verification provides a basic level of assurance that any
1963 intermediate firewall or proxy was not acting on misleading information when it
1964 decided to forward the request based on the content of the CIMMethod header.
1965 Additional securing of HTTP messages against modification in transit (such as
1966 the encryption of the payload or appending of a digital signature thereto) would
1967 be required to provide a higher degree of integrity.
1968 Back to contents
1969 3.3.7. CIMObject
1970 This header MUST be present in any CIM Operation Request message that contains a
1971 Simple Operation Request.
1972 It MUST NOT be present in any CIM Operation Response message, nor in any CIM
1973 Operation Request message that that is not a Simple Operation Request.
1974 The header identifies the CIM object (which MUST be a Class or Instance for an
1975 mike 1.1 extrinsic method, or a Namespace for an intrinsic method) on which the method is
1976 to be invoked, using a CIM object path encoded in an HTTP-safe representation.
1977 Firewalls and proxies may use this header to carry out routing and forwarding
1978 decisions based on the CIM object that is the target of a method invocation.
1979 CIMObject = "CIMObject" ":" ObjectPath
1980 ObjectPath = CIMObjectPath
1981
1982 The ObjectPath value is constructed by applying the algorithm defined in
1983 Encoding CIM Object Paths to either:
1984 The <LOCALNAMESPACEPATH> subelement of the <IMETHODCALL> element, or;
1985 The <LOCALCLASSPATH> or <LOCALINSTANCEPATH> subelement of the <METHODCALL>
1986 element
1987 within the CIM Operation Request.
1988 If a CIM Server receives a CIM Operation Request for which either:
1989 The CIMObject header is present but has an invalid value, or:
1990 The CIMObject header is not present but the Operation Request Message is a
1991 Simple Operation Request, or;
1992 The CIMObject header is present but the Operation Request Message is not a
1993 Simple Operation Request, or;
1994 The CIMObject header is present, Operation Request Message is a Simple
1995 Operation Request, but the ObjectPath value does not match (where match is
1996 mike 1.1 defined in the section on Encoding CIM Object Paths) the Operation Request
1997 Message,
1998 then it MUST fail the request and return a status of "400 Bad Request" (and MUST
1999 include a CIMError header in the response with a value of header-mismatch),
2000 subject to the considerations specified in Errors.
2001 Note that this verification provides a basic level of assurance that any
2002 intermediate firewall or proxy was not acting on misleading information when it
2003 decided to forward the request based on the content of the CIMObject header.
2004 Additional securing of HTTP messages against modification in transit (such as
2005 the encryption of the payload or appending of a digital signature thereto) would
2006 be required to provide a higher degree of integrity.
2007 Back to contents
2008 3.3.8. CIMBatch
2009 This header MUST be present in any CIM Operation Request message that contains a
2010 Multiple Operation Request.
2011 It MUST NOT be present in any CIM Operation Response message, nor in any CIM
2012 Operation Request message that is not a Multiple Operation Request.
2013 The header identifies the encapsulated Operation Request Message as containing
2014 multiple method invocations. Firewalls and proxies may use this header to carry
2015 out routing and forwarding decisions for batched CIM method invocations.
2016 CIMBatch = "CIMBatch"
2017 mike 1.1
2018 If a CIM Server receives a CIM Operation Request for which either:
2019 The CIMBatch header is present but has an invalid value, or:
2020 The CIMBatch header is not present but the Operation Request Message is a
2021 Multiple Operation Request, or;
2022 The CIMBatch header is present but the Operation Request Message is not a
2023 Multiple Operation Request,
2024 then it MUST fail the request and return a status of "400 Bad Request" (and MUST
2025 include a CIMError header in the response with a value of header-mismatch),
2026 subject to the considerations specified in Errors.
2027 Note that this verification provides a basic level of assurance that any
2028 intermediate firewall or proxy was not acting on misleading information when it
2029 decided to forward the request based on the content of the CIMBatch header.
2030 Additional securing of HTTP messages against modification in transit (such as
2031 the encryption of the payload or appending of a digital signature thereto) would
2032 be required to provide a higher degree of integrity.
2033 If a CIM Server receives a CIM Operation Request for which the CIMBatch header
2034 is present, but the Server does not support Multiple Operations, then it MUST
2035 fail the request and return a status of "501 Not Implemented". Firewalls or
2036 Proxies MAY also employ this mechanism to compel a CIM Client to use Simple
2037 Operation Requests rather than Multiple Operation Requests.
2038 mike 1.1 A CIM Client that receives a response of "501 Not Implemented" to a Multiple
2039 Operation Request SHOULD resubmit that request as a series of Simple Operation
2040 Requests.
2041 Back to contents
2042 3.3.9. CIMError
2043 This header MAY be present in any HTTP response to a CIM Operation Request
2044 message that is not a CIM Operation Response.
2045 It MUST NOT be present in any CIM Operation Response message, nor in any CIM
2046 Operation Request.
2047 The header provides further CIM specific diagnostic information in the case that
2048 the CIM Server encountered a fundamental error during processing of the CIM
2049 Operation Request, and is intended to assist Clients to further disambiguate
2050 errors that have the same HTTP status code.
2051 CIMError = "CIMError" ":" cim-error
2052 cim-error = "unsupported-protocol-version" |
2053 "multiple-requests-unsupported" |
2054 "unsupported-cim-version" |
2055 "unsupported-dtd-version" |
2056 "request-not-valid" |
2057 "request-not-well-formed" |
2058 "request-not-loosely-valid" |
2059 mike 1.1 "header-mismatch" |
2060 "unsupported-operation"
2061
2062 Back to contents
2063 4. HTTP Requirements & Usage
2064 4.1. HTTP Support
2065 It is RECOMMENDED that CIM clients and CIM servers support HTTP/1.1 [7]. CIM
2066 clients and servers MAY support HTTP/1.0 instead. CIM clients and servers MUST
2067 NOT be limited to any version of HTTP earlier than 1.0.
2068 It should be noted that the current revised draft [10] of RFC 2068 clarifies and
2069 corrects ambiguities and errors in that RFC.
2070 CIM Clients and Servers that make use of extension headers as defined in this
2071 specification MUST conform to the requirements defined in [9] for their use.
2072 Back to contents
2073 4.2. Use of Standard Headers
2074 Unless otherwise stated herein, CIM clients and CIM servers MUST comply with the
2075 requirements on the use of headers described in [6,7]. This section defines only
2076 any additional requirements on CIM clients and servers with respect to the use
2077 of standard HTTP headers [6,7] within a CIM Operation Request or CIM Operation
2078 Response.
2079 Note that headers defined in RFC 2068 [7] but deprecated from [10] (e.g. Public,
2080 mike 1.1 Content-Base) SHOULD NOT be used by CIM clients and servers.
2081 4.2.1. Accept
2082 If a CIM client includes an Accept header in a request, it MUST specify a value
2083 which allows the Server to return an entity body of "text/xml" or
2084 "application/xml" in the response.
2085 A CIM server MUST accept any value for this header which states that "text/xml"
2086 or "application/xml" is an acceptable type for an response entity. A server
2087 SHOULD return "406 Not Acceptable" if the Accept header indicates that neither
2088 of these content types are acceptable.
2089 If a CIM server decides to accept a request to return an entity of type other
2090 than "text/xml" or "application/xml", the nature of the response is outside of
2091 the domain of this specification.
2092 Back to contents
2093 4.2.2. Accept-Charset
2094 If a CIM client includes an Accept-Charset header in a request, it MUST specify
2095 a value which allows the Server to return an entity body using the character set
2096 "utf-8".
2097 A CIM server MUST accept any value for this header which implies that "utf-8" is
2098 an acceptable character set for an response entity. A server SHOULD return "406
2099 Not Acceptable" if the Accept-Charset header indicates that this character set
2100 is not acceptable.
2101 mike 1.1 If a CIM server decides to accept a request to return an entity using a
2102 character set other than "utf-8", the nature of the response is outside of the
2103 domain of this specification.
2104 See Internationalization Considerations for more details.
2105 Back to contents
2106 4.2.3. Accept-Encoding
2107 If a CIM client includes an Accept-Encoding header in a request, it MUST specify
2108 a value which allows the Server to use the "identity" encoding.
2109 A CIM Server MUST accept any value for this header which implies that "identity"
2110 is an acceptable encoding for the response entity. A server MAY return "406 Not
2111 Acceptable" if the Accept-Encoding header indicates that the this encoding is
2112 not acceptable.
2113 Back to contents
2114 4.2.4. Accept-Language
2115 If a CIM Client includes an Accept-Language header in a request, it SHOULD
2116 specify a value which allows the Server to return an entity in the language of
2117 its' own choosing. This is accomplished by including in the list of acceptable
2118 language ranges the special range "*".
2119 CIM Servers MAY support multiple languages if they so choose.
2120 See Internationalization Considerations for more details.
2121 Back to contents
2122 mike 1.1 4.2.5. Accept-Ranges
2123 CIM clients MUST NOT include this header in a request. A CIM Server MUST reject
2124 a request that includes an Accept-Range header with a status of "406 Not
2125 Acceptable".
2126 Back to contents
2127 4.2.6. Allow
2128 If a CIM Server is returning a "405 Method Not Allowed" response to a CIM
2129 Operations Request then the Allow header MUST include either M-POST or POST.
2130 Whether it includes any other HTTP methods is outside the scope of this
2131 specification.
2132 Back to contents
2133 4.2.7. Authorization
2134 See the section on Security Considerations for more details.
2135 Back to contents
2136 4.2.8. Cache-Control
2137 In general a CIM Operation Request may consist of a mixture of CIM method
2138 invocations, some of which may be eminently cachable (e.g. the Manufacturer
2139 label on a Disk Drive), and some of which may be decidedly uncachable (e.g.
2140 format a Disk Drive).
2141 Furthermore, the encapsulation of such multiple method invocations within an
2142 HTTP POST or M-POST means that if a CIM Operation Request has any effect on an
2143 mike 1.1 HTTP cache it is likely to be one of invalidating cached responses for the
2144 target CIM Server. Indeed HTTP/1.1[7] stipulates that by default POST responses
2145 are not cachable unless the server indicates otherwise using an appropriate
2146 Cache-Control or Expires header.
2147 For these reasons, CIM Operation Responses SHOULD NOT be considered cachable. A
2148 CIM Server SHOULD NOT include a Cache-Control header in a CIM Operation Response
2149 which might indicate to a cache that the response could be cached.
2150 If the CIM Server is responding to a CIM Operation Request coveyed within an
2151 M-POST request, then in accordance with [9] the Server MUST include a no-cache
2152 control directive to prevent inadvertant caching of the "Ext" header. For
2153 example:
2154 HTTP/1.1 200 OK
2155 Ext:
2156 Cache-Control: no-cache
2157 ...
2158
2159 Back to contents
2160 4.2.9. Connection
2161 It is RECOMMENDED that
2162 CIM clients should avoid the use of the "Connection: close" header unless it
2163 is known in advance that this is the only request likely to be sent out on
2164 mike 1.1 that connection.
2165 CIM servers support persistant connections wherever possible.
2166 Timeout mechanisms SHOULD be employed to remove idle connections on both client
2167 and server, the details of which are outside the domain of this specification.
2168 Clients SHOULD be cautious in retrying requests, especially if they are not
2169 idempotent (e.g. method invocation).
2170 CIM clients and servers SHOULD support pipelining [7, section 1.1.2.2] if
2171 possible, but be aware of the requirements defined in [7]. In particular,
2172 attention is drawn to the following requirement from [7]:
2173 Clients SHOULD NOT pipeline requests using non-idempotent methods or
2174 non-idempotent sequences of methods...A client wishing to send a
2175 non-idempotent request SHOULD wait to send that request until it has received
2176 the response status for the previous request.
2177 Back to contents
2178 4.2.10. Content-Encoding
2179 If a CIM client includes a Content-Encoding header in a request, it SHOULD
2180 specify a value of "identity", unless it has good reason to believe that the
2181 Server can accept another encoding.
2182 Back to contents
2183 4.2.11. Content-Language
2184 See Internationalization Considerations for more details.
2185 mike 1.1 Back to contents
2186 4.2.12. Content-Range
2187 CIM clients and CIM servers MUST NOT use this header.
2188 Back to contents
2189 4.2.13. Content-Type
2190 CIM clients and CIM servers MUST specify (and accept) a value for this header of
2191 either "text/xml" or "application/xml" as defined in [18].
2192 Back to contents
2193 4.2.14. Expires
2194 For the same reasons described in Cache-Control, a CIM Server SHOULD NOT include
2195 an Expires header in a CIM Operation Response which might indicate to a cache
2196 that the response could be cached.
2197 Back to contents
2198 4.2.15. If-Range
2199 CIM clients and CIM servers MUST NOT use this header.
2200 Back to contents
2201 4.2.16. Proxy-Authenticate
2202 See the section on Security Considerations for more details.
2203 Back to contents
2204 4.2.17. Range
2205 CIM clients and CIM servers MUST NOT use this header.
2206 mike 1.1 Back to contents
2207 4.2.18. WWW-Authenticate
2208 See the section on Security Considerations for more details.
2209 Back to contents
2210 4.3. Errors and Status Codes
2211 This section defines how CIM Servers MUST handle errors that occur in the
2212 processing of a CIM Operation Request. This specification does not introduce any
2213 new HTTP response status codes.
2214 If there is an error in processing the HTTP Request-Line or standard HTTP
2215 Headers then the CIM Server MUST take the appropriate action as dictated by its
2216 conformance to the relevant version of HTTP [6,7].
2217 Otherwise, if there are any mandatory extension declarations which the server
2218 does not support it MUST respond with a "510 Not Extended" status according to
2219 [9].
2220 Otherwise, the Server MUST process the request in accordance with the relevant
2221 version of HTTP [6,7] and the additional rules defined in this document.
2222 Assuming that the HTTP request is otherwise correct, the CIM Server MUST use the
2223 following status codes when processing the CIM Extension Headers:
2224 501 Not Implemented One of the following occured:
2225 The CIMProtocolVersion extension header specified in the request specifies a
2226 version of the CIM Mapping onto HTTP which is not supported by this CIM
2227 mike 1.1 Server. The CIM Server MUST include a CIMError header in the response with a
2228 value of unsupported-protocol-version.
2229 The Client specified a Multiple Operation Request and the CIM Server does
2230 not support such requests. The CIM Server MUST include a CIMError header in
2231 the response with a value of multiple-requests-unsupported.
2232 The CIMVERSION attribute in the Operation Request was not set to a value of
2233 "2.0". The CIM Server MUST include a CIMError header in the response with a
2234 value of unsupported-cim-version.
2235 The DTDVERSION attribute in the Operation Request was not set to a value of
2236 "2.0". The CIM Server MUST include a CIMError header in the response with a
2237 value of unsupported-dtd-version.
2238 401 Unauthorized The CIM Server is configured to require that a client
2239 authenticate itself before it can issue CIM Operation Requests to the Server.
2240 403 Forbidden The CIM Server does not allow the client to perform CIM
2241 Operations. The CIM Server MAY alternatively respond with a "404 Not Found"
2242 if it does not wish to reveal this information to the client.
2243 407 Proxy Authentication Required The CIM Server is configured to require that
2244 the proxy authenticate itself before it can issue CIM Operation Requests on
2245 behalf of a CIM Client to the Server.
2246 Assuming that the CIM Extension Headers are correct, then a validating CIM
2247 Server (one which is enforcing validity of the Operation Request Message with
2248 mike 1.1 respect to the CIM XML DTD) MUST use the following status code when processing
2249 the entity body containing the CIM Operation request.
2250 400 Bad Request The entity body defining the CIM Operation request was not
2251 well-formed or not valid with respect to the CIM XML DTD. The CIM Server MUST
2252 include a CIMError header in the response with a value of
2253 request-not-well-formed or request-not-valid (as appropriate).
2254 A loosely-validating CIM Server (one that is only enforcing that the CIM
2255 Operation Request be loosely valid) MAY reject an Operation Request Message that
2256 is not loosely valid with an HTTP status code of 400 (Bad Request) before
2257 further processing, in which case the CIM Server MUST include a CIMError header
2258 in the response with a value of request-not-loosely-valid.
2259 A loosely-validating CIM Server MUST reject an Operation Request Message that is
2260 not well-formed with an HTTP status code of 400 (Bad Request), in which case the
2261 CIM Server MUST include a CIMError header in the response with a value of
2262 request-not-well-formed.
2263 A loosely-validating CIM Server MUST NOT reject an invalid (in the XML sense)
2264 Operation Request Message that is loosely valid.
2265 A loosely-validating CIM Server MUST ultimately signal an error to the CIM
2266 Client if the Operation Request Message is not loosely valid (i.e. is missing
2267 required content, or for which the required content is incorrect, such as an
2268 attribute with an invalid value according to the CIM XML DTD). It is not
2269 mike 1.1 mandated to reject an Operation Request before processing, for to do otherwise
2270 would compel the Server into checking the complete request before processing
2271 could begin and this would be as expensive as requiring that the Server fully
2272 validate the request. Therefore a loosely-validating Server MAY elect to begin
2273 processing the request and issuing a response (with an HTTP success status code)
2274 before checking that the entire request is loosely valid.
2275 A CIM Client may determine whether a CIM Server is validating or
2276 loosely-validating via the CIMValidation header mechanism.
2277 Assuming that the CIM operation request was correctly formed (in the manner
2278 described above), the CIM Server MUST process the request accordingly and return
2279 a CIM Operation Response response.
2280 The entity body MUST be a correct Operation Response Message for that request.
2281 If the CIM Operation Response contains an entity which is a Simple Operation
2282 Response then the response status must be 200 OK. Otherwise the response status
2283 MUST be 207 Multistatus .
2284 Back to contents
2285 4.4. Security Considerations
2286 CIM Clients and CIM Servers MAY elect not to use authentication, but only in
2287 environments where lack of security is not an issue.
2288 Basic Authentication is described in [6,7]. Digest Authentication is defined in
2289 [12]. Both authentication schemes are covered in a consolidated document [14]
2290 mike 1.1 which also makes a number of improvements to the original specification of
2291 Digest Authentication.
2292 Basic Authentication provides a very rudimentary level of authentication, with
2293 the major weakness that the client password is sent over the wire in unencrypted
2294 form.
2295 For this reason CIM Clients and CIM Servers MUST NOT use Basic Authentication
2296 other than in the context of a highly secure environment (for example, if used
2297 in conjunction with SSL, or in a physically secure private network). CIM
2298 Servers MUST NOT send Basic Authentication credentials in a WWW-Authenticate
2299 header other than in the context of a highly secure environment.
2300 Conforming applications SHOULD support the Digest authentication scheme. Since
2301 Digest authentication verifies that both parties share a common secret, without
2302 having to send that secret in the clear, it is more secure than Basic
2303 authentication. However, CIM Clients and CIM Servers that require more robust
2304 protection SHOULD use encyption mechanisms such as SSL or SHTTP.
2305 CIM Clients and CIM Servers using Basic or Digest Authentication MUST comply
2306 with the requirements set forth in [6,7,12,14]. This specification describes
2307 only additional requirements on CIM Clients and CIM Servers when using these
2308 authentication schemes.
2309 CIM Servers SHOULD require that CIM Clients authenticate themselves. This
2310 specification does not mandate this as it is recognized that in some
2311 mike 1.1 circumstances the CIM Server may not require or wish the overhead of employing
2312 authentication. CIM Servers SHOULD consider carefully the performance/security
2313 tradeoffs in determining how often to issue challenges to CIM Clients.
2314 A CIM Server that returns a "401 Unauthorized" response to a CIM Operation
2315 Request SHOULD include in the WWW-Authenticate response-header either the
2316 "Basic" or "Digest" authentication values (but not both). This specification
2317 does not mandate use of Basic or Digest Authentication as it is recognized that
2318 in some circumstances the CIM Server may use bespoke authentication mechanisms
2319 not covered by [14]. Similar considerations apply to the use of the
2320 Proxy-Authorization header in "407 Proxy Authentication Required".
2321 Back to contents
2322 4.5. Determining CIM Server Capabilities
2323 The OPTIONS method MAY be used by a client to determine the CIM capabilities (if
2324 any) of the target server. A CIM Server MAY support the OPTIONS method (for
2325 example, CIM Servers supporting only HTTP/1.0 would not support OPTIONS).
2326 In order to support the ability for a Server to declare its CIM capabilities in
2327 a manner independent of HTTP, it is the intention of the DMTF to publish a CIM
2328 Schema (in a separate document) describing such capabilities. In particular this
2329 mechanism would allow Servers that do not support the OPTIONS method to declare
2330 their capabilities to a Client.
2331 If a CIM Server supports the OPTIONS method, it SHOULD:
2332 mike 1.1 Return the CIM Extension Header CIMProtocolVersion in the response. This
2333 provides a way for a client to discover the version of the CIM HTTP mapping
2334 supported by the CIM Server.
2335 Return the CIM Extension Header CIMSupportedFunctionalGroups in the response.
2336 This provides a way for a client to discover the CIM Operations supported by
2337 the CIM Server.
2338 Return the CIM Extension Header CIMSupportsMultipleOperations in the response.
2339 This provides a way for the client to discover whether the CIM Server can
2340 support Multiple Operation Requests.
2341 In addition, if the CIM Server supports one or more query languages, it SHOULD:
2342 Return the CIM Extension Header CIMSupportedQueryLanguages in the response.
2343 This allows the client to discover the query languages supported by the CIM
2344 Server.
2345 In addition, if the CIM Server runs in a fixed validation mode, it SHOULD:
2346 Return the CIM Extension Header CIMValidation in the response. This allows
2347 the client to determine whether the CIM Server is strictly validating or
2348 loosely validating.
2349 If the CIMProtocolVersion, CIMSupportedFunctionalGroups,
2350 CIMSupportsMultipleOperations, CIMValidation or CIMSupportedQueryLanguages
2351 extension headers are included in the response, the CIM Server MUST declare them
2352 as Optional extension headers using the "Opt" header defined in [9].
2353 mike 1.1 The full format of the "Opt" header declaration for this specification is:
2354 Opt = "Opt" ":" "http://www.dmtf.org/cim/mapping/http/v1.0"
2355 ";" "ns" "=" header-prefix
2356 header-prefix = 2*DIGIT
2357
2358 This header-prefix SHOULD be generated at random on a per-HTTP message basis,
2359 and SHOULD NOT necessarily be a specific number.
2360 For example the following is a fragment of a legitimate OPTIONS response from a
2361 CIM Server:
2362 HTTP/1.1 200 OK
2363 Opt: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=77
2364 77-CIMProtocolVersion: 1.0
2365 77-CIMSupportedFunctionalGroups: basic-read
2366 77-CIMBatch
2367 77-CIMSupportedQueryLanguages: wql
2368 ...
2369
2370 Back to contents
2371 4.5.1. CIMSupportedFunctionalGroups
2372 The CIMSupportedFunctionalGroups extension header SHOULD be returned by a CIM
2373 Server in any OPTIONS response. It MUST NOT be returned in any other scenario.
2374 mike 1.1 This header is defined as follows:
2375 CIMSupportedFunctionalGroups = "CIMSupportedFunctionalGroups" ":"
2376 1#functional-group
2377
2378 functional-group = "basic-read" |
2379 "basic-write" |
2380 "schema-manipulation" |
2381 "instance-manipulation" |
2382 "qualifier-declaration" |
2383 "association-traversal" |
2384 "query-execution"
2385
2386 The functional group definitions correspond directly to those listed in
2387 Functional Profiles. All CIM Servers MUST support the basic-read functional
2388 group. All CIM Clients MAY assume that any CIM Server supports the basic-read
2389 functional group.
2390 The list of functional groups returned by a CIM Server MUST contain the
2391 basic-read group, and MUST NOT contain any duplicates. CIM Clients MUST ignore
2392 any duplicate entries in the functional-group list.
2393 If a functional group is included in the list, then the CIM Client MUST assume
2394 that all other groups on which it depends (according to the rules defined in
2395 mike 1.1 Functional Profiles) are also supported. A CIM Server SHOULD NOT explicitly
2396 include a functional group in the list whose presence may be inferred implicitly
2397 by a dependency.
2398 For example the following HTTP response message indicates that the CIM Server
2399 supports instance-manipulation, association-traversal, basic-write and
2400 basic-read.
2401 HTTP/1.1 200 OK
2402 Opt: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=77
2403 77-CIMProtocolVersion: 1.0
2404 77-CIMSupportedFunctionalGroups: association-traversal,
2405 instance-manipulation
2406 ...
2407
2408 Support for a functional group does not imply that any method from that group
2409 will always succeed. Rather, the absence (whether explicit or implied) of the
2410 functional group from this header is an indication to the CIM Client that
2411 methods in that group will never succeed.
2412 Back to contents
2413 4.5.2. CIMSupportsMultipleOperations
2414 The CIMSupportsMultipleOperations extension header MUST be returned in an
2415 OPTIONS response by any CIM Server that supports Multiple Operation Requests.
2416 mike 1.1 It MUST NOT be returned in any other circumstances.
2417 This header is defined as follows:
2418 CIMSupportsMultipleOperations = "CIMSupportsMultipleOperations"
2419
2420 The presence of this header indicates that the Server can accept and process
2421 Multiple Operation Requests. The absence of this header indicates that the
2422 Server can only accept and process Simple Operation Requests.
2423 Back to contents
2424 4.5.3. CIMSupportedQueryLanguages
2425 The CIMSupportedQueryLanguages extension header SHOULD be returned by a CIM
2426 Server that supports at least one query language in any OPTIONS response. It
2427 MUST NOT be returned in any other scenario.
2428 This header is defined as follows (token has the meaning conferred by [7,
2429 section 2.2]:
2430 CIMSupportedQueryLanguages = "CIMSupportedQueryLanguages" ":"
2431 1#query-language
2432
2433 query-language = token
2434
2435 The query-language value MUST be treated as case-insensitive. It is anticipated
2436 that query languages will be submitted for approval to the DMTF, and each
2437 mike 1.1 submission will define a value for this token to enable it to be specified in
2438 this header.
2439 Back to contents
2440 4.5.4. CIMValidation
2441 The CIMValidation extension header MAY be returned by a CIM Server to provide
2442 information concerning the level of validation of CIM Operation Request
2443 messages.
2444 This header is defined as follows:
2445 CIMValidation = "CIMValidation" ":" validation-level
2446 validation-level = "validating" |
2447 "loosely-validating"
2448
2449 A validation-level of validating indicates that the CIM Server will always apply
2450 strict validation of each CIM Operation Request. A validation-level of
2451 loosely-validating indicates that the CIM Server will apply loose validation of
2452 each CIM Operation Request.
2453 In the absence of this header, a CIM Client SHOULD assume that the CIM Server
2454 operates in strict validation mode.
2455 Back to contents
2456 4.6. Other HTTP Methods
2457 This specification does not in any way define or constrain the manner in which a
2458 mike 1.1 CIM Client or Server uses any HTTP Method other than those explicitly referred
2459 to herein.
2460 Back to contents
2461 4.7. Discovery and Addressing
2462 The target URI of the CIM Operation Request is defined to be the location of the
2463 CIM Server. This specification does not constrain the format of this URI other
2464 than it be a valid URI [13] for the purposes of describing an HTTP-addressable
2465 resource.
2466 An HTTP Server which supports the CIM Mapping defined herein, and which supports
2467 the OPTIONS method, SHOULD include the following CIM extension header in an
2468 OPTIONS response:
2469 CIMOM
2470 This header is defined as follows:
2471 CIMOM = "CIMOM" ":" (absoluteURI | relativeURI)
2472
2473 The terms absoluteURI and relativeURI are taken from [7]; they indicate the
2474 location of the CIM Server for this HTTP Server.
2475 If the CIMOM extension header is included in the response, the CIM Server MUST
2476 declare it an Optional extension header in an analagous fashion to that
2477 described in the section on Determining CIM Server Capabilities.
2478 A CIM Client that wishes to communicate with a CIM Server on an HTTP Server
2479 mike 1.1 SHOULD try an OPTIONS request to that HTTP Server. If the OPTIONS request
2480 fails, or the response does not include the CIM-CIMOM extension header, then the
2481 CIM Client MAY assume that the value of CIM-CIMOM is the relative URI cimom.
2482 Other discovery mechanisms are outside the scope of this version of the
2483 specification.
2484 Example 1
2485 This example shows an HTTP Server located at http://www.dmtf.org issuing an
2486 OPTIONS response to an HTTP client to indicate that its CIM Server is located at
2487 http://www.dmtf.org/access/cimom.
2488 HTTP/1.1 200 OK
2489 Opt: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=48
2490 48-CIMOM: /access/cimom
2491 ...
2492
2493 Example 2
2494 If an HTTP Server located at http://www.dmtf.org responds with a "501 Not
2495 Implemented" to an OPTIONS request from a CIM Client, the CIM client may then
2496 try to contact the CIM Server at http://www.dmtf.org/cimom.
2497 Back to contents
2498 4.8. Internationalization Considerations
2499 This section defines the capabilities of the CIM HTTP Mapping with respect to
2500 mike 1.1 IETF policy guidelines on character sets and languages [19].
2501 In this specification, human-readable fields can be found within a response or
2502 request entity body. In all cases, any human-readable content is encoded using
2503 XML (which has explicit provisions for character set tagging and encoding) and
2504 requires that XML processors read XML elements encoded, at minimum, using the
2505 UTF-8 [15] encoding of the ISO 10646 multilingual plane.
2506 XML examples in this specification demonstrate use of the charset parameter of
2507 the Content-Type header, as defined in [10], as well as the XML encoding
2508 attribute on the <?xml> processing instruction, which together provide charset
2509 identification information for MIME and XML processors. This specification
2510 mandates that conforming applications MUST support at least the "utf-8" charset
2511 encoding [19] in the Content-Type header, and the "utf-8" value for the XML
2512 encoding attribute.
2513 XML also provides a language tagging capability for specifying the language of
2514 the contents of a particular XML element, based on use of IANA registered
2515 language tags [20] in the xml:lang attribute of an XML element to identify the
2516 language of its content and attributes. The XML CIM DTD [2,11] does not declare
2517 this attribute on any of the XML elements, and therefore conforming applications
2518 MUST NOT use this attribute as otherwise the XML document would not be valid
2519 with respect to that DTD.
2520 This specification defines a number of names of HTTP headers and their values.
2521 mike 1.1 These are constructed using standard encoding practices so as to always have an
2522 HTTP-safe ASCII representation. Since these headers are not in general visible
2523 to users they do not need to support encoding in multiple character sets.
2524 The XML DTD for CIM [2,11] introduces a number of XML element names. Similarly
2525 these are not visible to an end user and do not need to support multiple
2526 character set encodings.
2527 The CIM model [1] defines the subset of the Unicode character set that can be
2528 used to name CIM elements (Classes, Instances, Methods, Properties, Qualifiers
2529 and Method Parameters). In general these appear as the value of XML attributes
2530 or as element content, and in general would not be displayed to end users.
2531 Values of CIM Properties and Qualifiers, and error message descriptions MAY be
2532 localizable, but there is no mandate on CIM Servers to support this.
2533 Negotiation and notification of language settings is effected in this mapping
2534 using the standard Accept-Language and Content-Language headers defined in [7].
2535 5. References
2536 "Common Information Model (CIM) Specification", Version 2.2, DMTF, 14th June
2537 1999 (http://dmtf.org/spec/cim_schema_v22.pdf)
2538 "Specification for the Representation of CIM in XML", Version 2.0, DMTF, 20th
2539 July 1999 (http://www.dmtf.org/spec/CIM_XML_Mapping20.htm)
2540 "Extensible Markup Language (XML)", Version 1.0, W3C Recommendation
2541 (http://www.w3.org/TR/REC-xml)
2542 mike 1.1 "Namespaces in XML", 14th January 1999, W3C Recommendation
2543 (http://www.w3.org/TR/REC-xml-names)
2544 "XML as a Representation for Management Information - A White Paper", Version
2545 1.0, DMTF, September 15th 1998 (http://www.dmtf.org/spec/xmlw.html)
2546 "Hypertext Transfer Protocol -- HTTP/1.0", IETF RFC 1945, May 1996
2547 (http://www.ietf.org/rfc/rfc1945.txt)
2548 "Hypertext Transfer Protocol -- HTTP/1.1", IETF RFC 2068, January 1997
2549 (http://www.ietf.org/rfc/rfc2068.txt)
2550 "Key words for use in RFCs to Indicate Requirement Levels", IETF RFC 2119,
2551 March 1997 (http://www.ietf.org/rfc/rfc2119.txt)
2552 "HTTP Extension Framework", IETF Internet Draft, March 15th 1999
2553 (http://ietf.org/internet-drafts/draft-frystyk-http-extensions-03.txt)
2554 "Hypertext Transfer Protocol -- HTTP/1.1", IETF Internet Draft, 18th November
2555 1998 (http://ietf.org/internet-drafts/draft-ietf-http-v11-spec-rev-06.txt )
2556 "CIM XML DTD", Version 2.0, DMTF, 20th July 1999 (
2557 http://www.dmtf.org/spec/cim_dtd_V20.txt)
2558 "An Extension to HTTP : Digest Access Authentication", IETF RFC 2069, January
2559 1997 (http://www.ietf.org/rfc/rfc1945.txt)
2560 "Uniform Resource Identifiers (URI): Generic Syntax", IETF RFC 2396, 12th
2561 August 1998 (http://www.ietf.org/rfc/rfc2396.txt)
2562 "HTTP Authentication: Basic and Digest Access Authentication", IETF Internet
2563 mike 1.1 Draft, September 2nd 1998
2564 (http://ietf.org/internet-drafts/draft-ietf-http-authentication-03.txt)
2565 "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2279, January
2566 1998 (http://www.ietf.org/rfc/rfc2279.txt)
2567 "Uniform Resource Identifiers (URI): Generic Syntax", IETF RFC 2396, 12th
2568 August 1998 (http://www.ietf.org/rfc/rfc2396.txt)
2569 "XSL Transformations (XSLT)", Version 1.0, W3C Working Draft, 21st April 1999
2570 (http://www.w3.org/TR/WD-xslt)
2571 "XML Media Types", IETF Informational RFC 2376, July 1998
2572 (http://www.ietf.org/rfc/rfc2376.txt)
2573 "IETF Policy on Character Sets and Languages", IETF Best Current Practice RFC
2574 2277, January 1998 (http://www.ietf.org/rfc/rfc2277.txt)
2575 "Tags for the Identification of Languages", IETF Standards Track RFC 1766,
2576 March 1995 (http://www.ietf.org/rfc/rfc1766.txt)
2577 "XML Schema Part 1: Structures", W3C Working Draft 6th May 1999
2578 (http://www.w3.org/TR/xmlschema-1/)
2579 Back to contents
2580 Appendix A - Examples of Message Exchanges
2581 This section illustrates the protocol defined in this document by providing
2582 examples of valid HTTP request/response exchanges.
2583 For the purposes of clarity additional white space has been included in the
2584 mike 1.1 examples, but such white space is not an intrinsic part of such XML documents.
2585 A.1. Retrieval of a Single Class Definition
2586 The following HTTP request illustrates how a client would request the class
2587 CIM_VideoBIOSElement.
2588 M-POST /cimom HTTP/1.1
2589 HOST: www.erewhon.com
2590 Content-Type: application/xml; charset="utf-8"
2591 Content-Length: xxxx
2592 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2593 73-CIMOperation: MethodCall
2594 73-CIMMethod: GetClass
2595 73-CIMObject: root/cimv2
2596
2597 <?xml version="1.0" encoding="utf-8" ?>
2598 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2599 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2600 <SIMPLEREQ>
2601 <IMETHODCALL NAME="GetClass">
2602 <LOCALNAMESPACEPATH>
2603 <NAMESPACE NAME="root"/>
2604 <NAMESPACE NAME="cimv20"/>
2605 mike 1.1 </LOCALNAMESPACEPATH>
2606 <IPARAMVALUE NAME="ClassName"><CLASSNAME
2607 NAME="CIM_VideoBIOSElement"/></IPARAMVALUE>
2608 <IPARAMVALUE NAME="LocalOnly"><VALUE>FALSE</VALUE></IPARAMVALUE>
2609 </IMETHODCALL>
2610 </SIMPLEREQ>
2611 </MESSAGE>
2612 </CIM>
2613
2614 The following is an HTTP response to the above request indicating success of the
2615 requested operation. For clarity of exposition the complete definition of the
2616 returned <CLASS> element has not been shown.
2617 HTTP/1.1 200 OK
2618 Content-Type: application/xml; charset="utf-8"
2619 Content-Length: xxxx
2620 Ext:
2621 Cache-Control: no-cache
2622 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2623 73-CIMOperation: MethodResponse
2624
2625 <?xml version="1.0" encoding="utf-8" ?>
2626 mike 1.1 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2627 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2628 <SIMPLERSP>
2629 <IMETHODRESPONSE NAME="GetClass">
2630 <IRETURNVALUE>
2631 <CLASS NAME="CIM_VideoBIOSElement" SUPERCLASS="CIM_SoftwareElement">
2632 ...
2633 </CLASS>
2634 </IRETURNVALUE>
2635 </IMETHODRESPONSE>
2636 </SIMPLERSP>
2637 </MESSAGE>
2638 </CIM>
2639
2640 Back to contents
2641 A.2. Retrieval of a Single Instance Definition
2642 The following HTTP request illustrates how a client would request the instance
2643 MyClass.MyKey="S3".
2644 M-POST /cimom HTTP/1.1
2645 HOST: www.erewhon.com
2646 Content-Type: application/xml; charset="utf-8"
2647 mike 1.1 Content-Length: xxxx
2648 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2649 73-CIMOperation: MethodCall
2650 73-CIMMethod: GetInstance
2651 73-CIMObject: root/cimv2
2652
2653 <?xml version="1.0" encoding="utf-8" ?>
2654 <CIM CIMVERSION="2.0" DTDVERSION="1.1">
2655 <MESSAGE ID="87855" PROTOCOLVERSION="1.0">
2656 <SIMPLEREQ>
2657 <IMETHODCALL NAME="GetInstance">
2658 <LOCALNAMESPACEPATH>
2659 <NAMESPACE NAME="root"/>
2660 <NAMESPACE NAME="myNamespace"/>
2661 </LOCALNAMESPACEPATH>
2662 <IPARAMVALUE NAME="InstanceName">
2663 <INSTANCENAME CLASSNAME="MyClass">
2664 <KEYBINDING NAME="MyKey"><KEYVALUE>S3</KEYVALUE></KEYBINDING>
2665 </INSTANCENAME>
2666 </IPARAMVALUE>
2667 <IPARAMVALUE NAME="LocalOnly"><VALUE>FALSE</VALUE></IPARAMVALUE>
2668 mike 1.1 </IMETHODCALL>
2669 </SIMPLEREQ>
2670 </MESSAGE>
2671 </CIM>
2672
2673 The following is an HTTP response to the above request indicating an error due
2674 to the specified instance not being found.
2675 HTTP/1.1 200 OK
2676 Content-Type: application/xml; charset="utf-8"
2677 Content-Length: xxxx
2678 Ext:
2679 Cache-Control: no-cache
2680 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2681 73-CIMOperation: MethodResponse
2682
2683 <?xml version="1.0" encoding="utf-8" ?>
2684 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2685 <MESSAGE ID="87885" PROTOCOLVERSION="1.0">
2686 <SIMPLERSP>
2687 <IMETHODRESPONSE NAME="GetInstance">
2688 <ERROR CODE="6" DESCRIPTION="Instance of MyClass not found"/>
2689 mike 1.1 </IMETHODRESPONSE>
2690 </SIMPLERSP>
2691 </MESSAGE>
2692 </CIM>
2693
2694 Back to contents
2695 A.3. Deletion of a Single Class Definition
2696 The following HTTP request illustrates how a client would delete the class
2697 CIM_VideoBIOSElement.
2698 M-POST /cimom HTTP/1.1
2699 HOST: www.erewhon.com
2700 Content-Type: application/xml; charset="utf-8"
2701 Content-Length: xxxx
2702 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2703 73-CIMOperation: MethodCall
2704 73-CIMMethod: DeleteClass
2705 73-CIMObject: root/cimv2
2706
2707 <?xml version="1.0" encoding="utf-8" ?>
2708 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2709 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2710 mike 1.1 <SIMPLEREQ>
2711 <IMETHODCALL NAME="DeleteClass">
2712 <LOCALNAMESPACEPATH>
2713 <NAMESPACE NAME="root"/>
2714 <NAMESPACE NAME="cimv20"/>
2715 </LOCALNAMESPACEPATH>
2716 <IPARAMVALUE NAME="ClassName"><CLASSNAME
2717 NAME="CIM_VideoBIOSElement"/></IPARAMVALUE>
2718 </IMETHODCALL>
2719 </SIMPLEREQ>
2720 </MESSAGE>
2721 </CIM>
2722
2723 The following is an HTTP response to the above request indicating failure of the
2724 above operation due to the inability to delete instances of the Class.
2725 HTTP/1.1 200 OK
2726 Content-Type: application/xml; charset="utf-8"
2727 Content-Length: xxxx
2728 Ext:
2729 Cache-Control: no-cache
2730 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2731 mike 1.1 73-CIMOperation: MethodResponse
2732
2733 <?xml version="1.0" encoding="utf-8" ?>
2734 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2735 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2736 <SIMPLERSP>
2737 <IMETHODRESPONSE NAME="DeleteClass">
2738 <ERROR CODE="9" DESCRIPTION="Class has non-deletable instances"/>
2739 </IMETHODRESPONSE>
2740 </SIMPLERSP>
2741 </MESSAGE>
2742 </CIM>
2743
2744 Back to contents
2745 A.4. Deletion of a Single Instance Definition
2746 The following HTTP request illustrates how a client would delete the instance
2747 MyClass.MyKey="S3".
2748 M-POST /cimom HTTP/1.1
2749 HOST: www.erewhon.com
2750 Content-Type: application/xml; charset="utf-8"
2751 Content-Length: xxxx
2752 mike 1.1 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2753 73-CIMOperation: MethodCall
2754 73-CIMMethod: DeleteInstance
2755 73-CIMObject: root/cimv2
2756
2757 <?xml version="1.0" encoding="utf-8" ?>
2758 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2759 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2760 <SIMPLEREQ>
2761 <IMETHODCALL NAME="DeleteInstance">
2762 <LOCALNAMESPACEPATH>
2763 <NAMESPACE NAME="root"/>
2764 <NAMESPACE NAME="myNamespace"/>
2765 </LOCALNAMESPACEPATH>
2766 <IPARAMVALUE NAME="InstancePath">
2767 <INSTANCENAME CLASSNAME="MyClass">
2768 <KEYBINDING NAME="MyKey">
2769 <KEYVALUE>S3</KEYVALUE>
2770 </KEYBINDING>
2771 </INSTANCENAME>
2772 </IPARAMVALUE>
2773 mike 1.1 </IMETHODCALL>
2774 </SIMPLEREQ>
2775 </MESSAGE>
2776 </CIM>
2777
2778 The following is an HTTP response to the above request indicating success of the
2779 above operation.
2780 HTTP/1.1 200 OK
2781 Content-Type: application/xml; charset="utf-8"
2782 Content-Length: xxxx
2783 Ext:
2784 Cache-Control: no-cache
2785 Man: http://www.dmtf.org/cim/operation ; ns=73
2786 73-CIMOperation: MethodResponse
2787
2788 <?xml version="1.0" encoding="utf-8" ?>
2789 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2790 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2791 <SIMPLERSP>
2792 <IMETHODRESPONSE NAME="DeleteInstance"/>
2793 </SIMPLERSP>
2794 mike 1.1 </MESSAGE>
2795 </CIM>
2796
2797 Back to contents
2798 A.5. Creation of a Single Class Definition
2799 The following HTTP request illustrates how a client would create the class
2800 MySchema_VideoBIOSElement as a subclass of CIM_VideoBIOSElement. For clarity of
2801 exposition most of the submitted <CLASS> element is omitted from the example.
2802 M-POST /cimom HTTP/1.1
2803 HOST: www.erewhon.com
2804 Content-Type: application/xml; charset="utf-8"
2805 Content-Length: xxxx
2806 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2807 73-CIMOperation: MethodCall
2808 73-CIMMethod: CreateClass
2809 73-CIMObject: root/cimv2
2810
2811 <?xml version="1.0" encoding="utf-8" ?>
2812 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2813 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2814 <SIMPLEREQ>
2815 mike 1.1 <IMETHODCALL NAME="CreateClass">
2816 <LOCALNAMESPACEPATH>
2817 <NAMESPACE NAME="root"/>
2818 <NAMESPACE NAME="cimv2"/>
2819 </LOCALNAMESPACEPATH>
2820 <IPARAMVALUE NAME="NewClass">
2821 <CLASS NAME="MySchema_VideoBIOSElement"
2822 SUPERCLASS="CIM_VideoBIOSElement">
2823 ...
2824 </CLASS>
2825 </IPARAMVALUE>
2826 </IMETHODCALL>
2827 </SIMPLEREQ>
2828 </MESSAGE>
2829 </CIM>
2830
2831 The following is an HTTP response to the above request indicating success of the
2832 above operation.
2833 HTTP/1.1 200 OK
2834 Content-Type: application/xml; charset="utf-8"
2835 Content-Length: xxxx
2836 mike 1.1 Ext:
2837 Cache-Control: no-cache
2838 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2839 73-CIMOperation: MethodResponse
2840
2841 <?xml version="1.0" encoding="utf-8" ?>
2842 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2843 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2844 <SIMPLERSP>
2845 <IMETHODRESPONSE NAME="CreateClass"/>
2846 </SIMPLERSP>
2847 </MESSAGE>
2848 </CIM>
2849
2850 Back to contents
2851 A.6. Creation of a Single Instance Definition
2852 The following HTTP request illustrates how a client would create an instance of
2853 the class MySchema_VideoBIOSElement. For clarity of exposition most of the
2854 submitted <INSTANCE> element is omitted from the example.
2855 M-POST /cimom HTTP/1.1
2856 HOST: www.erewhon.com
2857 mike 1.1 Content-Type: application/xml; charset="utf-8"
2858 Content-Length: xxxx
2859 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2860 73-CIMOperation: MethodCall
2861 73-CIMMethod: CreateInstance
2862 73-CIMObject: root/cimv2
2863
2864 <?xml version="1.0" encoding="utf-8" ?>
2865 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2866 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2867 <SIMPLEREQ>
2868 <IMETHODCALL NAME="CreateInstance">
2869 <LOCALNAMESPACEPATH>
2870 <NAMESPACE NAME="root"/>
2871 <NAMESPACE NAME="cimv20"/>
2872 </LOCALNAMESPACEPATH>
2873 <IPARAMVALUE NAME="NewInstance">
2874 <INSTANCE CLASSNAME="CIM_VideoBIOSElement">
2875 ...
2876 </INSTANCE>
2877 </IPARAMVALUE>
2878 mike 1.1 </IMETHODCALL>
2879 </SIMPLEREQ>
2880 </MESSAGE>
2881 </CIM>
2882
2883 The following is an HTTP response to the above request indicating success of the
2884 above operation.
2885 HTTP/1.1 200 OK
2886 Content-Type: application/xml; charset="utf-8"
2887 Content-Length: xxxx
2888 Ext:
2889 Cache-Control: no-cache
2890 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2891 73-CIMOperation: MethodResponse
2892
2893 <?xml version="1.0" encoding="utf-8" ?>
2894 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2895 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2896 <SIMPLERSP>
2897 <IMETHODRESPONSE NAME="CreateInstance">
2898 <IRETURNVALUE>
2899 mike 1.1 <INSTANCENAME CLASSNAME="MySchema_VideoBIOSElement">
2900 <KEYBINDING NAME="Name">
2901 <KEYVALUE>S4</KEYVALUE>
2902 </KEYBINDING>
2903 </INSTANCENAME>
2904 </IRETURNVALUE>
2905 </IRETURNVALUE>
2906 </SIMPLERSP>
2907 </MESSAGE>
2908 </CIM>
2909
2910 Back to contents
2911 A.7. Enumeration of Class Names
2912 The following HTTP request illustrates how a client would enumerate the names of
2913 all subclasses of the class CIM_SoftwareElement.
2914 M-POST /cimom HTTP/1.1
2915 HOST: www.erewhon.com
2916 Content-Type: application/xml; charset="utf-8"
2917 Content-Length: xxxx
2918 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2919 73-CIMOperation: MethodCall
2920 mike 1.1 73-CIMMethod: EnumerateClassNames
2921 73-CIMObject: root/cimv2
2922
2923 <?xml version="1.0" encoding="utf-8" ?>
2924 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2925 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2926 <SIMPLEREQ>
2927 <IMETHODCALL NAME="EnumerateClassNames">
2928 <LOCALNAMESPACEPATH>
2929 <NAMESPACE NAME="root"/>
2930 <NAMESPACE NAME="cimv20"/>
2931 </LOCALNAMESPACEPATH>
2932 <IPARAMVALUE NAME="ClassName"><CLASSNAME
2933 NAME="CIM_SoftwareElement"/></IPARAMVALUE>
2934 <IPARAMVALUE NAME="DeepInheritance"><VALUE>FALSE</VALUE></IPARAMVALUE>
2935 </IMETHODCALL>
2936 </SIMPLEREQ>
2937 </MESSAGE>
2938 </CIM>
2939
2940 The following is an HTTP response to the above request indicating success of the
2941 mike 1.1 above operation, and returning the names of the requested subclasses.
2942 HTTP/1.1 200 OK
2943 Content-Type: application/xml; charset="utf-8"
2944 Content-Length: xxxx
2945 Ext:
2946 Cache-Control: no-cache
2947 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
2948 73-CIMOperation: MethodResponse
2949
2950 <?xml version="1.0" encoding="utf-8" ?>
2951 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2952 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2953 <SIMPLERSP>
2954 <IMETHODRESPONSE NAME="EnumerateClassNames">
2955 <IRETURNVALUE>
2956 <CLASSNAME NAME="CIM_BIOSElement"/>
2957 <CLASSNAME NAME="CIM_VideoBOISElement"/>
2958 </IRETURNVALUE>
2959 </IMETHODRESPONSE>
2960 </SIMPLERSP>
2961 </MESSAGE>
2962 mike 1.1 </CIM>
2963
2964 Back to contents
2965 A.8. Enumeration of Instances
2966 The following HTTP request illustrates how a client would enumerate all
2967 instances of the class CIM_LogicalDisk. For clarity of exposition most of the
2968 returned Instances are omitted from the example.
2969 M-POST /cimom HTTP/1.1
2970 HOST: www.erewhon.com
2971 Content-Type: application/xml; charset="utf-8"
2972 Content-Length: xxxx
2973 Man: http://www.dmtf.org/cim/operation ; ns=73
2974 73-CIMOperation: MethodCall
2975 73-CIMMethod: EnumerateInstances
2976 73-CIMObject: root/cimv2
2977
2978 <?xml version="1.0" encoding="utf-8" ?>
2979 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
2980 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
2981 <SIMPLEREQ>
2982 <IMETHODCALL NAME="EnumerateInstances">
2983 mike 1.1 <LOCALNAMESPACEPATH>
2984 <NAMESPACE NAME="root"/>
2985 <NAMESPACE NAME="cimv20"/>
2986 </LOCALNAMESPACEPATH>
2987 <IPARAMVALUE NAME="ClassName"><CLASSNAME
2988 NAME="CIM_LogicalDisk"/></IPARAMVALUE>
2989 <IPARAMVALUE NAME="LocalOnly"><VALUE>TRUE</VALUE></IPARAMVALUE>
2990 <IPARAMVALUE NAME="DeepInheritance"><VALUE>TRUE</VALUE></IPARAMVALUE>
2991 </IMETHODCALL>
2992 </SIMPLEREQ>
2993 </MESSAGE>
2994 </CIM>
2995
2996 The following is an HTTP response to the above request indicating success of the
2997 above operation, returning the requested instances.
2998 HTTP/1.1 200 OK
2999 Content-Type: application/xml; charset="utf-8"
3000 Content-Length: xxxx
3001 Ext:
3002 Cache-Control: no-cache
3003 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
3004 mike 1.1 73-CIMOperation: MethodResponse
3005
3006 <?xml version="1.0" encoding="utf-8" ?>
3007 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
3008 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
3009 <SIMPLERSP>
3010 <IMETHODRESPONSE NAME="EnumerateInstances">
3011 <IRETURNVALUE>
3012 <VALUE.NAMEDINSTANCE>
3013 <INSTANCENAME CLASSNAME="Erewhon_LogicalDisk">
3014 ...
3015 </INSTANCENAME>
3016 <INSTANCE CLASSNAME="Erewhon_LogicalDisk">
3017 ...
3018 </INSTANCE>
3019 </VALUE.NAMEDINSTANCE>
3020 ...
3021 <VALUE.NAMEDINSTANCE>
3022 <INSTANCENAME CLASSNAME="Foobar_LogicalDisk">
3023 ...
3024 </INSTANCENAME>
3025 mike 1.1 <INSTANCE CLASSNAME="Foobar_LogicalDisk">
3026 ...
3027 </INSTANCE>
3028 </VALUE.NAMEINSTANCE>
3029 </IRETURNVALUE>
3030 </IMETHODRESPONSE>
3031 </SIMPLERSP>
3032 </MESSAGE>
3033 </CIM>
3034
3035 Back to contents
3036 A.9. Retrieval of a Single Property
3037 The following HTTP request illustrates how a client would retrieve the FreeSpace
3038 property from the Instance MyDisk.DeviceID="C:".
3039 M-POST /cimom HTTP/1.1
3040 HOST: www.erewhon.com
3041 Content-Type: application/xml; charset="utf-8"
3042 Content-Length: xxxx
3043 Man: http://www.dmtf.org/cim/operation ; ns=73
3044 73-CIMOperation: MethodCall
3045 73-CIMMethod: GetProperty
3046 mike 1.1 73-CIMObject: root/cimv2
3047
3048 <?xml version="1.0" encoding="utf-8" ?>
3049 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
3050 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
3051 <SIMPLEREQ>
3052 <IMETHODCALL NAME="GetProperty">
3053 <LOCALNAMESPACEPATH>
3054 <NAMESPACE NAME="root"/>
3055 <NAMESPACE NAME="myNamespace"/>
3056 </LOCALNAMESPACEPATH>
3057 <IPARAMVALUE NAME="InstanceName">
3058 <INSTANCENAME CLASSNAME="MyDisk">
3059 <KEYBINDING NAME="DeviceID"><KEYVALUE>C:</KEYVALUE></KEYBINDING>
3060 </INSTANCENAME>
3061 </IPARAMVALUE>
3062 <IPARAMVALUE
3063 NAME="PropertyName"><VALUE>FreeSpace</VALUE></IPARAMVALUE>
3064 </IMETHODCALL>
3065 </SIMPLEREQ>
3066 </MESSAGE>
3067 mike 1.1 </CIM>
3068
3069 The following is an HTTP response to the above request indicating success of the
3070 above operation, returning the requested value.
3071 HTTP/1.1 200 OK
3072 Content-Type: application/xml; charset="utf-8"
3073 Content-Length: xxxx
3074 Ext:
3075 Cache-Control: no-cache
3076 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
3077 73-CIMOperation: MethodResponse
3078
3079 <?xml version="1.0" encoding="utf-8" ?>
3080 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
3081 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
3082 <SIMPLERSP>
3083 <IMETHODRESPONSE NAME="GetProperty">
3084 <IRETURNVALUE>
3085 <VALUE>6752332</VALUE>
3086 </IRETURNVALUE>
3087 </IMETHODRESPONSE>
3088 mike 1.1 </SIMPLERSP>
3089 </MESSAGE>
3090 </CIM>
3091
3092 Back to contents
3093 A.10. Execution of an Extrinsic Method
3094 The following HTTP request illustrates how a client would execute the
3095 SetPowerState method on the Instance MyDisk.DeviceID="C:".
3096 M-POST /cimom HTTP/1.1
3097 HOST: www.erewhon.com
3098 Content-Type: application/xml; charset="utf-8"
3099 Content-Length: xxxx
3100 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
3101 73-CIMOperation: MethodCall
3102 73-CIMMethod: SetPowerState
3103 73-CIMObject: root/cimv2:Win32_LogicalDisk="C:"
3104
3105 <?xml version="1.0" encoding="utf-8" ?>
3106 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
3107 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
3108 <SIMPLEREQ>
3109 mike 1.1 <METHODCALL NAME="SetPowerState">
3110 <LOCALINSTANCEPATH>
3111 <LOCALNAMESPACEPATH>
3112 <NAMESPACE NAME="root"/>
3113 <NAMESPACE NAME="myNamespace"/>
3114 </LOCALNAMESPACEPATH>
3115 <INSTANCENAME CLASSNAME="MyDisk">
3116 <KEYBINDING NAME="C:"><KEYVALUE>C:</KEYVALUE></KEYBINDING>
3117 </INSTANCENAME>
3118 </LOCALINSTANCEPATH>
3119 <PARAMVALUE NAME="PowerState"><VALUE>1</VALUE></PARAMVALUE>
3120 <PARAMVALUE
3121 NAME="Time"><VALUE>00000001132312.000000:000</VALUE></PARAMVALUE>
3122 </METHODCALL>
3123 </SIMPLEREQ>
3124 </MESSAGE>
3125 </CIM>
3126
3127 The following is an HTTP response to the above request indicating success of the
3128 above operation.
3129 HTTP/1.1 200 OK
3130 mike 1.1 Content-Type: application/xml; charset="utf-8"
3131 Content-Length: xxxx
3132 Ext:
3133 Cache-Control: no-cache
3134 Man: http://www.dmtf.org/cim/mapping/http/v1.0 ; ns=73
3135 73-CIMOperation: MethodResponse
3136
3137 <?xml version="1.0" encoding="utf-8" ?>
3138 <CIM CIMVERSION="2.0" DTDVERSION="2.0">
3139 <MESSAGE ID="87872" PROTOCOLVERSION="1.0">
3140 <SIMPLERSP>
3141 <METHODRESPONSE NAME="SetPowerState">
3142 <RETURNVALUE>
3143 <VALUE>0</VALUE>
3144 </RETURNVALUE>
3145 </METHODRESPONSE>
3146 </SIMPLERSP>
3147 </MESSAGE>
3148 </CIM>
3149
3150 Back to contents
|
Return to
CIM-HTTP.txt
CVS log
Up to [Pegasus] / pegasus / doc