1 thilo.boehm 1.1.2.1 //%LICENSE////////////////////////////////////////////////////////////////
2 //
3 // Licensed to The Open Group (TOG) under one or more contributor license
4 // agreements. Refer to the OpenPegasusNOTICE.txt file distributed with
5 // this work for additional information regarding copyright ownership.
6 // Each contributor licenses this file to you under the OpenPegasus Open
7 // Source License; you may not use this file except in compliance with the
8 // License.
9 //
10 // Permission is hereby granted, free of charge, to any person obtaining a
11 // copy of this software and associated documentation files (the "Software"),
12 // to deal in the Software without restriction, including without limitation
13 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
14 // and/or sell copies of the Software, and to permit persons to whom the
15 // Software is furnished to do so, subject to the following conditions:
16 //
17 // The above copyright notice and this permission notice shall be included
18 // in all copies or substantial portions of the Software.
19 //
20 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
21 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
22 thilo.boehm 1.1.2.1 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
23 // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
24 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
25 // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
26 // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
27 //
28 //////////////////////////////////////////////////////////////////////////
29 //
30 //%/////////////////////////////////////////////////////////////////////////////
31
32 #ifndef _SCMOINSTANCE_H_
33 #define _SCMOINSTANCE_H_
34
35
36 #include <Pegasus/Common/Config.h>
37 #include <Pegasus/Common/Linkage.h>
38 #include <Pegasus/Common/SCMO.h>
|
39 thilo.boehm 1.1.2.2 #include <Pegasus/Common/SCMOClass.h>
|
40 thilo.boehm 1.1.2.1
41 PEGASUS_NAMESPACE_BEGIN
42
43 #define PEGASUS_SCMB_INSTANCE_MAGIC 0xD00D1234
44
45 class SCMOClass;
46
47 class PEGASUS_COMMON_LINKAGE SCMOInstance
48 {
49 public:
50
51 /**
52 * Creating a SCMOInstance using a SCMOClass.
53 * @param baseClass A SCMOClass.
54 */
55 SCMOInstance(SCMOClass baseClass);
56
57 /**
58 * Copy constructor for the SCMO instance, used to implement refcounting.
59 * @param theSCMOClass The instance for which to create a copy
60 * @return
61 thilo.boehm 1.1.2.1 */
62 SCMOInstance(const SCMOInstance& theSCMOInstance )
63 {
64 inst.hdr = theSCMOInstance.inst.hdr;
65 Ref();
66 }
67
68 /**
69 * Destructor is decrementing the refcount. If refcount is zero, the
70 * singele chunk memory object is deallocated.
71 */
72 ~SCMOInstance()
73 {
74 Unref();
75 }
76
77 /**
78 * Builds a SCMOInstance based on this SCMOClass.
79 * The method arguments determine whether qualifiers are included,
80 * the class origin attributes are included,
81 * and which properties are included in the new instance.
82 thilo.boehm 1.1.2.1 * @param baseClass The SCMOClass of this instance.
83 * @param includeQualifiers A Boolean indicating whether qualifiers in
84 * the class definition (and its properties) are to be added to the
85 * instance. The TOINSTANCE flavor is ignored.
86 * @param includeClassOrigin A Boolean indicating whether ClassOrigin
87 * attributes are to be added to the instance.
88 * @param propertyList Is an NULL terminated array of char* to property
89 * names defining the properties that are included in the created instance.
90 * If the propertyList is NULL, all properties are included to the instance.
91 * If the propertyList is empty, no properties are added.
92 *
93 * Note that this function does NOT generate an error if a property name
94 * is supplied that is NOT in the class;
95 * it simply does not add that property to the instance.
96 *
97 */
98 SCMOInstance(
99 SCMOClass baseClass,
100 Boolean includeQualifiers,
101 Boolean includeClassOrigin,
102 const char** propertyList);
103 thilo.boehm 1.1.2.1
104 /**
105 * Builds a SCMOInstance from the given SCMOClass and copies all
106 * CIMInstance data into the new SCMOInstance.
107 * @param baseClass The SCMOClass of this instance.
108 * @param cimInstance A CIMInstace of the same class.
|
109 thilo.boehm 1.1.2.4 * @exception Exception if class name and name space does not match.
110 * @exception
111 * Exception if CIMInstance has more key bindings then the SCMOClass.
112 * @exception
113 * Exception if a key binding is not found as a key property
114 * of the SCMOClass.
115 * @exception Exception if a key binding does not match
116 * the class definition.
117 * @exception Exception if a property is not part of class definition.
118 * @exception Exception if a property does not match the class definition.
|
119 thilo.boehm 1.1.2.1 */
120 SCMOInstance(SCMOClass baseClass, const CIMInstance& cimInstance);
121
122 /**
|
123 thilo.boehm 1.1.2.4 * Builds a SCMOInstance from the given SCMOClass and copies all
124 * CIMObjectPath data into the new SCMOInstance.
125 * @param baseClass The SCMOClass of this instance.
126 * @param cimInstance A CIMObjectpath of the same class.
127 * @exception Exception if class name and name space does not match.
128 * @exception
129 * Exception if CIMInstance has more key bindings then the SCMOClass.
130 * @exception
131 * Exception if a key binding is not found as a key property
132 * of the SCMOClass.
133 * @exception Exception if a key binding does not match
134 * the class definition.
135 */
136 SCMOInstance(SCMOClass baseClass, const CIMObjectPath& cimObj);
137
138 /**
|
139 thilo.boehm 1.1.2.1 * Converts the SCMOInstance into a CIMInstance.
140 * It is a deep copy of the SCMOInstance into the CIMInstance.
141 * @param cimInstance An empty CIMInstance.
142 */
|
143 thilo.boehm 1.1.2.6 SCMO_RC getCIMInstance(CIMInstance& cimInstance) const;
|
144 thilo.boehm 1.1.2.1
145 /**
146 * Makes a deep copy of the instance.
147 * This creates a new copy of the instance.
|
148 thilo.boehm 1.1.2.5 * @param objectPathOnly If set to true, only the object path relevant parts
149 * host name and key bindings are part of the cloned instance.
|
150 thilo.boehm 1.1.2.1 * @return A new copy of the SCMOInstance object.
151 */
|
152 thilo.boehm 1.1.2.5 SCMOInstance clone(Boolean objectPathOnly = false) const;
|
153 thilo.boehm 1.1.2.1
154 /**
|
155 r.kieninger 1.1.2.9 * Retrieves the objectpath part of the SCMOInstance as an instance
156 * of class CIMObjectPath. .
157 * @param cimObj Reference to an instantiated CIMObjectPath to be
158 * populated with the data from the SCMOInstance.
159 * @return void
160 */
161 void getCIMObjectPath(CIMObjectPath& cimObj) const;
162
163 /**
|
164 thilo.boehm 1.1.2.1 * Returns the number of properties of the instance.
165 * @param Number of properties
166 */
167 Uint32 getPropertyCount() const;
168
169 /**
170 * Gets the property name, type, and value addressed by a positional index.
171 * The property name and value has to be copied by the caller !
172 * @param pos The positional index of the property
173 * @param pname Returns the property name as '\0' terminated string.
174 * Has to be copied by caller.
175 * It is set to NULL if rc != SCMO_OK.
176 * @param pvalue Returns a pointer to the value of property.
177 * The value has to be copied by the caller !
178 * It returns NULL if rc != SCMO_OK.
179 * If the value is an array, the
180 * value array is stored in continuous memory.
181 * e.g. If the CIMType is CIMTYPE_UINT32:
182 * value = (void*)Uint32[0 to size-1]
183 * If it is an array of CIMTYPE_STRING, an array
184 * of char* to the string values is returned.
185 thilo.boehm 1.1.2.1 * This array has to be freed by the caller !
186 * @param type Returns the CIMType of the property
187 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
188 * @param isArray Returns if the value is an array.
189 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
190 * @param size Returns the size of the array.
191 * If it is not an array, 0 is returned.
192 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
193 *
194 * @return SCMO_OK
195 * SCMO_NULL_VALUE : The value is a null value.
196 * SCMO_INDEX_OUT_OF_BOUND : Given index not found
197 *
198 */
199 SCMO_RC getPropertyAt(
200 Uint32 pos,
201 const char** pname,
202 CIMType& type,
203 const void** pvalue,
204 Boolean& isArray,
205 Uint32& size ) const;
206 thilo.boehm 1.1.2.1
207 /**
208 * Gets the type and value of the named property.
209 * The value has to be copied by the caller !
210 * @param name The property name
211 * @param pvalue Returns a pointer to the value of property.
212 * The value has to be copied by the caller !
213 * It returns NULL if rc != SCMO_OK.
214 * If the value is an array, the
215 * value array is stored in continuous memory.
216 * e.g. If the CIMType is CIMTYPE_UINT32:
217 * value = (void*)Uint32[0 to size-1]
218 * If it is an array of CIMTYPE_STRING, an array
219 * of char* to the string values is returned.
220 * This array has to be freed by the caller !
221 * @param type Returns the CIMType of the property
222 * It is invalid if rc == SCMO_NOT_FOUND.
223 * @param isArray Returns if the value is an array.
224 * It is invalid if rc == SCMO_NOT_FOUND.
225 * @param size Returns the size of the array.
226 * If it is not an array, 0 is returned.
227 thilo.boehm 1.1.2.1 * It is invalid if rc == SCMO_NOT_FOUND.
228 *
229 * @return SCMO_OK
230 * SCMO_NULL_VALUE : The value is a null value.
231 * SCMO_NOT_FOUND : Given property name not found.
232 */
233 SCMO_RC getProperty(
234 const char* name,
235 CIMType& type,
236 const void** pvalue,
237 Boolean& isArray,
238 Uint32& size ) const;
239
240 /**
241 * Set/replace a property in the instance.
242 * If the class origin is specified, it is honored at identifying
243 * the property within the instance.
244 * Note: Only properties which are already part of the instance/class can
245 * be set/replaced.
246 * @param name The name of the property to be set.
247 * @param type The CIMType of the property
248 thilo.boehm 1.1.2.1 * @param value A pointer to property value.
249 * The value is copied into the instance
250 * If the value == NULL, a null value is assumed.
251 * If the value is an array, the
252 * value array must be stored in continuous memory.
253 * e.g. If the CIMType is CIMTYPE_UINT32:
254 * value = (void*)Uint32[0 to size-1]
255 * @param isArray Indicate that the value is an array. Default false.
256 * @param size Returns the size of the array. If not an array this
257 * this parameter is ignorer. Default 0.
258 * @param origin The class originality of the property.
259 * If NULL, then it is ignorred. Default NULL.
260 * @return SCMO_OK
261 * SCMO_NOT_SAME_ORIGIN : The property name was found, but
262 * the origin was not the same.
263 * SCMO_NOT_FOUND : Given property name not found.
264 * SCMO_WRONG_TYPE : Named property has the wrong type.
265 * SCMO_NOT_AN_ARRAY : Named property is not an array.
266 * SCMO_IS_AN_ARRAY : Named property is an array.
267 */
268 SCMO_RC setPropertyWithOrigin(
269 thilo.boehm 1.1.2.1 const char* name,
270 CIMType type,
271 void* value,
272 Boolean isArray=false,
273 Uint32 size = 0,
274 const char* origin = NULL);
275
276 /**
|
277 thilo.boehm 1.1.2.3 * Rebuild of the key bindings from the property values
|
278 thilo.boehm 1.1.2.1 * if no or incomplete key properties are set on the instance.
|
279 thilo.boehm 1.1.2.3 * @exception NoSuchProperty
|
280 thilo.boehm 1.1.2.1 */
|
281 thilo.boehm 1.1.2.2 void buildKeyBindingsFromProperties();
|
282 thilo.boehm 1.1.2.1
283 /**
284 * Set/replace a property filter on an instance.
285 * The filter is a white list of property names.
286 * A property part of the list can be accessed by name or index and
287 * is eligible to be returned to requester.
288 * Key properties can not be filtered. They are always a part of the
289 * instance. If a key property is not part of the property list,
290 * it will not be filtered out.
291 * @param propertyList Is an NULL terminated array of char* to
292 * property names
293 */
294 void setPropertyFilter(const char **propertyList);
295
296 /**
297 * Gets the hash index for the named property. Filtering is ignored.
298 * @param theName The property name
299 * @param pos Returns the hash index.
300 * @return SCMO_OK
301 * SCMO_INVALID_PARAMETER: name was a NULL pointer.
302 * SCMO_NOT_FOUND : Given property name not found.
303 thilo.boehm 1.1.2.1 */
304 SCMO_RC getPropertyNodeIndex(const char* name, Uint32& pos) const;
305
306 /**
307 * Set/replace a property in the instance at node index.
|
308 thilo.boehm 1.1.2.4 * Note: If node is filtered, the property is not set but the return value
|
309 thilo.boehm 1.1.2.1 * is still SCMO_OK.
310 * @param index The node index.
311 * @param type The CIMType of the property
312 * @param value A pointer to property value.
313 * The value is copied into the instance
314 * If the value is an array, the
315 * value array must be stored in continuous memory.
316 * e.g. If the CIMType is CIMTYPE_UINT32:
317 * value = (void*)Uint32[0 to size-1]
318 * @param isArray Indicate that the value is an array. Default false.
319 * @param size The size of the array. If not an array this
320 * this parameter is ignorer. Default 0.
321 * @return SCMO_OK
322 * SCMO_INDEX_OUT_OF_BOUND : Given index not found
323 * SCMO_WRONG_TYPE : The property at given node index
324 * has the wrong type.
325 * SCMO_NOT_AN_ARRAY : The property at given node index
326 * is not an array.
327 * SCMO_IS_AN_ARRAY : The property at given node index
328 * is an array.
329 */
330 thilo.boehm 1.1.2.1 SCMO_RC setPropertyWithNodeIndex(
331 Uint32 node,
332 CIMType type,
333 void* value,
334 Boolean isArray=false,
335 Uint32 size = 0);
336
337 /**
338 * Set/replace the named key binding
339 * @param name The key binding name.
340 * @param type The type as CIMKeyBinding::Type.
341 * @parma value The value as string.
342 * @return SCMO_OK
|
343 thilo.boehm 1.1.2.8 * SCMO_INVALID_PARAMETER : Given name or pvalue
344 * is a NULL pointer.
|
345 thilo.boehm 1.1.2.1 * SCMO_TYPE_MISSMATCH : Given type does not
346 * match to key binding type
347 * SCMO_NOT_FOUND : Given property name not found.
348 */
349 SCMO_RC setKeyBinding(
350 const char* name,
351 CIMKeyBinding::Type type,
352 const char* pvalue);
353
354 /**
|
355 thilo.boehm 1.1.2.7 * Set/replace the named key binding
356 * @param node The node index of the key.
357 * @param type The type as CIMKeyBinding::Type.
358 * @parma value The value as string.
359 * @return SCMO_OK
|
360 thilo.boehm 1.1.2.8 * SCMO_INVALID_PARAMETER : Given pvalue is a NULL pointer.
|
361 thilo.boehm 1.1.2.7 * SCMO_TYPE_MISSMATCH : Given type does not
362 * match to key binding type
363 * SCMO_INDEX_OUT_OF_BOUND : Given index is our of range.
364 */
365 SCMO_RC setKeyBindingAt(
366 Uint32 node,
367 CIMKeyBinding::Type type,
368 const char* pvalue);
369
370 /**
|
371 thilo.boehm 1.1.2.1 * Gets the key binding count.
372 * @return the number of key bindings set.
373 */
374 Uint32 getKeyBindingCount();
375
376 /**
377 * Get the indexed key binding.
378 * @parm idx The key bining index
379 * @parm pname Returns the name.
380 * Has to be copied by caller.
381 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
382 * @param type Returns the type as CIMKeyBinding::Type.
383 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
384 * @parma pvalue Returns the value as string.
385 * Has to be copied by caller.
386 * It is only valid if rc == SCMO_OK.
387 * @return SCMO_OK
388 * SCMO_NULL_VALUE : The key binding is not set.
389 * SCMO_INDEX_OUT_OF_BOUND : Given index not found
390 *
391 */
392 thilo.boehm 1.1.2.1 SCMO_RC getKeyBindingAt(
393 Uint32 idx,
394 const char** pname,
395 CIMKeyBinding::Type& type,
396 const char** pvalue) const;
397
398 /**
399 * Get the named key binding.
400 * @parm name The name of the key binding.
401 * @param type Returns the type as CIMKeyBinding::Type.
402 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
403 * @parma value Returns the value as string.
404 * Has to be copied by caller.
405 * It is only valid if rc == SCMO_OK.
406 * @return SCMO_OK
407 * SCMO_NULL_VALUE : The key binding is not set.
408 * SCMO_NOT_FOUND : Given property name not found.
409 */
410 SCMO_RC getKeyBinding(
411 const char* name,
412 CIMKeyBinding::Type& ptype,
413 thilo.boehm 1.1.2.1 const char** pvalue) const;
414
415 /**
416 * Determines whether the object has been initialized.
417 * @return True if the object has not been initialized, false otherwise.
418 */
419 Boolean isUninitialized( ) const {return (inst.base == NULL); };
420
421 /**
422 * Determies if two objects are referencing to the same instance
423 * @return True if the objects are referencing to the some instance.
424 */
425 Boolean isSame(SCMOInstance& theInstance) const;
426
427 /**
428 * Get the host name of the instance. The caller has to make a copy !
429 * @return The host name as UTF8.
430 */
431 const char* getHostName() const;
432
433 /**
434 thilo.boehm 1.1.2.1 * Sets the provided host name at the instance.
435 * @param hostName The host name as UTF8.
436 */
437 void setHostName(const char* hostName);
438
439 /**
440 * Get the class name of the instance. The cabler has to make a copy !
441 * @return The class name as UTF8.
442 */
443 const char* getClassName() const;
444
445 /**
446 * Get the name space of the instance. The caller has to make a copy !
447 * @return The name space as UTF8.
448 */
449 const char* getNameSpace() const;
450
451 /**
452 * To indicate the export processing ( eg. XMLWriter )
453 * to include qualifiers for this instance.
454 */
455 thilo.boehm 1.1.2.1 void includeQualifiers()
456 {
457 inst.hdr->flags.includeQualifiers = true;
458 };
459
460 /**
461 * To indicate the export processing ( eg. XMLWriter )
462 * to NOT to include (exclude) qualifiers for this instance.
463 */
464 void excludeQualifiers()
465 {
466 inst.hdr->flags.includeQualifiers = false;
467 }
468
469 /**
470 * To indicate the export processing ( eg. XMLWriter )
471 * to include class origins for this instance.
472 */
473 void includeClassOrigins()
474 {
475 inst.hdr->flags.includeClassOrigin = true;
476 thilo.boehm 1.1.2.1 };
477
478 /**
479 * To indicate the export processing ( eg. XMLWriter )
480 * to NOT to include (exclude) class origins for this instance.
481 */
482 void excludeClassOrigins()
483 {
484 inst.hdr->flags.includeClassOrigin = false;
485 }
486
487 private:
488
489 void Ref()
490 {
491 inst.hdr->refCount++;
492 // printf("\ninst.hdr->refCount=%u\n",inst.hdr->refCount.get());
493 };
494
495 void Unref()
496 {
497 thilo.boehm 1.1.2.1 if (inst.hdr->refCount.decAndTestIfZero())
498 {
499 // printf("\ninst.hdr->refCount=%u\n",inst.hdr->refCount.get());
500 // The class has also be dereferenced.
501 delete inst.hdr->theClass;
502 free(inst.base);
503 inst.base=NULL;
504 }
505 else
506 {
507 // printf("\ninst.hdr->refCount=%u\n",inst.hdr->refCount.get());
508 }
509
510 };
511 /**
512 * A SCMOInstance can only be created by a SCMOClass
513 */
514 SCMOInstance();
515
516 void _initSCMOInstance(
517 SCMOClass* pClass,
518 thilo.boehm 1.1.2.1 Boolean inclQual,
519 Boolean inclOrigin);
520
521
522 SCMO_RC _getPropertyAtNodeIndex(
523 Uint32 pos,
524 const char** pname,
525 CIMType& type,
526 const void** pvalue,
527 Boolean& isArray,
528 Uint32& size ) const;
529
530 void _setPropertyAtNodeIndex(
531 Uint32 pos,
532 CIMType type,
533 void* value,
534 Boolean isArray,
535 Uint32 size);
536
|
537 thilo.boehm 1.1.2.4 void _setCIMValueAtNodeIndex(Uint32 node, CIMValueRep* valRep);
538
|
539 thilo.boehm 1.1.2.6 void _getCIMValueFromSCMBValue(
540 CIMValue& cimV,
541 const SCMBValue& scmbV,
542 const char * base) const;
543
544 CIMProperty _getCIMPropertyAtNodeIndex(Uint32 nodeIdx) const;
545
|
546 thilo.boehm 1.1.2.4 void _setCIMObjectPath(const CIMObjectPath& cimObj);
547
|
548 thilo.boehm 1.1.2.1 void* _getSCMBUnion(
549 CIMType type,
550 Boolean isArray,
551 Uint32 size,
552 Uint64 start,
553 char* base) const;
554
555 void _setSCMBUnion(
556 void* value,
557 CIMType type,
558 Boolean isArray,
559 Uint32 size,
560 Uint64 start);
561
|
562 thilo.boehm 1.1.2.4 static void _setUnionValue(
563 Uint64 start,
564 SCMBMgmt_Header** pmem,
565 CIMType type,
566 Union& u);
567
568 static void _setArrayValue(
569 Uint64 start,
570 SCMBMgmt_Header** pmem,
571 CIMType type,
572 Uint32& n,
573 Union& u);
574
|
575 thilo.boehm 1.1.2.1 SCMO_RC _getKeyBindingAtNodeIndex(
576 Uint32 pos,
577 const char** pname,
578 CIMKeyBinding::Type& ptype,
579 const char** pvalue) const;
580
|
581 thilo.boehm 1.1.2.5 void _copyKeyBindings(SCMOInstance& targetInst) const;
582
|
583 thilo.boehm 1.1.2.1 Uint32 _initPropFilterWithKeys();
584
585 void _setPropertyInPropertyFilter(Uint32 i);
586
587 Boolean _isPropertyInFilter(Uint32 i) const;
588
589 void _clearPropertyFilter();
590
|
591 thilo.boehm 1.1.2.3 void _setKeyBindingFromSCMBUnion(
|
592 thilo.boehm 1.1.2.4 CIMType type,
|
593 thilo.boehm 1.1.2.3 SCMBUnion& u,
594 SCMBDataPtr& keyNode);
|
595 thilo.boehm 1.1.2.2
|
596 thilo.boehm 1.1.2.1 union{
597 // To access the instance main structure
598 SCMBInstance_Main *hdr;
599 // To access the memory management header
600 SCMBMgmt_Header *mem;
601 // Generic access pointer
602 char *base;
603 }inst;
604
605 friend class SCMOClass;
606 friend class SCMODump;
607 };
608
609
610 PEGASUS_NAMESPACE_END
611
612
613 #endif
|