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