1 martin 1.29 //%LICENSE////////////////////////////////////////////////////////////////
|
2 martin 1.31 //
|
3 martin 1.29 // 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 martin 1.31 //
|
10 martin 1.29 // 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 martin 1.31 //
|
17 martin 1.29 // The above copyright notice and this permission notice shall be included
18 // in all copies or substantial portions of the Software.
|
19 martin 1.31 //
|
20 martin 1.29 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
21 martin 1.31 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
22 martin 1.29 // 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 martin 1.31 //
|
28 martin 1.29 //////////////////////////////////////////////////////////////////////////
|
29 chip 1.1 //
30 //%/////////////////////////////////////////////////////////////////////////////
31
32 #ifndef Pegasus_CIMInstanceProvider_h
33 #define Pegasus_CIMInstanceProvider_h
34
35 #include <Pegasus/Common/Config.h>
|
36 kumpf 1.16 #include <Pegasus/Provider/CIMProvider.h>
|
37 chip 1.1
38 #include <Pegasus/Common/Array.h>
|
39 kumpf 1.5 #include <Pegasus/Common/CIMPropertyList.h>
|
40 kumpf 1.6 #include <Pegasus/Common/CIMObjectPath.h>
|
41 chip 1.1 #include <Pegasus/Common/CIMInstance.h>
|
42 kumpf 1.12 #include <Pegasus/Provider/Linkage.h>
|
43 chip 1.1
44 PEGASUS_NAMESPACE_BEGIN
|
45 kumpf 1.27
46 /**
47 This class defines a set of functions that support the manipulation of
48 instances of a CIM object class and their properties.
49
50 <p>The Instance Provider is the most common provider, and is the provider
51 interface used by the CIM Server to perform instance and property
52 manipulation operations.</p>
53
54 <p>The Instance Provider receives operation requests from clients through
55 calls to these functions by the CIM Server. Its purpose is to convert
56 these to calls to system services, operations on system resources, or
57 whatever platform-specific behavior is required to perform the operation
58 modeled by the request. The specific requirements for each of the interface
59 functions are discussed in their respective sections.</p>
|
60 chip 1.1 */
|
61 kumpf 1.16 class PEGASUS_PROVIDER_LINKAGE CIMInstanceProvider : public virtual CIMProvider
|
62 chip 1.1 {
63 public:
|
64 kumpf 1.8 /**
|
65 kumpf 1.28 Constructs a default CIMInstanceProvider object.
|
66 kumpf 1.8 */
|
67 kumpf 1.25 CIMInstanceProvider();
|
68 kumpf 1.8
69 /**
|
70 kumpf 1.28 Destructs a CIMInstanceProvider object.
|
71 kumpf 1.8 */
|
72 kumpf 1.25 virtual ~CIMInstanceProvider();
|
73 chip 1.1
|
74 chip 1.4 /**
|
75 kumpf 1.28 Returns a specified CIM instance.
|
76 chip 1.1
|
77 kumpf 1.28 @param context An OperationContext object containing the context for
78 the processing of the operation. The context includes the name of
79 the requesting user, language information, and other data.
80
81 @param instanceReference A fully qualified CIMObjectPath specifying
82 the instance to be retrieved.
83
84 @param includeQualifiers A Boolean indicating whether the returned
85 instance must include the qualifiers for the instance and its
86 properties. Qualifiers may be included even if this flag is false.
87
88 @param includeClassOrigin A Boolean indicating whether the returned
89 instance must include the class origin for each of the instance
90 elements.
91
92 @param propertyList A CIMPropertyList specifying the minimum set of
93 properties required in the returned instance. Support for this
|
94 anusha.kandepu 1.32 parameter is optional.This parameter can be used by the provider
95 to optimize their code and not fill properties which are not
96 requested.The cimserver will filter all properties using an
97 efficient algorithm hence the returned instance may contain
98 properties not specified in the list.A null propertyList
|
99 kumpf 1.28 indicates that all properties must be included. A non-null,
100 but empty, propertyList indicates that no properites are required.
101 Note: The client PropertyList and LocalOnly parameters are
102 consolidated by the CIM Server into this single parameter.
|
103 kumpf 1.25
|
104 kumpf 1.26 @param handler ResponseHandler object for delivery of results.
|
105 kumpf 1.25
106 @exception CIMNotSupportedException
107 @exception CIMInvalidParameterException
108 @exception CIMObjectNotFoundException
109 @exception CIMAccessDeniedException
110 @exception CIMOperationFailedException
|
111 chip 1.4 */
112 virtual void getInstance(
|
113 kumpf 1.25 const OperationContext& context,
114 const CIMObjectPath& instanceReference,
|
115 kumpf 1.15 const Boolean includeQualifiers,
116 const Boolean includeClassOrigin,
|
117 kumpf 1.25 const CIMPropertyList& propertyList,
118 InstanceResponseHandler& handler) = 0;
|
119 chip 1.4
120 /**
|
121 kumpf 1.28 Returns all instances of a specified class.
|
122 kumpf 1.8
|
123 kumpf 1.28 <p>A typical implementation of this method will call the
124 <tt>processing</tt> method in the <tt>ResponseHandler</tt> object,
|
125 kumpf 1.26 then iterate over the system resources representing instances of
|
126 kumpf 1.28 the CIM object, calling <tt>deliver</tt> on each iteration.
|
127 kumpf 1.26 Finally, it will call <tt>complete</tt> to inform the CIM Server that
128 it has delivered all known instances. It is correct to call
129 <tt>complete</tt> without calling <tt>deliver</tt> if no instances
130 exist.</p>
|
131 kumpf 1.25
132 <p>A provider can be implemented and registered to perform
133 operations for several levels of the same line of descent (e.g.,
134 CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
135 is done, the provider must return instances <i>only</i>
136 for the deepest class for which it is registered, since
137 the CIM Server will invoke <tt>enumerateInstances</tt> for all
|
138 kumpf 1.28 classes at and beneath the class specified by the client.</p>
|
139 kumpf 1.25
|
140 kumpf 1.28 @param context An OperationContext object containing the context for
141 the processing of the operation. The context includes the name of
142 the requesting user, language information, and other data.
143
144 @param classReference A fully qualified CIMObjectPath specifying
145 the class for which to retrieve the instances.
146
147 @param includeQualifiers A Boolean indicating whether the returned
148 instances must include the qualifiers for the instance and its
149 properties. Qualifiers may be included even if this flag is false.
150
151 @param includeClassOrigin A Boolean indicating whether the returned
152 instances must include the class origin for each of the instance
153 elements.
154
155 @param propertyList A CIMPropertyList specifying the minimum set of
|
156 anusha.kandepu 1.32 properties required in the returned instance. Support for this
157 parameter is optional.This parameter can be used by the provider
158 to optimize their code and not fill properties which are not
159 requested.The cimserver will filter all properties using an
160 efficient algorithm hence the returned instance may contain
161 properties not specified in the list.A null propertyList
|
162 kumpf 1.28 indicates that all properties must be included. A non-null,
163 but empty, propertyList indicates that no properites are required.
|
164 anusha.kandepu 1.32 Note: The client PropertyList and LocalOnly parameters are
165 consolidated by the CIM Server into this single parameter.
|
166 kumpf 1.25
|
167 kumpf 1.26 @param handler ResponseHandler object for delivery of results.
|
168 kumpf 1.25
169 @exception CIMNotSupportedException
170 @exception CIMInvalidParameterException
171 @exception CIMAccessDeniedException
172 @exception CIMOperationFailedException
|
173 chip 1.4 */
174 virtual void enumerateInstances(
|
175 kumpf 1.25 const OperationContext& context,
176 const CIMObjectPath& classReference,
|
177 kumpf 1.15 const Boolean includeQualifiers,
178 const Boolean includeClassOrigin,
|
179 kumpf 1.25 const CIMPropertyList& propertyList,
180 InstanceResponseHandler& handler) = 0;
|
181 chip 1.4
182 /**
|
183 kumpf 1.28 Returns the names of all instances of a specified class.
|
184 chip 1.4
|
185 kumpf 1.28 <p>A typical implementation of this method will call the
186 <tt>processing</tt> method in the <tt>ResponseHandler</tt> object,
187 then iterate over the system resources representing instances of
188 the CIM object, calling <tt>deliver</tt> on each iteration.
|
189 kumpf 1.26 Finally, it will call <tt>complete</tt> to inform the CIM Server that
|
190 kumpf 1.28 it has delivered all known instances. It is correct to call
191 <tt>complete</tt> without calling <tt>deliver</tt> if no instances
|
192 kumpf 1.26 exist.</p>
|
193 kumpf 1.25
194 <p>A provider can be implemented and registered to perform
195 operations for several levels of the same line of descent (e.g.,
196 CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
|
197 kumpf 1.28 is done, the provider must return instances <i>only</i>
|
198 kumpf 1.25 for the deepest class for which it is registered, since
199 the CIM Server will invoke <tt>enumerateInstanceNames</tt> for all
|
200 kumpf 1.28 classes at and beneath the class specified by the client.</p>
|
201 kumpf 1.25
|
202 kumpf 1.28 @param context An OperationContext object containing the context for
203 the processing of the operation. The context includes the name of
204 the requesting user, language information, and other data.
|
205 kumpf 1.25
|
206 kumpf 1.28 @param classReference A fully qualified CIMObjectPath specifying
207 the class for which to retrieve the instance names.
|
208 kumpf 1.25
|
209 kumpf 1.26 @param handler ResponseHandler object for delivery of results.
|
210 kumpf 1.30 The delivered CIMObjectPath values should not contain host or
211 namespace information, as these attributes are not included in the
212 WBEM protocol.
|
213 kumpf 1.25
214 @exception CIMNotSupportedException
215 @exception CIMInvalidParameterException
216 @exception CIMAccessDeniedException
217 @exception CIMOperationFailedException
|
218 chip 1.4 */
219 virtual void enumerateInstanceNames(
|
220 kumpf 1.25 const OperationContext& context,
221 const CIMObjectPath& classReference,
222 ObjectPathResponseHandler& handler) = 0;
|
223 chip 1.4
224 /**
|
225 kumpf 1.28 Replaces all or part of a specified instance.
|
226 kumpf 1.25
|
227 kumpf 1.28 This method is intended to be atomic. Intermediate states should
228 not be visible to other operations that access the instance.
|
229 kumpf 1.25
|
230 kumpf 1.28 @param context An OperationContext object containing the context for
231 the processing of the operation. The context includes the name of
232 the requesting user, language information, and other data.
233
234 @param instanceReference A fully qualified CIMObjectPath specifying
235 the instance to be modified.
236
237 @param instanceObject A CIMInstance containing the properties and
238 qualifiers with which to update the instance.
239
240 @param includeQualifiers A Boolean indicating whether the instance
241 qualifiers are to be updated in the instance and its properties.
242 If false, no qualifiers are explicitly modified by this operation.
243
244 @param propertyList A CIMPropertyList specifying the set of properties
245 to be updated in the instance. Support for this parameter is NOT
246 optional. If the propertyList cannot be honored, a
247 CIMNotSupportedException must be thrown. A null propertyList
248 indicates that all properties must be updated. Properties
249 specified in the propertyList but not present in the
250 <tt>instanceObject</tt> are to be replaced by the class default
251 kumpf 1.28 values or left null.
252
253 @param handler ResponseHandler object for delivery of results.
|
254 kumpf 1.25
255 @exception CIMNotSupportedException
256 @exception CIMInvalidParameterException
257 @exception CIMObjectNotFoundException
258 @exception CIMAccessDeniedException
259 @exception CIMOperationFailedException
|
260 chip 1.4 */
261 virtual void modifyInstance(
|
262 kumpf 1.25 const OperationContext& context,
263 const CIMObjectPath& instanceReference,
264 const CIMInstance& instanceObject,
|
265 kumpf 1.15 const Boolean includeQualifiers,
|
266 kumpf 1.25 const CIMPropertyList& propertyList,
267 ResponseHandler& handler) = 0;
|
268 chip 1.4
269 /**
|
270 kumpf 1.28 Creates a new instance.
|
271 kumpf 1.25
|
272 kumpf 1.28 @param context An OperationContext object containing the context for
273 the processing of the operation. The context includes the name of
274 the requesting user, language information, and other data.
|
275 kumpf 1.25
276 @param instanceReference Specifies the namespace and class name
|
277 kumpf 1.28 of the instance to create. The key bindings are not present in
278 the instanceReference, because an instance name is not defined
279 until after the instance has been created.
280
281 @param instanceObject The CIM instance to create. If a key property
282 is null, the provider <em>must</em> supply a valid value for the
283 property or throw a CIMInvalidParameterException. If any property
284 value is invalid, the provider should throw a
285 CIMInvalidParameterException.
286
287 @param handler ResponseHandler object for delivery of results. On
288 a successful operation, the name of the newly created instance
289 must be delivered.
|
290 kumpf 1.25
291 @exception CIMNotSupportedException
292 @exception CIMInvalidParameterException
293 @exception CIMObjectAlreadyExistsException
294 @exception CIMAccessDeniedException
295 @exception CIMOperationFailedException
|
296 chip 1.4 */
297 virtual void createInstance(
|
298 kumpf 1.25 const OperationContext& context,
299 const CIMObjectPath& instanceReference,
300 const CIMInstance& instanceObject,
301 ObjectPathResponseHandler& handler) = 0;
|
302 chip 1.4
303 /**
|
304 kumpf 1.28 Deletes a specified instance.
|
305 chip 1.4
|
306 kumpf 1.28 @param context An OperationContext object containing the context for
307 the processing of the operation. The context includes the name of
308 the requesting user, language information, and other data.
|
309 chip 1.4
|
310 kumpf 1.28 @param instanceReference A fully qualified CIMObjectPath specifying
311 the instance to be deleted.
|
312 kumpf 1.25
|
313 kumpf 1.26 @param handler ResponseHandler object for delivery of results.
|
314 kumpf 1.25
315 @exception CIMNotSupportedException
316 @exception CIMInvalidParameterException
317 @exception CIMObjectNotFoundException
318 @exception CIMAccessDeniedException
319 @exception CIMOperationFailedException
|
320 chip 1.4 */
321 virtual void deleteInstance(
|
322 kumpf 1.25 const OperationContext& context,
323 const CIMObjectPath& instanceReference,
324 ResponseHandler& handler) = 0;
|
325 chip 1.1 };
326
327 PEGASUS_NAMESPACE_END
328
329 #endif
|