1 mike 1.2 //%/////////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2000, 2001 The Open group, BMC Software, Tivoli Systems, IBM
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a copy
6 // of this software and associated documentation files (the "Software"), to
7 // deal in the Software without restriction, including without limitation the
8 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 // sell copies of the Software, and to permit persons to whom the Software is
10 // furnished to do so, subject to the following conditions:
11 //
12 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
13 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
14 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
15 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
16 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
18 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
19 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20 //
21 //==============================================================================
22 mike 1.2 //
23 // Author: Mike Brasher (mbrasher@bmc.com)
24 //
25 // Modified By: Karl Schopmeyer (k.schopmeyer@opengroup.org)
26 //
27 //%/////////////////////////////////////////////////////////////////////////////
28
29 #ifndef Pegasus_Operations_h
30 #define Pegasus_Operations_h
31
32 #include <Pegasus/Common/Config.h>
33 #include <Pegasus/Common/CIMClass.h>
34 #include <Pegasus/Common/CIMInstance.h>
35 #include <Pegasus/Common/CIMQualifierDecl.h>
36 #include <Pegasus/Common/CIMObject.h>
37
38 PEGASUS_NAMESPACE_BEGIN
39
40 /** The CIMOperations Class.
41 This class defines the external client operations for Pegasus These
42 operations are based on the WBEM operations defined in the DMTF CIM
43 mike 1.2 CIMOperations over HTTP operations Specification. They duplicate the names,
44 functions, and parameters of those CIMOperations. Each WBEM operation is a
45 method in this class.
46
47 This library (operations.h) defines the external APIs for the Pegasus MSB.
48 These are synchronous calls and match the operations defined by the DMTF in
49 the document "Specification for CIM CIMOperations over HTTP" Version 1.0
50 with
51 errata
52
53 The CIMOperations class is used by other classes such as the client,
54 provider, and repository classes to instantiate the operations interfaces.
55 */
56 class PEGASUS_COMMON_LINKAGE CIMOperations
57 {
58 public:
59
60 virtual ~CIMOperations();
61
62 /** The <TT>getClass</TT> method returns a single CIM Class from the
63 target Namespace where the ClassName input parameter defines the name of
64 mike 1.2 the class to be retrieved.
65
66 @param nameSpace The <TT>nameSpace</TT> parameter is a string that
67 defines the target Namespace.
68 See defintion of \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
69
70 @param className The <TT>className</TT> input parameter defines the name
71 of the Class to be retrieved.
72
73 @param localOnly If the <TT>localOnly</TT> input parameter is true, this
74 specifies that only CIM Elements (properties, methods and qualifiers)
75 overriden within the definition of the Class are returned. If false,
76 all elements are returned. This parameter therefore effects a CIM
77 Server-side mechanism to filter certain elements of the returned object
78 based on whether or not they have been propagated from the parent Class
79 (as defined by the PROPAGATED attribute).
80
81 @param includeQualifiers If the <TT>includeQualifiers</TT> input
82 parameter is true, this specifies that all Qualifiers for that Class
83 (including Qualifiers on the Class and on any returned Properties,
84 Methods or CIMMethod Parameters) MUST be included as <QUALIFIER>
85 mike 1.2 elements in the response. If false no <QUALIFIER> elements are
86 present in the returned Class.
87
88 @param includeClassOrigin If the <TT>includeClassOrigin</TT> input
89 parameter is true, this specifies that the CLASSORIGIN attribute MUST be
90 present on all appropriate elements in the returned Class. If false, no
91 CLASSORIGIN attributes are present in the returned Class.
92
93 @param propertyList If the <TT>propertyList</TT> input parameter is not
94 NULL, the members of the array define one or more CIMProperty names. The
95 returned Class MUST NOT include elements for any Properties missing from
96 this list. Note that if LocalOnly is specified as true this acts as an
97 additional filter on the set of Properties returned (for example, if
98 CIMProperty A is included in the PropertyList but LocalOnly is set to
99 true and A is not local to the requested Class, then it will not be
100 included in the response). If the PropertyList input parameter is an
101 empty array this signifies that no Properties are included in the
102 response. If the PropertyList input parameter is NULL this specifies
103 that all Properties (subject to the conditions expressed by the other
104 parameters) are included in the response.
105
106 mike 1.2 If the <TT>propertyList</TT> contains duplicate elements, the Server
107 MUST ignore the duplicates but otherwise process the request normally.
108 If the PropertyList contains elements which are invalid CIMProperty
109 names for the target Class, the Server MUST ignore such entries but
110 otherwise process the request normally.
111
112 @return If successful, the return value is a single CIM Class.
113
114 If unsuccessful, one of the following status codes MUST be returned by
115 this method, where the first applicable error in the list (starting with
116 the first element of the list, and working down) is the error returned.
117 Any additional method-specific interpretation of the error in is given
118 in parentheses.
119 <UL>
120 <LI>CIM_ERR_ACCESS_DENIED
121 <LI>CIM_ERR_INVALID_NAMESPACE
122 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
123 duplicate,unrecognized or otherwise
124 incorrect parameters)
125 <LI>CIM_ERR_NOT_FOUND (the request CIM Class does not exist in
126 the
127 mike 1.2 specified
128 namespace)
129 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
130 </UL>
131 */
132 virtual CIMClass getClass(
133 const String& nameSpace,
134 const String& className,
135 Boolean localOnly = true,
136 Boolean includeQualifiers = true,
137 Boolean includeClassOrigin = false,
138 const Array<String>& propertyList = EmptyStringArray()) = 0;
139
140 /** The <<TT>getInstance</TT> method returns a single CIM Instance from
141 the target Namespace based on the InstanceName parameter provided.
142
143 @param nameSpace The <TT>nameSpace</TT> parameter is a string that
144 defines the target namespace. See defintion of
145 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
146
147 @param instanceName The <TT>instanceName</TT> input parameter defines
148 mike 1.2 the name of the Instance to be retrieved.
149
150 @param localOnly If the <TT>localOnly</TT> input parameter is true,
151 this specifies that only elements (properties and qualifiers) overriden
152 within the definition of the Instance are returned. If false, all
153 elements are returned. This parameter therefore effects a CIM
154 Server-side mechanism to filter certain elements of the returned object
155 based on whether or not they have been propagated from the parent Class
156 (as defined by the PROPAGATED attribute).
157
158 @param includeQualifiers If the <TT>includeQualifiers</TT> input
159 parameter is true, this specifies that all Qualifiers for that Instance
160 (including Qualifiers on the Instance and on any returned Properties)
161 MUST be included as <QUALIFIER> elements in the response. If false no
162 <QUALIFIER> elements are present in the returned Instance.
163
164 @param includeClassOrigin If the <TT>includeClassOrigin</TT> input
165 parameter is true, this specifies that the CLASSORIGIN attribute MUST
166 be present on all appropriate elements in the returned Instance. If
167 false, no CLASSORIGIN attributes are present in the returned instance.
168
169 mike 1.2 @param propertyList If the <TT>propertyList</TT> input parameter is not
170 NULL, the members of the array define one or more CIMProperty names. The
171 returned Instance MUST NOT include elements for any Properties missing
172 from this list. Note that if LocalOnly is specified as true this acts as
173 an additional filter on the set of Properties returned (for example, if
174 CIMProperty A is included in the PropertyList but LocalOnly is set to
175 true and A is not local to the requested Instance, then it will not be
176 included in the response). If the PropertyList input parameter is an
177 empty array this signifies that no Properties are included in the
178 response. If the PropertyList input parameter is NULL this specifies
179 that all Properties (subject to the conditions expressed by the other
180 parameters) are included in the response.
181
182 If the <TT>PropertyList</TT> contains duplicate elements, the Server
183 MUST ignore the duplicates but otherwise process the request normally.
184 If the PropertyList contains elements which are invalid CIMProperty
185 names for the target Instance, the Server MUST ignore such entries but
186 otherwise process the request normally.
187
188 @return If successful, the return value is a single CIM Instance.
189
190 mike 1.2 If unsuccessful, one of the following status codes MUST be returned by
191 this method, where the first applicable error in the list (starting
192 with the first element of the list, and working down) is the error
193 returned. Any additional method-specific interpretation of the error in
194 is given in parentheses.
195
196 <UL>
197 <LI>CIM_ERR_ACCESS_DENIED
198 <LI>CIM_ERR_INVALID_NAMESPACE
199 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
200 unrecognized or otherwise incorrect parameters)
201 <LI>CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the
202 specified namespace)
203 <LI>CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
204 CIM Instance does not exist in the specified namespace)
205 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
206 </LI>
207 </UL>
208 */
209 virtual CIMInstance getInstance(
210 const String& nameSpace,
211 mike 1.2 const CIMReference& instanceName,
212 Boolean localOnly = true,
213 Boolean includeQualifiers = false,
214 Boolean includeClassOrigin = false,
215 const Array<String>& propertyList = EmptyStringArray()) = 0;
216
217 /** The <TT>DeleteClass</TT> method deletes a single CIM Class from the
218 target Namespace.
219
220 @param nameSpace The nameSpace parameter is a string that defines
221 the target namespace. See defintion of
222 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
223
224 @param className The <TT>className</TT> input parameter defines the name
225 of the Class to be deleted.
226
227 @return If successful, the specified Class (including any subclasses
228 and any instances) MUST have been removed by the CIM Server. The
229 operation MUST fail if any one of these objects cannot be deleted.
230
231 If unsuccessful, one of the following status codes MUST be returned by
232 mike 1.2 this method, where the first applicable error in the list (starting
233 with the first element of the list, and working down) is the error
234 returned. Any additional method-specific interpretation of the error
235 in is given in parentheses.
236
237 <UL>
238 <LI>CIM_ERR_ACCESS_DENIED
239 <LI>CIM_ERR_NOT_SUPPORTED
240 <LI>CIM_ERR_INVALID_NAMESPACE
241 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
242 unrecognized or otherwise incorrect parameters)
243 <LI>CIM_ERR_NOT_FOUND (the CIM Class to be deleted does not exist)
244 <LI>CIM_ERR_CLASS_HAS_CHILDREN (the CIM Class has one or more
245 subclasses which cannot be deleted)
246 <LI>CIM_ERR_CLASS_HAS_INSTANCES (the CIM Class has one or more
247 instances which cannot be deleted)
248 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
249 </UL>
250 */
251 virtual void deleteClass(
252 const String& nameSpace,
253 mike 1.2 const String& className) = 0;
254
255 /** The <TT>DeleteInstance</TT> operation deletes a single CIM Instance
256 from the target Namespace.
257
258 @param nameSpace The nameSpace parameter is a string that defines
259 the target namespace. See defintion of
260 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
261
262 @param instanceName The <TT>instanceName</TT> input parameter defines
263 the name (model path) of the Instance to be deleted.
264
265 @return If successful, the specified Instance MUST have been removed
266 by the CIM Server.
267
268 If unsuccessful, one of the following status codes MUST be returned by
269 this method, where the first applicable error in the list (starting
270 with the first element of the list, and working down) is the error
271 returned. Any additional method-specific interpretation of the error in
272 is given in parentheses.
273
274 mike 1.2 <UL>
275 <LI>CIM_ERR_ACCESS_DENIED
276 <LI>CIM_ERR_NOT_SUPPORTED
277 <LI>CIM_ERR_INVALID_NAMESPACE
278 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
279 unrecognized or otherwise incorrect parameters)
280 <LI>CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the
281 specified namespace)
282 <LI>CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
283 CIM Instance does not exist in the specified namespace)
284 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
285 </UL>
286 */
287 virtual void deleteInstance(
288 const String& nameSpace,
289 const CIMReference& instanceName) = 0;
290
291 /** The <TT>createClass</TT> method creates a single CIM Class in
292 the target Namespace. The Class MUST NOT already exist. The NewClass input
293 parameter defines the new Class. The proposed definition MUST be a correct
294 Class definition according to the CIM specification.
295 mike 1.2
296 In processing the creation of the new Class, the following rules MUST be
297 conformed to by the CIM Server:
298
299 Any CLASSORIGIN and PROPAGATED attributes in the NewClass MUST be ignored by
300 the Server. If the new Class has no Superclass, the NewClass parameter
301 defines a new base Class. The Server MUST ensure that all Properties and
302 Methods of the new Class have a CLASSORIGIN attribute whose value is the
303 name of the new Class. If the new Class has a Superclass, the NewClass
304 parameter defines a new Subclass of that Superclass. The Superclass MUST
305 exist. The Server MUST ensure that:
306
307 <UL>
308 <LI>Any Properties, Methods or Qualifiers in the Subclass not defined in
309 the Superclass are created as new elements of the Subclass. In
310 particular the Server MUST set the CLASSORIGIN attribute on the new
311 Properties and Methods to the name of the Subclass, and ensure that all
312 other Properties and Methods preserve their CLASSORIGIN attribute value
313 from that defined in the Superclass
314
315 If a CIMProperty is defined in the Superclass and in the Subclass, the
316 mike 1.2 value assigned to that property in the Subclass (including NULL) becomes
317 the default value of the property for the Subclass. If a CIMProperty or
318 CIMMethod of the Superclass is not specified in the Subclass, then that
319 CIMProperty or CIMMethod is inherited without modification by the
320 Subclass
321
322 <LI>Any Qualifiers defined in the Superclass with a TOSUBCLASS attribute
323 value of true MUST appear in the resulting Subclass. Qualifiers in the
324 Superclass with a TOSUBCLASS attribute value of false MUST NOT be
325 propagated to the Subclass . Any CIMQualifier propagated from the
326 Superclass cannot be modified in the Subclass if the OVERRIDABLE
327 attribute of that CIMQualifier was set to false in the Superclass. It is
328 a
329 Client error to specify such a CIMQualifier in the NewClass with a
330 different definition to that in the Superclass (where definition
331 encompasses the name, type and flavor attribute settings of the
332 <QUALIFIER> element, and the value of the CIMQualifier).
333 </LI>
334 </UL>
335
336 @param nameSpace The nameSpace parameter is a string that defines the target
337 mike 1.2 namespace. See defintion of
338 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
339
340 @param newClass The <TT>newClass<?TT> input parameter defines the new Class.
341
342 @return If successful, the specified Class MUST have been created by the CIM
343 Server.
344
345 If unsuccessful, one of the following status codes MUST be returned by this
346 method, where the first applicable error in the list (starting with the
347 first element of the list, and working down) is the error returned. Any
348 additional method-specific interpretation of the error in is given in
349 parentheses.
350 <UL>
351 <LI>CIM_ERR_ACCESS_DENIED
352 <LI>CIM_ERR_NOT_SUPPORTED
353 <LI>CIM_ERR_INVALID_NAMESPACE
354 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
355 unrecognized or otherwise incorrect parameters)
356 <LI>CIM_ERR_ALREADY_EXISTS (the CIM Class already exists)
357 <LI>CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a
358 mike 1.2 non-existent superclass)
359 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
360 </UL>
361 */
362 virtual void createClass(
363 const String& nameSpace,
364 const CIMClass& newClass) = 0;
365
366 /** The <TT>createInstance</TT> method creates a single CIM
367 Instance in the target Namespace. The Instance MUST NOT already exist.
368
369 In processing the creation of the new Instance, the following rules MUST be
370 conformed to by the CIM Server:
371
372 Any CLASSORIGIN and PROPAGATED attributes in the NewInstance MUST be ignored
373 by the Server.
374
375 The Server MUST ensure that:
376
377 <UL>
378 <LI>Any Qualifiers in the Instance not defined in the Class are created
379 mike 1.2 as new elements of the Instance.
380 <LI>All Properties of the Instance preserve their CLASSORIGIN attribute
381 value from that defined in the Class.
382 <LI>If a CIMProperty is specified in the ModifiedInstance parameter, the
383 value assigned to that property in the Instance (including NULL) becomes
384 the value of the property for the Instance. Note that it is a Client
385 error to specify a CIMProperty that does not belong to the Class.
386 <LI>If a CIMProperty of the Class is not specified in the Instance, then
387 that CIMProperty is inherited without modification by the Instance.
388 <LI>Any Qualifiers defined in the Class with a TOINSTANCE attribute
389 value of true appear in the Instance. Qualifiers in the
390 Class with a TOINSTANCE attribute value of false MUST NOT be propagated
391 to the Instance.
392 <LI>Any CIMQualifier propagated from the Class cannot be modified in the
393 Instance if the OVERRIDABLE attribute of that CIMQualifier was set to
394 false
395 in the Class. It is a Client error to specify such a CIMQualifier in the
396 NewInstance with a different definition to that in the Class (where
397 definition encompasses the name, type and flavor attribute settings of
398 the <QUALIFIER> element, and the value of the CIMQualifier).
399 </UL>
400 mike 1.2
401 @param nameSpace The nameSpace parameter is a string that defines the target
402 namespace. See defintion of
403 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
404
405 @param newInstance The <TT>newInstance</TT> input parameter defines the new
406 Instance. The proposed definition MUST be a correct Instance definition for
407 the underlying CIM Class according to the CIM specification.
408
409 @return If successful, the return value defines the object path of the new
410 CIM Instance relative to the target Namespace (i.e. the Model Path as
411 defined by the CIM specification), created by the CIM Server. It is
412 returned in case one or more of the new keys of the Instance are allocated
413 dynamically during the creation process rather than specified in the
414 request.
415
416 If unsuccessful, one of the following status codes MUST be returned by this
417 method, where the first applicable error in the list (starting with the
418 first element of the list, and working down) is the error returned. Any
419 additional method-specific interpretation of the error in is given in
420 parentheses.
421 mike 1.2
422 <UL>
423 <LI>CIM_ERR_ACCESS_DENIED
424 <LI>CIM_ERR_NOT_SUPPORTED
425 <LI>CIM_ERR_INVALID_NAMESPACE
426 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
427 unrecognized or otherwise incorrect parameters)
428 <LI>CIM_ERR_INVALID_CLASS (the CIM Class of which this is to be a new
429 Instance does not exist)
430 <LI>CIM_ERR_ALREADY_EXISTS (the CIM Instance already exists)
431 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
432 </UL>
433 */
434 virtual void createInstance(
435 const String& nameSpace,
436 const CIMInstance& newInstance) = 0;
437
438
439 /** The <TT>modifyClass</TT> method modifies an existing CIM Class in the
440 target Namespace.
441
442 mike 1.2 The Class MUST already exist. The <TT>ModifiedClass</TT>
443 input parameter defines the set of changes (which MUST be correct
444 amendments to the CIM Class as defined by the CIM Specification) to be made
445 to the current class definition.
446
447 In processing the modifcation of the Class, the following rules MUST be
448 conformed to by the CIM Server.
449
450 <UL>
451 <LI>Any <TT>CLASSORIGIN</TT> and <TT>PROPAGATED</TT> attributes in the
452 <TT>ModifiedClass</TT> MUST be ignored by the Server.
453 <LI>If the modified Class has no Superclass,
454 the<TT>ModifiedClass</TT> parameter defines modifications to a base Class.
455 The Server MUST ensure that:
456 <UL>
457 <LI>All Properties and Methods of the modified Class have a
458 <TT>CLASSORIGIN</TT> attribute whose value is the name of this Class.
459 <LI>Any Properties, Methods or Qualifiers in the existing Class
460 definition which do not appear in the <FONT face="Courier
461 New">ModifiedClass</TT> parameter are removed from the resulting
462 modified Class.</LI>
463 mike 1.2 </UL>
464 <LI>If the modified Class has a Superclass,the <TT>ModifiedClass</TT>
465 parameter defines modifications to a Subclass of that Superclass. The
466 Superclass MUST exist, and the Client MUST NOT change the name of the
467 Superclass in the modified Subclass. The Server MUST ensure that:
468 <UL>
469 <LI>Any Properties, Methods or Qualifiers in the Subclass not
470 defined in the Superclass are created as elements of the Subclass. In
471 particular the Server MUST set the <TT>CLASSORIGIN</TT> attribute on the
472 new Properties and Methods to the name of the Subclass, and MUST ensure
473 that all other Properties and Methods preserve their
474 <TT>CLASSORIGIN</TT> attribute value from that defined in the
475 Superclass.
476 <LI>Any CIMProperty, CIMMethod or CIMQualifier previously defined in the
477 Subclass
478 but not defined in the Superclass, and which is not present in the
479 <TT>ModifiedClass</TT> parameter, is removed from the Subclass.
480 <LI>If a CIMProperty is specified in the <TT>ModifiedClass</TT>
481 parameter, the value assigned to that property therein (including
482 NULL) becomes the default value of the property for the Subclass.
483 <LI>If a CIMProperty or CIMMethod of the Superclass is not specified in
484 mike 1.2 the
485 Subclass, then that CIMProperty or CIMMethod is inherited
486 without modification by the Subclass (so that any previous changes to
487 such an Element in the Subclass are lost).
488 <LI>If a CIMQualifier in the Superclass is not specified in the
489 Subclass, and the CIMQualifier is defined in the Superclass with a
490 <TT>TOSUBCLASS</TT> attribute value of <TT>true</TT>, then the
491 CIMQualifier
492 MUST still be present in the resulting modified Subclass (it is not
493 possible to remove a propagated CIMQualifier from a Subclass).
494 <LI>Any CIMQualifier propagated from the Superclass cannot be
495 modified in the Subclass if the <TT>OVERRIDABLE</TT> attribute of
496 that CIMQualifier was set to <TT>false</TT> in the Superclass. It is a
497 Client error to specify such a CIMQualifier in the
498 <TT>ModifiedClass</TT>
499 with a different definition to that in the Superclass (where definition
500 encompasses the name, type and flavor attribute settings of the
501 <TT><QUALIFIER></TT> element, and the value of the CIMQualifier).
502 <LI>Any Qualifiers defined in the Superclass with a <TT>TOSUBCLASS</TT>
503 attribute value of <TT>false</TT> MUST NOT be propagated to the
504 Subclass.</LI> </UL>
505 mike 1.2 </LI></UL>
506
507 @param nameSpace The nameSpace parameter is a string that defines the target
508 namespace. See defintion of
509 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
510
511 @param modifiedClass The <TT>modifiedClass</TT>
512 input parameter defines the set of changes (which MUST be correct
513 amendments to the CIM Class as defined by the CIM Specification) to be made
514 to the current class definition.
515
516 @return If successful, the specified Class MUST have been updated by
517 the CIM Server.
518
519 The request to modify the Class MUST fail if the Server cannot update any
520 existing Subclasses or Instances of that Class in a consistent manner.
521
522 @return If unsuccessful, one of the following status codes MUST be
523 returned by this method, where the first applicable error in the list
524 (starting with the first element of the list, and working down) is the
525 error returned. Any additional method-specific interpretation of the error
526 mike 1.2 in is given in parentheses.
527
528 <UL>
529 <LI>CIM_ERR_ACCESS_DENIED
530 <LI>CIM_ERR_NOT_SUPPORTED
531 <LI>CIM_ERR_INVALID_NAMESPACE
532 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
533 duplicate, unrecognized or otherwise incorrect parameters)
534 <LI>CIM_ERR_NOT_FOUND (the CIM Class does not
535 exist)
536 <LI>CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class
537 declares a non-existent or incorrect superclass)
538 <LI>CIM_ERR_CLASS_HAS_CHILDREN (the modification could
539 not be performed because it was not possible to update the subclasses of
540 the Class in a consistent fashion)
541 <LI>CIM_ERR_CLASS_HAS_INSTANCES (the modification could
542 not be performed because it was not possible to update
543 the instances of the Class in a consistent fashion)
544 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
545 </LI></UL>
546 */
547 mike 1.2 virtual void modifyClass(
548 const String& nameSpace,
549 const CIMClass& modifiedClass) = 0;
550
551 /** The <TT>modifyInstance</TT> method modifies an existing CIM
552 Instance in the target Namespace.
553
554 @param nameSpace The nameSpace parameter is a string that defines the target
555 namespace. See defintion of
556 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
557
558 @param modifiedInstance The <TT>modifiedInstance</TT> input parameter
559 identifies the name of the Instance to be modified, and defines the set of
560 changes (which MUST be correct amendments to the Instance as
561 defined by the CIM Specification) to be made to the current Instance
562 definition.
563
564 In processing the modifcation of the Instance, the following rules MUST
565 be conformed to by the CIM Server:
566
567 <UL>
568 mike 1.2 <LI>Any <TT>CLASSORIGIN</TT> and <TT>PROPAGATED</TT> attributes in the
569 <TT>ModifiedInstance</TT> MUST be ignored by the Server.
570 <LI>The Class MUST exist, and the Client MUST NOT change
571 the name of the Class in the modified Instance. The Server MUST ensure
572 that:
573 <UL>
574 <LI>Any Qualifiers in the Instance not defined in
575 the Class are created as new elements of the Instance.
576 <LI>All Properties of the Instance preserve their
577 <TT>CLASSORIGIN</TT> attribute value from that defined in the Class.
578 <LI>Any CIMQualifier previously defined in the Instance but not
579 defined in the Class, and which is not present in the
580 <TT>ModifiedInstance</TT> parameter, is removed from the Instance.
581
582 <LI>If a CIMProperty is specified in the <TT>ModifiedInstance</TT>
583 parameter, the value assigned to that property therein
584 (including NULL) becomes the value of the property for the Instance.
585 Note that it is a Client error to specify a CIMProperty that does not
586 belong to the Class.
587
588 <LI>If a CIMProperty of the Class is not specified in the Instance,
589 mike 1.2 then that CIMProperty is inherited without modification by the Instance
590 (so that any previous changes to that CIMProperty in the Instance are
591 lost).
592 <LI>Any Qualifiers defined in the Class with a <TT>TOINSTANCE</TT>
593 attribute value of <TT>true</TT> appear in the Instance (it is not
594 possible remove a propagated CIMQualifier from an Instance. Qualifiers
595 in the Class with a <TT>TOINSTANCE</TT> attribute value of <TT>false</TT>
596 MUST NOT be propagated to the Instance.
597 <LI>Any CIMQualifier propagated from the Class cannot be modified by the
598 Server if the <TT>OVERRIDABLE</TT> attribute of that CIMQualifier was
599 set to <TT>false</TT> in the Class. It is a Client error to specify such
600 a CIMQualifier in the <TT>ModifiedInstance</TT> with a different
601 definition to that in the Class (where definition encompasses the name,
602 type and flavor attribute settings of the
603 <TT><QUALIFIER></TT> element, and the value of the CIMQualifier).
604 <LI>Any CIMQualifier propagated from the Class cannot be modified in
605 the Instance if the <TT>OVERRIDABLE</TT> attribute of that CIMQualifier
606 was
607 set to <TT>false</TT> in the Class. It is a Client error to specify such
608 a CIMQualifier in the <TT>ModifiedInstance</TT> with a different
609 definition
610 mike 1.2 to that in the Class (where definition encompasses the name, type and
611 flavor attribute settings of the <TT><QUALIFIER></TT>
612 element, and the value of the CIMQualifier).</LI>
613 </UL>
614 </LI></UL>
615
616 @return If successful, the specified Instance MUST have been updated by the
617 CIM Server.
618
619 If unsuccessful, one of the following status codes MUST be returned by
620 this method, where the first applicable error in the list (starting with the
621 first element of the list, and working down) is the error returned. Any
622 additional method-specific interpretation of the error in is given in
623 parentheses
624
625 <UL>
626 <LI>CIM_ERR_ACCESS_DENIED
627 <LI>CIM_ERR_NOT_SUPPORTED
628 <LI>CIM_ERR_INVALID_NAMESPACE
629 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
630 duplicate, unrecognized or otherwise incorrect parameters)
631 mike 1.2 <LI>CIM_ERR_INVALID_CLASS (the CIM Class of which this is
632 to be a new Instance does not exist)
633 <LI>CIM_ERR_NOT_FOUND (the CIM Instance does not exist)
634 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI></UL>
635 */
636 virtual void modifyInstance(
637 const String& nameSpace,
638 const CIMInstance& modifiedInstance) = 0;
639
640
641 /** The <TT>enumerateClasses</TT> method is used to enumerate subclasses of
642 a CIM Class in the target Namespace.
643
644 @param nameSpace The nameSpace parameter is a string that defines the target
645 namespace. See defintion of
646 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
647
648 @param className The <TT>className</TT> input parameter defines the Class
649 that is the basis for the enumeration.
650
651 @param deepInheritance If the <TT>deepInheritance</TT> input
652 mike 1.2 parameter is <TT>true</TT>, this specifies that all subclasses of
653 the specified Class should be returned (if the <TT>ClassName</TT> input
654 parameter is absent, this implies that all Classes in the target Namespace
655 should be returned). If <TT>false</TT>, only immediate child
656 subclasses are returned (if the <TT>ClassName</TT> input parameter is
657 NULL, this implies that all base Classes in the target Namespace should be
658 returned).
659
660 @param localOnly If the <TT>localOnly</TT> input parameter is
661 <TT>true</TT>, it specifies that, for each returned Class, only elements
662 (properties, methods and qualifiers) overriden within the definition of
663 that Class are included. If <TT>false</TT>, all elements are
664 returned. This parameter therefore effects a CIM Server-side mechanism
665 to filter certain elements of the returned object based on whether or not
666 they have been propagated from the parent Class (as defined by the
667 <TT>PROPAGATED</TT> attribute).
668
669 @param includeQualifiers If the <TT>includeQualifiers</TT> input parameter
670 is <TT>true</TT>, this specifies that all Qualifiers for each Class
671 (including Qualifiers on the Class and on any returned Properties, Methods
672 or CIMMethod Parameters) MUST be included as <TT><QUALIFIER></TT>
673 mike 1.2 elements in the response. If false no <TT><QUALIFIER></TT> elements
674 are present in each returned Class.
675
676 @param includeClassOrigin If the <TT>IncludeClassOrigin</TT> input
677 parameter is <TT>true</TT>, this specifies that the <TT>CLASSORIGIN</TT>
678 attribute MUST be present on all appropriate elements in each returned
679 Class. If false, no <TT>CLASSORIGIN</TT> attributes are present in each
680 returned Class.
681
682 @return If successful, the method returns zero or more Classes that meet the
683 required criteria.
684
685 If unsuccessful, one of the following status codes MUST be returned by
686 this method, where the first applicable error in the list (starting with the
687 first element of the list, and working down) is the error returned. Any
688 additional method-specific interpretation of the error in is given in
689 parentheses.
690
691 <UL>
692 <LI>CIM_ERR_ACCESS_DENIED
693 <LI>CIM_ERR_NOT_SUPPORTED
694 mike 1.2 <LI>CIM_ERR_INVALID_NAMESPACE
695 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
696 duplicate, unrecognized or otherwise incorrect parameters)
697 <LI>CIM_ERR_INVALID_CLASS (the CIM Class that is the
698 basis for this enumeration does not exist)
699 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
700 </LI>
701 </UL>
702 */
703 virtual Array<CIMClass> enumerateClasses(
704 const String& nameSpace,
705 const String& className = String::EMPTY,
706 Boolean deepInheritance = false,
707 Boolean localOnly = true,
708 Boolean includeQualifiers = true,
709 Boolean includeClassOrigin = false) = 0;
710
711
712 /** The <TT>enumerateClassNames</TT> operation is used to enumerate the
713 names of subclasses of a CIM Class in the target Namespace.
714
715 mike 1.2 @param nameSpace The nameSpace parameter is a string that defines the target
716 namespace. See defintion of
717 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
718
719 @param className The <TT>className</TT> input parameter defines the Class
720 that is the basis for the enumeration.
721
722 @param deepInheritance If the <TT>deepInheritance</TT> input parameter is
723 true, this specifies that the names of all subclasses of the specified Class
724 should be returned (if the ClassName input parameter is absent, this implies
725 that the names of all Classes in the target Namespace should be returned).
726 If false, only the names of immediate child subclasses are returned (if the
727 className input parameter is NULL, this implies that the names of all base
728 Classes in the target Namespace should be returned). @return If successful,
729 the method returns zero or more names of Classes that meet the requested
730 criteria. If unsuccessful, one of the following status codes MUST be
731 returned by this method, where the first applicable error in the list
732 (starting with the first element of the list, and working down) is the error
733 returned. Any additional method-specific interpretation of the error in is
734 given in parentheses.
735
736 mike 1.2 <UL>
737 <LI>CIM_ERR_ACCESS_DENIED
738 <LI>CIM_ERR_NOT_SUPPORTED
739 <LI>CIM_ERR_INVALID_NAMESPACE
740 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
741 duplicate, unrecognized or otherwise incorrect parameters)
742 <LI>CIM_ERR_INVALID_CLASS (the CIM Class that is the
743 basis for this enumeration does not exist)
744 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
745 </UL>
746 */
747 virtual Array<String> enumerateClassNames(
748 const String& nameSpace,
749 const String& className = String::EMPTY,
750 Boolean deepInheritance = false) = 0;
751
752
753 /** The <TT>enumerateInstances</TT> method enumerates instances of a CIM
754 Class in the target Namespace.
755
756 @param nameSpace The nameSpace parameter is a string that defines the target
757 mike 1.2 namespace. See defintion of
758 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
759
760 @param className The <TT>className</TT> input parameter defines the
761 Class that is the basis for the enumeration.
762
763 @param localOnly If the <TT>localOnly</TT> input parameter is
764 <TT>true</TT>, this specifies that, for each returned Instance,
765 only elements (properties and qualifiers) overriden within the
766 definition of that Instance are included. If <TT>false</TT>,
767 all elements are returned. This parameter therefore effects a CIM
768 Server-side mechanism to filter certain elements of the returned object
769 based on whether or not they have been propagated from the parent
770 Class (as defined by the <TT>PROPAGATED</TT> attribute).
771
772 Only elements (properties, methods and qualifiers) defined or
773 overridden within the class are included in the response. Propagated
774 properties are not included because their values are based on another class’
775 information. If not specified, all elements of the class’ definition are
776 returned. Note: When instances are returned, the InstanceName must include
777 all keys, including propagated keys. Therefore, these attributes are
778 mike 1.2 included in the name part of the method response, but not in the value
779 information.
780
781 @param deepInheritance If the <TT>deepInheritance</TT> input
782 parameter is <TT>true</TT>, this specifies that, for each
783 returned Instance of the Class, all properties of the Instance MUST
784 be present (subject to constraints imposed by the other
785 parameters), including any which were added by subclassing the specified
786 Class. If <TT>false</TT>, each returned Instance includes only
787 properties defined for the specified Class.
788
789 The Enumerate Instances operation returns the same number of instances
790 regardless of whether or not the DeepInheritance flag is set. The
791 DeepInheritance flag is only used to determine whether or not the subclass
792 property values should be returned.
793
794 @param includeQualifiersIf the <TT>includeQualifiers</TT> input
795 parameter is <TT>true</TT>, this specifies that all Qualifiers
796 for each Instance (including Qualifiers on the Instance
797 and on any returned Properties) MUST be included as
798 <TT><QUALIFIER></TT> elements in the response. If false no
799 mike 1.2 <TT><QUALIFIER></TT> elements are present in each
800 returned Instance.
801
802 @param includeClassOrigin If the <TT>includeClassOrigin</TT> input
803 parameter is <TT>true</TT>, this specifies that the
804 <TT>CLASSORIGIN</TT> attribute MUST be present on all appropriate
805 elements in each returned Instance. If false, no
806 <TT>CLASSORIGIN</TT> attributes are present in each returned
807 Instance.
808
809 @param propertyList If the <TT>propertyList</TT> input parameter is not
810 <TT>NULL</TT>, the members of the array define one or more CIMProperty
811 names. Each returned Instance MUST NOT include elements
812 for any Properties missing from this list. Note that if
813 <TT>LocalOnly</TT> is specified as <TT>true</TT> (or
814 <TT>DeepInheritance</TT> is specified as <TT>false</TT>) this acts as an
815 additional filter on the set of Properties returned (for example,
816 if CIMProperty <TT>A</TT> is included in the
817 <TT>PropertyList</TT> but <TT>LocalOnly</TT> is set to true and
818 <TT>A</TT> is not local to a returned Instance, then it will not be
819 included in that Instance). If the <TT>PropertyList</TT> input parameter
820 mike 1.2 is an empty array this signifies that no Properties are included in each
821 returned Instance. If the <TT>PropertyList</TT> input parameter is
822 NULL this specifies that all Properties (subject to the conditions
823 expressed by the other parameters) are included in each returned
824 Instance.
825
826 If the <TT>propertyList</TT> contains duplicate elements,
827 the Server MUST ignore the duplicates but otherwise process the request
828 normally. If the <TT>PropertyList</TT> contains elements which are
829 invalid CIMProperty names for any target Instance, the Server MUST
830 ignore such entries but otherwise process the request normally.
831
832 @return If successful, the method returns zero or more named
833 Instances that meet the required criteria.
834
835 If unsuccessful, one of the following status codes MUST be returned
836 by this method, where the first applicable error in the list (starting
837 with the first element of the list, and working down) is the error
838 returned. Any additional method-specific interpretation of the error in
839 is given in parentheses.
840
841 mike 1.2 <UL>
842 <LI>CIM_ERR_ACCESS_DENIED
843 <LI>CIM_ERR_NOT_SUPPORTED
844 <LI>CIM_ERR_INVALID_NAMESPACE
845 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
846 duplicate, unrecognized or otherwise incorrect parameters)
847 <LI>CIM_ERR_INVALID_CLASS (the CIM Class that is the
848 basis for this enumeration does not exist)
849 <LI>CIM_ERR_FAILED (some other unspecified erroroccurred)</LI>
850 </UL>
851 */
852
853 virtual Array<CIMInstance> enumerateInstances(
854 const String& nameSpace,
855 const String& className,
856 Boolean deepInheritance = true,
857 Boolean localOnly = true,
858 Boolean includeQualifiers = false,
859 Boolean includeClassOrigin = false,
860 const Array<String>& propertyList = EmptyStringArray()) = 0;
861
862 mike 1.2 /** The <TT>enumerateInstanceNames</TT> operation enumerates the
863 names (model paths) of the instances of a CIM Class in the target Namespace.
864
865 @param nameSpace The nameSpace parameter is a string that defines the target
866 namespace. See defintion of
867 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
868
869 @param className The <TT>className</TT> input parameter defines the Class
870 that is the basis for the enumeration.
871
872 @return If successful, the method returns zero or more names of Instances
873 (model paths) that meet the requsted criteria.
874
875 If unsuccessful, one of the following status codes MUST be returned by this
876 method, where the first applicable error in the list (starting with the
877 first element of the list, and working down) is the error returned. Any
878 additional method-specific interpretation of the error in is given in
879 parentheses.
880
881 <UL>
882 <LI>CIM_ERR_ACCESS_DENIED
883 mike 1.2 <LI>CIM_ERR_NOT_SUPPORTED
884 <LI>CIM_ERR_INVALID_NAMESPACE
885 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
886 duplicate, unrecognized or otherwise incorrect parameters)
887 <LI>CIM_ERR_INVALID_CLASS (the CIM Class that is the
888 basis for this enumeration does not exist)
889 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
890 </UL>
891 */
892
893 virtual Array<CIMReference> enumerateInstanceNames(
894 const String& nameSpace,
895 const String& className) = 0;
896
897 /** The <TT>execQuery</TT> is used to execute a query against the target
898 Namespace.
899
900 @param nameSpace The nameSpace parameter is a string that defines the target
901 namespace. See defintion of
902 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
903
904 mike 1.2 @param queryLanguage The <TT>queryLanguage</TT> String input parameter
905 defines the query language in which the Query parameter is expressed.
906
907 @param query The <TT>query</TT> input parameter defines the query to be
908 executed.
909
910 @return If successful, the method returns zero or more CIM Classes or
911 Instances that correspond to the results set of the query.
912
913 If unsuccessful, one of the following status codes MUST be returned by this
914 method, where the first applicable error in the list (starting with the
915 first element of the list, and working down) is the error returned. Any
916 additional method-specific interpretation of the error in is given in
917 parentheses.
918
919 <UL>
920 <LI>CIM_ERR_ACCESS_DENIED
921 <LI>CIM_ERR_NOT_SUPPORTED
922 <LI>CIM_ERR_INVALID_NAMESPACE
923 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
924 duplicate, unrecognized or otherwise incorrect parameters)
925 mike 1.2 <LI>CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED (the requested query language is
926 not recognized)
927 <LI>CIM_ERR_INVALID_QUERY (the query is not a valid query in the
928 specified query language)
929 <LI>CIM_ERR_FAILED (some other unspecified error ccurred)</LI>
930 </UL>
931 */
932
933 virtual Array<CIMInstance> execQuery(
934 const String& queryLanguage,
935 const String& query) = 0;
936
937 /** The <TT>Associators</TT> method enumerates CIM Objects
938 (Classes or Instances) that are associated to a particular source CIM
939 Object.
940
941 @param nameSpace The nameSpace parameter is a string that defines the target
942 namespace. See defintion of
943 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
944
945 @param objectName The <TT>objectName</TT> input parameter defines the source
946 mike 1.2 CIM Object whose associated Objects are to be returned. This may be either
947 a Class name or Instance name (model path).
948
949 @param assocClass The <TT>assocClass</TT> input parameter, if not NULL, MUST
950 be a valid CIM Association Class name. It acts as a filter on the returned
951 set of Objects by mandating that each returned Object MUST be associated to
952 the source Object via an Instance of this Class or one of its subclasses.
953
954 @param resultClass The <TT>resultClass</TT> input parameter, if not NULL,
955 MUST be a valid CIM Class name. It acts as a filter on the returned set of
956 Objects by mandating that each returned Object MUST be either an Instance of
957 this Class (or one of its subclasses) or be this Class (or one of its
958 subclasses).
959
960 @param role The <TT>role</TT> input parameter, if not NULL, MUST be a valid
961 CIMProperty name. It acts as a filter on the returned set of Objects by
962 mandating that each returned Object MUST be associated to the source Object
963 via an Association in which the source Object plays the specified role (i.e.
964 the name of the CIMProperty in the Association Class that refers to the
965 source object MUST match the value of this parameter).
966
967 mike 1.2 @param resultRole The <TT>resultRole</TT> input parameter, if not NULL, MUST
968 be a valid CIMProperty name. It acts as a filter on the returned set of
969 Objects by mandating that each returned Object MUST be associated to the
970 source Object via an Association in which the returned Object plays the
971 specified role (i.e. the name of the CIMProperty in the Association Class
972 that refers to the returned Object MUST match the value of this parameter).
973
974 @param includeQualifiers If the <TT>includeQualifiers</TT> input parameter
975 is true, this specifies that all Qualifiers for each Object (including
976 Qualifiers on the Object and on any returned Properties) MUST be included as
977 <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are
978 present in each returned Object.
979
980 @param includeClassOrigin If the <TT>includeClassOrigin</TT> input parameter
981 is true, this specifies that the CLASSORIGIN attribute MUST be present on
982 all appropriate elements in each returned Object. If false, no CLASSORIGIN
983 attributes are present in each returned Object.
984
985 @param propertyList If the <TT>propertyList</TT> input parameter is not
986 NULL, the members of the array define one or more CIMProperty names. Each
987 returned Object MUST NOT include elements for any Properties missing from
988 mike 1.2 this list. Note that if LocalOnly is specified as true (or DeepInheritance
989 is specified as false) this acts as an additional filter on the set of
990 Properties returned (for example, if CIMProperty A is included in the
991 PropertyList but LocalOnly is set to true and A is not local to a returned
992 Instance, then it will not be included in that Instance). If the
993 PropertyList input parameter is an empty array this signifies that no
994 Properties are included in each returned Object. If the PropertyList input
995 parameter is NULL this specifies that all Properties (subject to the
996 conditions expressed by the other parameters) are included in each returned
997 Object.
998
999 If the propertyList contains duplicate elements, the Server MUST ignore the
1000 duplicates but otherwise process the request normally. If the PropertyList
1001 contains elements which are invalid CIMProperty names for any target Object,
1002 the Server MUST ignore such entries but otherwise process the request
1003 normally.
1004
1005 Clients SHOULD NOT explicitly specify properties in the PropertyList
1006 parameter unless they have specified a non-NULL value for the ResultClass
1007 parameter.
1008
1009 mike 1.2 @return If successful, the method returns zero or more CIM Classes or
1010 Instances meeting the requested criteria. Since it is possible for CIM
1011 Objects from different hosts or namespaces to be associated, each returned
1012 Object includes location information.
1013
1014 If unsuccessful, one of the following status codes MUST be returned by this
1015 method, where the first applicable error in the list (starting with the
1016 first element of the list, and working down) is the error returned. Any
1017 additional method-specific interpretation of the error in is given in
1018 parentheses.
1019
1020 <UL>
1021 <LI>CIM_ERR_ACCESS_DENIED
1022 <LI>CIM_ERR_NOT_SUPPORTED
1023 <LI>CIM_ERR_INVALID_NAMESPACE
1024 <LI>CIM_ERR_INVALID_PARAMETER (including
1025 missing,duplicate, unrecognized or
1026 otherwise incorrect parameters)
1027 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
1028 </UL>
1029 */
1030 mike 1.2 virtual Array<CIMObjectWithPath> associators(
1031 const String& nameSpace,
1032 const CIMReference& objectName,
1033 const String& assocClass = String::EMPTY,
1034 const String& resultClass = String::EMPTY,
1035 const String& role = String::EMPTY,
1036 const String& resultRole = String::EMPTY,
1037 Boolean includeQualifiers = false,
1038 Boolean includeClassOrigin = false,
1039 const Array<String>& propertyList = EmptyStringArray()) = 0;
1040
1041 /** The <TT>associatorNames</TT> operation enumerates the names of
1042 CIM Objects (Classes or Instances) that are associated to a particular
1043 source CIM Object.
1044
1045 @param nameSpace The nameSpace parameter is a string that defines the target
1046 namespace. See defintion of
1047 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1048
1049 @param objectName The <TT>objectName</TT> input parameter defines the source
1050 CIM Object whose associated names are to be returned. This is either a Class
1051 mike 1.2 name or Instance name (model path).
1052
1053 @param assocClass The <TT>assocClass</TT> input parameter, if not NULL,
1054 MUST be a valid CIM Association Class name. It acts as a filter on the
1055 returned set of names by mandating that each returned name identifies an
1056 Object that MUST be associated to the source Object via an Instance of this
1057 Class or one of its subclasses.
1058
1059 @param resultClass The <TT>resultClass</TT> input parameter, if not NULL,
1060 MUST be a valid CIM Class name. It acts as a filter on the returned set of
1061 names by mandating that each returned name identifies an Object that MUST be
1062 either an Instance of this Class (or one of its subclasses) or be this Class
1063 (or one of its subclasses).
1064
1065 @param role The <TT>role</TT> input parameter, if not NULL, MUST be a valid
1066 CIMProperty name. It acts as a filter on the returned set of names by
1067 mandating that each returned name identifies an Object that MUST be
1068 associated to the source Object via an Association in which the source
1069 Object plays the specified role (i.e. the name of the CIMProperty in the
1070 Association Class that refers to the source Object MUST match the value of
1071 this parameter).
1072 mike 1.2
1073 @param resultRole The <TT>resultRole</TT> input parameter, if not
1074 <TT>NULL</TT>, MUST be a valid CIMProperty name. It acts as a filter on the
1075 returned set of names by mandating that each returned name identifies an
1076 Object that MUST be associated to the source Object via an Association in
1077 which the named returned Object plays the specified role (i.e. the name of
1078 the CIMProperty in the Association Class that refers to the returned Object
1079 MUST match the value of this parameter).
1080
1081 @return If successful, the method returns zero or more full CIM Class paths
1082 or Instance paths of Objects meeting the requested criteria. Since it is
1083 possible for CIM Objects from different hosts or namespaces to be
1084 associated, each returned path is an absolute path that includes host and
1085 namespace information.
1086
1087 If unsuccessful, one of the following status codes MUST be returned by this
1088 method, where the first applicable error in the list (starting with the
1089 first element of the list, and working down) is the error returned. Any
1090 additional method-specific interpretation of the error in is given in
1091 parentheses.
1092
1093 mike 1.2 <UL>
1094 <LI>CIM_ERR_ACCESS_DENIED
1095 <LI>CIM_ERR_NOT_SUPPORTED
1096 <LI>CIM_ERR_INVALID_NAMESPACE;
1097 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
1098 duplicate, unrecognized or otherwise incorrect parameters)
1099 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
1100 </UL>
1101 */
1102 virtual Array<CIMReference> associatorNames(
1103 const String& nameSpace,
1104 const CIMReference& objectName,
1105 const String& assocClass = String::EMPTY,
1106 const String& resultClass = String::EMPTY,
1107 const String& role = String::EMPTY,
1108 const String& resultRole = String::EMPTY) = 0;
1109
1110 /** The <TT>references</TT> operation enumerates the association
1111 objects that refer to a particular target CIM Object (Class or Instance).
1112
1113 @param The NameSpace parameter is a string that defines the target
1114 mike 1.2 namespace \Ref{NAMESPACE}
1115
1116 @param nameSpace The nameSpace parameter is a string that defines the target
1117 namespace. See defintion of
1118 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1119
1120 @param objectName The <TT>objectName</TT> input parameter defines the target
1121 CIM Object whose referring Objects are to be returned. This is either a
1122 Class name or Instance name (model path).
1123
1124 @param resultClass The <TT>resultClass</TT> input parameter, if not NULL,
1125 MUST be a valid CIM Class name. It acts as a filter on the returned set of
1126 Objects by mandating that each returned Object MUST be an Instance of this
1127 Class (or one of its subclasses), or this Class (or one of its subclasses).
1128
1129 @param role The <TT>role</TT> input parameter, if not NULL, MUST be a valid
1130 CIMProperty name. It acts as a filter on the returned set of Objects by
1131 mandating that each returned Objects MUST refer to the target Object via a
1132 CIMProperty whose name matches the value of this parameter.
1133
1134 @param includeQualifiers. If the <TT>includeQualifiers</TT> input parameter
1135 mike 1.2 is true, this specifies that all Qualifiers for each Object (including
1136 Qualifiers on the Object and on any returned Properties) MUST be included as
1137 <QUALIFIER> elements in the response. If false no <QUALIFIER> elements are
1138 present in each returned Object.
1139
1140 @param includeClassOrigin If the <TT>includeClassOrigin</TT> input parameter
1141 is true, this specifies that the CLASSORIGIN attribute MUST be present on
1142 all appropriate elements in each returned Object. If false, no CLASSORIGIN
1143 attributes are present in each returned Object.
1144
1145 @param propertyList If the <TT>propertyList</TT> input parameter is not
1146 NULL, the members of the array define one or more CIMProperty names. Each
1147 returned Object MUST NOT include elements for any Properties missing from
1148 this list. Note that if LocalOnly is specified as true (or DeepInheritance
1149 is specified as false) this acts as an additional filter on the set of
1150 Properties returned (for example, if CIMProperty A is included in the
1151 PropertyList but LocalOnly is set to true and A is not local to a returned
1152 Instance, then it will not be included in that Instance). If the
1153 PropertyList input parameter is an empty array this signifies that no
1154 Properties are included in each returned Object. If the PropertyList input
1155 parameter is NULL this specifies that all Properties (subject to the
1156 mike 1.2 conditions expressed by the other parameters) are included in each returned
1157 Object.
1158
1159 If the PropertyList contains duplicate elements, the Server MUST ignore the
1160 duplicates but otherwise process the request normally. If the PropertyList
1161 contains elements which are invalid CIMProperty names for any target Object,
1162 the Server MUST ignore such entries but otherwise process the request
1163 normally.
1164
1165 Clients SHOULD NOT explicitly specify properties in the PropertyList
1166 parameter unless they have specified a non-NULL value for the ResultClass
1167 parameter.
1168
1169 @return If successful, the method returns zero or more CIM Classes or
1170 Instances meeting the requested criteria. Since it is possible for CIM
1171 Objects from different hosts or namespaces to be associated, each returned
1172 Object includes location information.
1173
1174 If unsuccessful, one of the following status codes MUST be returned by this
1175 method, where the first applicable error in the list (starting with the
1176 first element of the list, and working down) is the error returned. Any
1177 mike 1.2 additional method-specific interpretation of the error in is given in
1178 parentheses.
1179
1180 <UL>
1181 <LI>CIM_ERR_ACCESS_DENIED
1182 <LI>CIM_ERR_NOT_SUPPORTED
1183 <LI>CIM_ERR_INVALID_NAMESPACE
1184 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
1185 duplicate, unrecognized or otherwise incorrect parameters)
1186 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
1187 </UL>
1188 */
1189 virtual Array<CIMObjectWithPath> references(
1190 const String& nameSpace,
1191 const CIMReference& objectName,
1192 const String& resultClass = String::EMPTY,
1193 const String& role = String::EMPTY,
1194 Boolean includeQualifiers = false,
1195 Boolean includeClassOrigin = false,
1196 const Array<String>& propertyList= EmptyStringArray()) = 0;
1197
1198 mike 1.2 /**
1199 The <TT>referenceNames</TT> operation enumerates the association
1200 objects that refer to a particular target CIM Object (Class or Instance).
1201
1202 @param The NameSpace parameter is a string that defines the target
1203 namespace \Ref{NAMESPACE}
1204
1205 @param nameSpace The nameSpace parameter is a string that defines the target
1206 namespace. See defintion of
1207 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1208
1209 @param objectName The <TT>objectName</TT> input parameter defines the target
1210 CIM Object whose referring object names are to be returned. It may be either
1211 a Class name or an Instance name (model path).
1212
1213 @param resultClass The <TT>resultClass</TT> input parameter, if not NULL,
1214 MUST be a valid CIM Class name. It acts as a filter on the returned set of
1215 Object Names by mandating that each returned Object CIMName MUST identify an
1216 Instance of this Class (or one of its subclasses), or this Class (or one of
1217 its subclasses).
1218
1219 mike 1.2 @param role The <TT>role</TT> input parameter, if not NULL, MUST be a valid
1220 CIMProperty name. It acts as a filter on the returned set of Object Names by
1221 mandating that each returned Object CIMName MUST identify an Object that
1222 refers to the target Instance via a CIMProperty whose name matches the value
1223 of this parameter.
1224
1225 @return If successful,the method returns the names of zero or more full CIM
1226 Class paths or Instance paths of Objects meeting the requested criteria.
1227 Since it is possible for CIM Objects from different hosts or namespaces to
1228 be associated, each returned path is an absolute path that includes host and
1229 namespace information.
1230
1231 If unsuccessful, one of the following status codes MUST be returned by this
1232 method, where the first applicable error in the list (starting with the
1233 first element of the list, and working down) is the error returned. Any
1234 additional method-specific interpretation of the error in is given in
1235 parentheses.
1236 <UL>
1237 <LI>CIM_ERR_ACCESS_DENIED
1238 <LI>CIM_ERR_NOT_SUPPORTED
1239 <LI>CIM_ERR_INVALID_NAMESPACE
1240 mike 1.2 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
1241 unrecognized or otherwise incorrect parameters)
1242 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
1243 </UL>
1244 */
1245 virtual Array<CIMReference> referenceNames(
1246 const String& nameSpace,
1247 const CIMReference& objectName,
1248 const String& resultClass = String::EMPTY,
1249 const String& role = String::EMPTY) = 0;
1250
1251 /**
1252 The <TT>getProperty</TT>operation is used to retrieve a single property
1253 value from a CIM Instance in the target Namespace.
1254
1255 @param nameSpace The nameSpace parameter is a string that defines the target
1256 namespace. See defintion of
1257 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1258
1259 @param instanceName The <TT>instanceName</TT> input parameter specifies the
1260 name of the Instance (model path) from which the CIMProperty value is
1261 mike 1.2 requested. \\Ref{INSTANCENAME}
1262
1263 @param propertyName The <TT>propertyName</TT> input parameter specifies the
1264 name of the CIMProperty whose value is to be returned.
1265
1266 @return If successful, the return value specifies the value of the requested
1267 CIMProperty. If the value is NULL then no element is returned.
1268
1269 If unsuccessful, one of the following status codes MUST be returned by this
1270 method, where the first applicable error in the list (starting with the
1271 first element of the list, and working down) is the error returned. Any
1272 additional method-specific interpretation of the error in is given in
1273 parentheses.
1274 <UL>
1275 <LI>CIM_ERR_ACCESS_DENIED
1276 <LI>CIM_ERR_INVALID_NAMESPACE
1277 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
1278 unrecognized or otherwise incorrect parameters)
1279 <LI>CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
1280 namespace)
1281 <LI>CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested CIM
1282 mike 1.2 Instance does not exist in the specified namespace)
1283 <LI><LI>CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the
1284 requested CIMProperty does not)
1285 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
1286 </UL>
1287 */
1288 virtual CIMValue getProperty(
1289 const String& nameSpace,
1290 const CIMReference& instanceName,
1291 const String& propertyName) = 0;
1292
1293 /** The <TT>setProperty</TT> operation sets a single property value in a CIM
1294 Instance in the target Namespace.
1295
1296 @param nameSpace The nameSpace parameter is a string that defines the target
1297 namespace. See defintion of
1298 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1299
1300 @param instanceName The <TT>instanceName</TT> input parameter specifies the
1301 name of the Instance (model path) for which the CIMProperty value is to be
1302 updated.
1303 mike 1.2
1304 @param propertyName The <TT>propertyName</TT> input parameter specifies the
1305 name of the CIMProperty whose value is to be updated.
1306
1307 @param newValue The NewValue input parameter specifies the new value for the
1308 CIMProperty (which may be NULL).
1309
1310 @return If unsuccessful, one of the following status codes MUST be returned
1311 by this method, where the first applicable error in the list (starting with
1312 the first element of the list, and working down) is the error returned. Any
1313 additional method-specific interpretation of the error in is given in
1314 parentheses.
1315 <UL>
1316 <LI>CIM_ERR_ACCESS_DENIED
1317 <LI>CIM_ERR_INVALID_NAMESPACE
1318
1319 <LI>CIM_ERR_INVALID_PARAMETER (including
1320 missing,duplicate, unrecognized or otherwise incorrect parameters)
1321
1322 <LI>CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
1323 namespace)
1324 mike 1.2 <LI>CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
1325 CIM Instance does not exist in the specified namespace)
1326 <LI>CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the
1327 requested CIMProperty does not)
1328 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
1329 </UL>
1330 */
1331 virtual void setProperty(
1332 const String& nameSpace,
1333 const CIMReference& instanceName,
1334 const String& propertyName,
1335 const CIMValue& newValue = CIMValue()) = 0;
1336
1337 /** The <TT>getQualifier</TT> operation retrieves a single CIMQualifier
1338 declaration from the target Namespace.
1339
1340 @param nameSpace The nameSpace parameter is a string that defines the target
1341 namespace. See defintion of
1342 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1343
1344 @param qualifierName The <TT>qualifierName</TT> input parameter identifies
1345 mike 1.2 the CIMQualifier whose declaration to be retrieved.
1346
1347 @return If successful, the method returns the CIMQualifier declaration for
1348 the named CIMQualifier.
1349
1350 If unsuccessful, one of the following status codes MUST be returned by this
1351 method, where the first applicable error in the list (starting with the
1352 first element of the list, and working down) is the error returned. Any
1353 additional method-specific interpretation of the error in is given in
1354 parentheses.
1355
1356 <UL>
1357 <LI>CIM_ERR_ACCESS_DENIED
1358 <LI>CIM_ERR_NOT_SUPPORTED
1359 <LI>CIM_ERR_INVALID_NAMESPACE
1360 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
1361 duplicate, unrecognized or otherwise incorrect parameters)
1362 <LI>CIM_ERR_INVALID_CLASS (the CIM Class does not exist in the specified
1363 namespace)
1364 <LI>CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
1365 CIM Instance does not exist in the specified namespace)
1366 mike 1.2 <LI>CIM_ERR_NO_SUCH_PROPERTY (the CIM Instance does exist, but the
1367 requested CIMProperty does not)
1368 <LI>CIM_ERR_TYPE_MISMATCH (the supplied value is incompatible with the
1369 type of the CIMProperty)
1370 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
1371 </UL>
1372 */
1373 virtual CIMQualifierDecl getQualifier(
1374 const String& nameSpace,
1375 const String& qualifierName) = 0;
1376
1377
1378 /** The <TT>setQualifier</TT> creates or update a single CIMQualifier
1379 declaration in the target Namespace. If the CIMQualifier declaration
1380 already
1381 exists it is overwritten.
1382
1383 @param NameSpace The NameSpace parameter is a string that defines the target
1384 namespace \Ref{NAMESPACE}
1385
1386 @param nameSpace The nameSpace parameter is a string that defines the target
1387 mike 1.2 namespace. See defintion of
1388 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1389
1390 @param CIMQualifierDecl The <TT>CIMQualifierDecl</TT> input parameter
1391 defines the CIMQualifier Declaration to be added to the Namespace.
1392
1393 @return If successful, the CIMQualifier declaration MUST have been added to
1394 the target Namespace. If a CIMQualifier declaration with the same
1395 CIMQualifier name already existed, then it MUST have been replaced by the
1396 new declaration.
1397
1398 If unsuccessful, one of the following status codes MUST be returned
1399 by this method, where the first applicable error in the list (starting with
1400 the first element of the list, and working down) is the error returned. Any
1401 additional method-specific interpretation of the error in is given in
1402 parentheses.
1403
1404 <UL>
1405 <LI>CIM_ERR_ACCESS_DENIED
1406 <LI>CIM_ERR_NOT_SUPPORTED
1407 <LI>CIM_ERR_INVALID_NAMESPACE
1408 mike 1.2 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
1409 duplicate, unrecognized or otherwise incorrect parameters)
1410 <LI>CIM_ERR_NOT_FOUND (the requested CIMQualifier declaration did not
1411 exist)
1412 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
1413 </LI>
1414 </UL>
1415 */
1416 virtual void setQualifier(
1417 const String& nameSpace,
1418 const CIMQualifierDecl& qualifierDecl) = 0;
1419
1420 /** The <TT>deleteQualifier</TT> operation deletes a single CIMQualifier
1421 declaration from the target Namespace.
1422
1423 @param nameSpace The nameSpace parameter is a string that defines the target
1424 namespace. See defintion of
1425 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1426
1427 @param qualifierName The <TT>qualifierName</TT> input parameter identifies
1428 the CIMQualifier whose declaration to be deleted. @return If successful, the
1429 mike 1.2 specified CIMQualifier declaration MUST have been deleted from the
1430 Namespace.
1431
1432 @return If unsuccessful, one of the following status codes MUST be returned
1433 by this method, where the first applicable error in the list (starting with
1434 the first element of the list, and working down) is the error returned. Any
1435 additional method-specific interpretation of the error in is given in
1436 parentheses.
1437
1438 <UL>
1439 <LI>CIM_ERR_ACCESS_DENIED
1440 <LI>CIM_ERR_NOT_SUPPORTED
1441 <LI>CIM_ERR_INVALID_NAMESPACE
1442 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
1443 duplicate, unrecognized or otherwise incorrect parameters)
1444 <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
1445 </UL>
1446
1447 */
1448 virtual void deleteQualifier(
1449 const String& nameSpace,
1450 mike 1.2 const String& qualifierName) = 0;
1451
1452
1453 /** The <TT>enumerateQualifiers</TT> operation is used to enumerate
1454 CIMQualifier declarations from the target Namespace.
1455
1456 @param nameSpace The nameSpace parameter is a string that defines the target
1457 namespace. See defintion of
1458 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1459
1460 @return If successful, the method returns zero or more CIMQualifier
1461 declarations.
1462
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
1465 first element of the list, and working down) is the error returned. Any
1466 additional method-specific interpretation of the error in is given in
1467 parentheses.
1468
1469 <UL>
1470 <LI>CIM_ERR_ACCESS_DENIED
1471 mike 1.2 <LI>CIM_ERR_NOT_SUPPORTED
1472 <LI>CIM_ERR_INVALID_NAMESPACE
1473 <LI>CIM_ERR_INVALID_PARAMETER (including missing,
1474 duplicate, unrecognized or otherwise incorrect parameters)
1475 <LI>CIM_ERR_NOT_FOUND (the requested CIMQualifier declaration did not
1476 exist)
1477 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
1478 </LI>
1479 </UL>
1480 */
1481 virtual Array<CIMQualifierDecl> enumerateQualifiers(
1482 const String& nameSpace) = 0;
1483
1484
1485 /** Execute an extrinsic CIM method.
1486 Any CIM Server is assumed to support extrinsic methods. Extrinsic methods
1487 are defined by the Schema supported by the Cim Server. If a CIM Server does
1488 not support extrinsic method invocations, it MUST (subject to the
1489 considerations described in the rest of this section) return the error code
1490 CIM_ERR_NOT_SUPPORTED to any request to execute an extrinsic method. This
1491 allows a CIM client to determine that all attempts to execute extrinsic
1492 mike 1.2 methods will fail.
1493
1494 @param nameSpace The nameSpace parameter is a string that defines the target
1495 namespace. See defintion of
1496 \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.
1497
1498 @param instanceName The <TT>instanceName</TT> parameter is a CIMReference
1499 that defines the CIM instance for which the method is defined
1500
1501 @param methodName The <TT>methodName</TT> parameter is a String with the
1502 name of the method to be executed.
1503
1504 @param inParameters This parameter defines an array of input parameters for
1505 the method execution
1506
1507 @param outParameters This parameter defines an array of parameters returned
1508 by the executed method
1509
1510 @return If the Cim Server is unable to perform the extrinsic method
1511 invocation, one of the following status codes MUST be returned by the
1512 CimServer, where the first applicable error in the list (starting with the
1513 mike 1.2 first element of the list, and working down) is the error returned. Any
1514 additional specific interpretation of the error is given in parentheses.
1515
1516 ATTN: We have not defined the CIMValue returned
1517 <UL>
1518
1519 <LI>CIM_ERR_ACCESS_DENIED
1520 <LI>CIM_ERR_NOT_SUPPORTED (the CimServer does not support extrinsic
1521 method invocations)
1522 <LI>CIM_ERR_INVALID_NAMESPACE
1523 <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
1524 unrecognized or otherwise incorrect parameters)
1525 <LI>CIM_ERR_NOT_FOUND (the target CIM Class or instance does not exist
1526 in the specified namespace)
1527 <LI>CIM_ERR_METHOD_NOT_FOUND
1528 <LI>CIM_ERR_METHOD_NOT_AVAILABLE (the CimServer is unable to honor the
1529 invocation request)
1530 <LI>CIM_ERR_FAILED (some other unspecified error occurred)
1531 </UL>
1532
1533 */
1534 mike 1.2 virtual CIMValue invokeMethod(
1535 const String& nameSpace,
1536 const CIMReference& instanceName,
1537 const String& methodName,
1538 const Array<CIMValue>& inParameters,
1539 Array<CIMValue>& outParameters) = 0;
1540 };
1541
1542 PEGASUS_NAMESPACE_END
1543
1544 #endif /* Pegasus_Operations_h */
1545
|
Return to
CIMOperations.h
CVS log
Up to [Pegasus] / pegasus / doc