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
40 PEGASUS_NAMESPACE_BEGIN
41
42 #define PEGASUS_SCMB_INSTANCE_MAGIC 0xD00D1234
43 thilo.boehm 1.1.2.1
44 class SCMOClass;
45
46 class PEGASUS_COMMON_LINKAGE SCMOInstance
47 {
48 public:
49
50 /**
51 * Creating a SCMOInstance using a SCMOClass.
52 * @param baseClass A SCMOClass.
53 */
54 SCMOInstance(SCMOClass baseClass);
55
56 /**
57 * Copy constructor for the SCMO instance, used to implement refcounting.
58 * @param theSCMOClass The instance for which to create a copy
59 * @return
60 */
61 SCMOInstance(const SCMOInstance& theSCMOInstance )
62 {
63 inst.hdr = theSCMOInstance.inst.hdr;
64 thilo.boehm 1.1.2.1 Ref();
65 }
66
67 /**
68 * Destructor is decrementing the refcount. If refcount is zero, the
69 * singele chunk memory object is deallocated.
70 */
71 ~SCMOInstance()
72 {
73 Unref();
74 }
75
76 /**
77 * Builds a SCMOInstance based on this SCMOClass.
78 * The method arguments determine whether qualifiers are included,
79 * the class origin attributes are included,
80 * and which properties are included in the new instance.
81 * @param baseClass The SCMOClass of this instance.
82 * @param includeQualifiers A Boolean indicating whether qualifiers in
83 * the class definition (and its properties) are to be added to the
84 * instance. The TOINSTANCE flavor is ignored.
85 thilo.boehm 1.1.2.1 * @param includeClassOrigin A Boolean indicating whether ClassOrigin
86 * attributes are to be added to the instance.
87 * @param propertyList Is an NULL terminated array of char* to property
88 * names defining the properties that are included in the created instance.
89 * If the propertyList is NULL, all properties are included to the instance.
90 * If the propertyList is empty, no properties are added.
91 *
92 * Note that this function does NOT generate an error if a property name
93 * is supplied that is NOT in the class;
94 * it simply does not add that property to the instance.
95 *
96 */
97 SCMOInstance(
98 SCMOClass baseClass,
99 Boolean includeQualifiers,
100 Boolean includeClassOrigin,
101 const char** propertyList);
102
103 /**
104 * Builds a SCMOInstance from the given SCMOClass and copies all
105 * CIMInstance data into the new SCMOInstance.
106 thilo.boehm 1.1.2.1 * @param baseClass The SCMOClass of this instance.
107 * @param cimInstance A CIMInstace of the same class.
108 */
109 SCMOInstance(SCMOClass baseClass, const CIMInstance& cimInstance);
110
111 /**
112 * Converts the SCMOInstance into a CIMInstance.
113 * It is a deep copy of the SCMOInstance into the CIMInstance.
114 * @param cimInstance An empty CIMInstance.
115 */
116 void getCIMInstance(CIMInstance& cimInstance) const;
117
118 /**
119 * Makes a deep copy of the instance.
120 * This creates a new copy of the instance.
121 * @return A new copy of the SCMOInstance object.
122 */
123 SCMOInstance clone() const;
124
125 /**
126 * Returns the number of properties of the instance.
127 thilo.boehm 1.1.2.1 * @param Number of properties
128 */
129 Uint32 getPropertyCount() const;
130
131 /**
132 * Gets the property name, type, and value addressed by a positional index.
133 * The property name and value has to be copied by the caller !
134 * @param pos The positional index of the property
135 * @param pname Returns the property name as '\0' terminated string.
136 * Has to be copied by caller.
137 * It is set to NULL if rc != SCMO_OK.
138 * @param pvalue Returns a pointer to the value of property.
139 * The value has to be copied by the caller !
140 * It returns NULL if rc != SCMO_OK.
141 * If the value is an array, the
142 * value array is stored in continuous memory.
143 * e.g. If the CIMType is CIMTYPE_UINT32:
144 * value = (void*)Uint32[0 to size-1]
145 * If it is an array of CIMTYPE_STRING, an array
146 * of char* to the string values is returned.
147 * This array has to be freed by the caller !
148 thilo.boehm 1.1.2.1 * @param type Returns the CIMType of the property
149 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
150 * @param isArray Returns if the value is an array.
151 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
152 * @param size Returns the size of the array.
153 * If it is not an array, 0 is returned.
154 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
155 *
156 * @return SCMO_OK
157 * SCMO_NULL_VALUE : The value is a null value.
158 * SCMO_INDEX_OUT_OF_BOUND : Given index not found
159 *
160 */
161 SCMO_RC getPropertyAt(
162 Uint32 pos,
163 const char** pname,
164 CIMType& type,
165 const void** pvalue,
166 Boolean& isArray,
167 Uint32& size ) const;
168
169 thilo.boehm 1.1.2.1 /**
170 * Gets the type and value of the named property.
171 * The value has to be copied by the caller !
172 * @param name The property name
173 * @param pvalue Returns a pointer to the value of property.
174 * The value has to be copied by the caller !
175 * It returns NULL if rc != SCMO_OK.
176 * If the value is an array, the
177 * value array is stored in continuous memory.
178 * e.g. If the CIMType is CIMTYPE_UINT32:
179 * value = (void*)Uint32[0 to size-1]
180 * If it is an array of CIMTYPE_STRING, an array
181 * of char* to the string values is returned.
182 * This array has to be freed by the caller !
183 * @param type Returns the CIMType of the property
184 * It is invalid if rc == SCMO_NOT_FOUND.
185 * @param isArray Returns if the value is an array.
186 * It is invalid if rc == SCMO_NOT_FOUND.
187 * @param size Returns the size of the array.
188 * If it is not an array, 0 is returned.
189 * It is invalid if rc == SCMO_NOT_FOUND.
190 thilo.boehm 1.1.2.1 *
191 * @return SCMO_OK
192 * SCMO_NULL_VALUE : The value is a null value.
193 * SCMO_NOT_FOUND : Given property name not found.
194 */
195 SCMO_RC getProperty(
196 const char* name,
197 CIMType& type,
198 const void** pvalue,
199 Boolean& isArray,
200 Uint32& size ) const;
201
202 /**
203 * Set/replace a property in the instance.
204 * If the class origin is specified, it is honored at identifying
205 * the property within the instance.
206 * Note: Only properties which are already part of the instance/class can
207 * be set/replaced.
208 * @param name The name of the property to be set.
209 * @param type The CIMType of the property
210 * @param value A pointer to property value.
211 thilo.boehm 1.1.2.1 * The value is copied into the instance
212 * If the value == NULL, a null value is assumed.
213 * If the value is an array, the
214 * value array must be stored in continuous memory.
215 * e.g. If the CIMType is CIMTYPE_UINT32:
216 * value = (void*)Uint32[0 to size-1]
217 * @param isArray Indicate that the value is an array. Default false.
218 * @param size Returns the size of the array. If not an array this
219 * this parameter is ignorer. Default 0.
220 * @param origin The class originality of the property.
221 * If NULL, then it is ignorred. Default NULL.
222 * @return SCMO_OK
223 * SCMO_NOT_SAME_ORIGIN : The property name was found, but
224 * the origin was not the same.
225 * SCMO_NOT_FOUND : Given property name not found.
226 * SCMO_WRONG_TYPE : Named property has the wrong type.
227 * SCMO_NOT_AN_ARRAY : Named property is not an array.
228 * SCMO_IS_AN_ARRAY : Named property is an array.
229 */
230 SCMO_RC setPropertyWithOrigin(
231 const char* name,
232 thilo.boehm 1.1.2.1 CIMType type,
233 void* value,
234 Boolean isArray=false,
235 Uint32 size = 0,
236 const char* origin = NULL);
237
238 /**
239 * Rebuilds the key bindings off the property values
240 * if no or incomplete key properties are set on the instance.
241 */
242 void rebuildKeyProperties();
243
244 /**
245 * Set/replace a property filter on an instance.
246 * The filter is a white list of property names.
247 * A property part of the list can be accessed by name or index and
248 * is eligible to be returned to requester.
249 * Key properties can not be filtered. They are always a part of the
250 * instance. If a key property is not part of the property list,
251 * it will not be filtered out.
252 * @param propertyList Is an NULL terminated array of char* to
253 thilo.boehm 1.1.2.1 * property names
254 */
255 void setPropertyFilter(const char **propertyList);
256
257 /**
258 * Gets the hash index for the named property. Filtering is ignored.
259 * @param theName The property name
260 * @param pos Returns the hash index.
261 * @return SCMO_OK
262 * SCMO_INVALID_PARAMETER: name was a NULL pointer.
263 * SCMO_NOT_FOUND : Given property name not found.
264 */
265 SCMO_RC getPropertyNodeIndex(const char* name, Uint32& pos) const;
266
267 /**
268 * Set/replace a property in the instance at node index.
269 * Note: If node is filtered, the property is not set but the return value
270 * is still SCMO_OK.
271 * @param index The node index.
272 * @param type The CIMType of the property
273 * @param value A pointer to property value.
274 thilo.boehm 1.1.2.1 * The value is copied into the instance
275 * If the value is an array, the
276 * value array must be stored in continuous memory.
277 * e.g. If the CIMType is CIMTYPE_UINT32:
278 * value = (void*)Uint32[0 to size-1]
279 * @param isArray Indicate that the value is an array. Default false.
280 * @param size The size of the array. If not an array this
281 * this parameter is ignorer. Default 0.
282 * @return SCMO_OK
283 * SCMO_INDEX_OUT_OF_BOUND : Given index not found
284 * SCMO_WRONG_TYPE : The property at given node index
285 * has the wrong type.
286 * SCMO_NOT_AN_ARRAY : The property at given node index
287 * is not an array.
288 * SCMO_IS_AN_ARRAY : The property at given node index
289 * is an array.
290 */
291 SCMO_RC setPropertyWithNodeIndex(
292 Uint32 node,
293 CIMType type,
294 void* value,
295 thilo.boehm 1.1.2.1 Boolean isArray=false,
296 Uint32 size = 0);
297
298 /**
299 * Set/replace the named key binding
300 * @param name The key binding name.
301 * @param type The type as CIMKeyBinding::Type.
302 * @parma value The value as string.
303 * @return SCMO_OK
304 * SCMO_TYPE_MISSMATCH : Given type does not
305 * match to key binding type
306 * SCMO_NOT_FOUND : Given property name not found.
307 */
308 SCMO_RC setKeyBinding(
309 const char* name,
310 CIMKeyBinding::Type type,
311 const char* pvalue);
312
313 /**
314 * Gets the key binding count.
315 * @return the number of key bindings set.
316 thilo.boehm 1.1.2.1 */
317 Uint32 getKeyBindingCount();
318
319 /**
320 * Get the indexed key binding.
321 * @parm idx The key bining index
322 * @parm pname Returns the name.
323 * Has to be copied by caller.
324 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
325 * @param type Returns the type as CIMKeyBinding::Type.
326 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
327 * @parma pvalue Returns the value as string.
328 * Has to be copied by caller.
329 * It is only valid if rc == SCMO_OK.
330 * @return SCMO_OK
331 * SCMO_NULL_VALUE : The key binding is not set.
332 * SCMO_INDEX_OUT_OF_BOUND : Given index not found
333 *
334 */
335 SCMO_RC getKeyBindingAt(
336 Uint32 idx,
337 thilo.boehm 1.1.2.1 const char** pname,
338 CIMKeyBinding::Type& type,
339 const char** pvalue) const;
340
341 /**
342 * Get the named key binding.
343 * @parm name The name of the key binding.
344 * @param type Returns the type as CIMKeyBinding::Type.
345 * It is invalid if rc == SCMO_INDEX_OUT_OF_BOUND.
346 * @parma value Returns the value as string.
347 * Has to be copied by caller.
348 * It is only valid if rc == SCMO_OK.
349 * @return SCMO_OK
350 * SCMO_NULL_VALUE : The key binding is not set.
351 * SCMO_NOT_FOUND : Given property name not found.
352 */
353 SCMO_RC getKeyBinding(
354 const char* name,
355 CIMKeyBinding::Type& ptype,
356 const char** pvalue) const;
357
358 thilo.boehm 1.1.2.1 /**
359 * Determines whether the object has been initialized.
360 * @return True if the object has not been initialized, false otherwise.
361 */
362 Boolean isUninitialized( ) const {return (inst.base == NULL); };
363
364 /**
365 * Determies if two objects are referencing to the same instance
366 * @return True if the objects are referencing to the some instance.
367 */
368 Boolean isSame(SCMOInstance& theInstance) const;
369
370 /**
371 * Get the host name of the instance. The caller has to make a copy !
372 * @return The host name as UTF8.
373 */
374 const char* getHostName() const;
375
376 /**
377 * Sets the provided host name at the instance.
378 * @param hostName The host name as UTF8.
379 thilo.boehm 1.1.2.1 */
380 void setHostName(const char* hostName);
381
382 /**
383 * Get the class name of the instance. The cabler has to make a copy !
384 * @return The class name as UTF8.
385 */
386 const char* getClassName() const;
387
388 /**
389 * Get the name space of the instance. The caller has to make a copy !
390 * @return The name space as UTF8.
391 */
392 const char* getNameSpace() const;
393
394 /**
395 * To indicate the export processing ( eg. XMLWriter )
396 * to include qualifiers for this instance.
397 */
398 void includeQualifiers()
399 {
400 thilo.boehm 1.1.2.1 inst.hdr->flags.includeQualifiers = true;
401 };
402
403 /**
404 * To indicate the export processing ( eg. XMLWriter )
405 * to NOT to include (exclude) qualifiers for this instance.
406 */
407 void excludeQualifiers()
408 {
409 inst.hdr->flags.includeQualifiers = false;
410 }
411
412 /**
413 * To indicate the export processing ( eg. XMLWriter )
414 * to include class origins for this instance.
415 */
416 void includeClassOrigins()
417 {
418 inst.hdr->flags.includeClassOrigin = true;
419 };
420
421 thilo.boehm 1.1.2.1 /**
422 * To indicate the export processing ( eg. XMLWriter )
423 * to NOT to include (exclude) class origins for this instance.
424 */
425 void excludeClassOrigins()
426 {
427 inst.hdr->flags.includeClassOrigin = false;
428 }
429
430 private:
431
432 void Ref()
433 {
434 inst.hdr->refCount++;
435 // printf("\ninst.hdr->refCount=%u\n",inst.hdr->refCount.get());
436 };
437
438 void Unref()
439 {
440 if (inst.hdr->refCount.decAndTestIfZero())
441 {
442 thilo.boehm 1.1.2.1 // printf("\ninst.hdr->refCount=%u\n",inst.hdr->refCount.get());
443 // The class has also be dereferenced.
444 delete inst.hdr->theClass;
445 free(inst.base);
446 inst.base=NULL;
447 }
448 else
449 {
450 // printf("\ninst.hdr->refCount=%u\n",inst.hdr->refCount.get());
451 }
452
453 };
454 /**
455 * A SCMOInstance can only be created by a SCMOClass
456 */
457 SCMOInstance();
458
459 void _initSCMOInstance(
460 SCMOClass* pClass,
461 Boolean inclQual,
462 Boolean inclOrigin);
463 thilo.boehm 1.1.2.1
464
465 SCMO_RC _getPropertyAtNodeIndex(
466 Uint32 pos,
467 const char** pname,
468 CIMType& type,
469 const void** pvalue,
470 Boolean& isArray,
471 Uint32& size ) const;
472
473 void _setPropertyAtNodeIndex(
474 Uint32 pos,
475 CIMType type,
476 void* value,
477 Boolean isArray,
478 Uint32 size);
479
480 void* _getSCMBUnion(
481 CIMType type,
482 Boolean isArray,
483 Uint32 size,
484 thilo.boehm 1.1.2.1 Uint64 start,
485 char* base) const;
486
487 void _setSCMBUnion(
488 void* value,
489 CIMType type,
490 Boolean isArray,
491 Uint32 size,
492 Uint64 start);
493
494 SCMO_RC _getKeyBindingAtNodeIndex(
495 Uint32 pos,
496 const char** pname,
497 CIMKeyBinding::Type& ptype,
498 const char** pvalue) const;
499
500 Uint32 _initPropFilterWithKeys();
501
502 void _setPropertyInPropertyFilter(Uint32 i);
503
504 Boolean _isPropertyInFilter(Uint32 i) const;
505 thilo.boehm 1.1.2.1
506 void _clearPropertyFilter();
507
508 union{
509 // To access the instance main structure
510 SCMBInstance_Main *hdr;
511 // To access the memory management header
512 SCMBMgmt_Header *mem;
513 // Generic access pointer
514 char *base;
515 }inst;
516
517 friend class SCMOClass;
518 friend class SCMODump;
519 };
520
521
522 PEGASUS_NAMESPACE_END
523
524
525 #endif
|