1 karl  1.24 //%2006////////////////////////////////////////////////////////////////////////

  2 chip  1.1  //

  3 karl  1.22 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4            // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5            // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;

  6 karl  1.19 // IBM Corp.; EMC Corporation, The Open Group.

  7 karl  1.22 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8            // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.

  9 karl  1.23 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10            // EMC Corporation; VERITAS Software Corporation; The Open Group.

 11 karl  1.24 // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 12            // EMC Corporation; Symantec Corporation; The Open Group.

 13 chip  1.1  //
 14            // Permission is hereby granted, free of charge, to any person obtaining a copy
 15            // of this software and associated documentation files (the "Software"), to
 16            // deal in the Software without restriction, including without limitation the
 17            // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 18            // sell copies of the Software, and to permit persons to whom the Software is
 19            // furnished to do so, subject to the following conditions:

 20 karl  1.19 // 

 21 chip  1.1  // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 22            // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 23            // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 24            // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 25            // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 26            // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 27            // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 28            // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 29            //
 30            //==============================================================================
 31            //
 32            //%/////////////////////////////////////////////////////////////////////////////
 33            
 34            #ifndef Pegasus_CIMInstanceProvider_h
 35            #define Pegasus_CIMInstanceProvider_h
 36            
 37            #include <Pegasus/Common/Config.h>

 38 kumpf 1.16 #include <Pegasus/Provider/CIMProvider.h>

 39 chip  1.1  
 40            #include <Pegasus/Common/Array.h>

 41 kumpf 1.5  #include <Pegasus/Common/CIMPropertyList.h>

 42 kumpf 1.6  #include <Pegasus/Common/CIMObjectPath.h>

 43 chip  1.1  #include <Pegasus/Common/CIMInstance.h>

 44 kumpf 1.12 #include <Pegasus/Provider/Linkage.h>

 45 chip  1.1  
 46            PEGASUS_NAMESPACE_BEGIN

 47 kumpf 1.17 /** This class defines a set of functions that support the

 48 kumpf 1.8  manipulation of instances of a CIM object class and their
 49            properties.
 50            
 51            <p>The Instance Provider is the most common provider, and

 52 kumpf 1.17 is the provider interface used by the CIM Server to perform instance

 53 kumpf 1.8  and property
 54            manipulation requests from CIM clients. Instance providers
 55            may be implemented for any CIM class, including <i>Association</i>
 56            classes.</p>
 57            
 58            <p>In addition to

 59 chip  1.9  functions inherited from the

 60 kumpf 1.16 {@link CIMProvider CIMProvider} interface,

 61 kumpf 1.8  the functions in the Instance Provider interface are:</p>
 62            
 63            <p><ul>
 64            <li>{@link getInstance getInstance}</li>
 65            <li>{@link enumerateInstances enumerateInstances}</li>

 66 kumpf 1.17 <li>{@link enumerateInstanceNames enumerateInstanceNames}</li>

 67 kumpf 1.8  <li>{@link modifyInstance modifyInstance}</li>
 68            <li>{@link createInstance createInstance}</li>
 69            <li>{@link deleteInstance deleteInstance}</li>
 70            </ul></p>
 71            
 72            <p>The Instance Provider receives operation requests from

 73 kumpf 1.17 clients through calls to these functions by the CIM Server. Its

 74 kumpf 1.8  purpose is to convert these to calls to system services,
 75            operations on system resources, or whatever platform-specific
 76            behavior is required to perform the operation modeled by
 77            the request. The specific requirements for each of the interface
 78            functions are discussed in their respective sections.</p>

 79 chip  1.1  */

 80 kumpf 1.16 class PEGASUS_PROVIDER_LINKAGE CIMInstanceProvider : public virtual CIMProvider

 81 chip  1.1  {
 82            public:

 83 kumpf 1.8      /**
 84                Constructor.
 85                The constructor should not do anything.
 86                */

 87 chip  1.4      CIMInstanceProvider(void);

 88 kumpf 1.8  
 89                /**
 90                Destructor.
 91                The destructor should not do anything.
 92                */

 93 chip  1.4      virtual ~CIMInstanceProvider(void);

 94 chip  1.1  

 95 chip  1.4      /**

 96 kumpf 1.8      \Label{getInstance}
 97                Return a single instance.

 98 chip  1.1  

 99 kumpf 1.8      <p><tt>getInstance</tt> is called with an
100                {@link CIMObjectPath instanceReference} specifying a CIM
101                instance to be returned. The provider should determine whether
102                the specification corresponds to a valid instance. If so, it will
103                construct a <tt>{@link CIMInstance CIMInstance}</tt>

104 kumpf 1.17     and deliver this to the CIM Server via the
105                <tt>{@link ResponseHandler ResponseHandler}</tt>

106 kumpf 1.8      callback. If the specified instance does not exist, this

107 kumpf 1.17     function should throw an <tt>{@link CIMObjectNotFoundException CIMObjectNotFoundException}.</tt>
108                </p>

109 chip  1.9  

110 kumpf 1.8      <p>A provider can be implemented and registered to perform
111                operations for
112                several levels of the same line of descent (e.g.,
113                CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
114                is done, care must be taken to return the same set of key
115                values regardless of which class was specified in the
116                operation.</p>

117 chip  1.1  

118 kumpf 1.8      @param context specifies the client user's context for this operation,
119                including the User ID.
120            
121                @param instanceReference specifies the fully qualified object path
122                of the instance of interest.

123 chip  1.4  

124 kumpf 1.15     @param includeQualifiers indicates whether the returned instance must
125                include the qualifiers for the instance and properties.  Qualifiers may
126                be included even if this flag is false.
127            
128                @param includeClassOrigin indicates whether the returned instance must
129                include the class origin for each of the instance elements.

130 chip  1.4  

131 kumpf 1.8      @param propertyList if not null, this parameter
132                specifies the minimum set of properties required in instances
133                returned by this operation. Because
134                support for this parameter is optional, the instances may contain
135                additional properties not specified in the list.

136 karl  1.18 	NOTE: The provider does NOT receive the client filtering parameter
137            	localOnly.  This is resolved in the CIMOM into the propertyList so 
138            	that the property list represents the complete set of properties to
139            	be returned.
140            	If the propertyList is NULL all properties are returned.  If it is
141            	nonNULL but empty, no properites are to be returned.

142 chip  1.4  

143 kumpf 1.8      @param handler a {@link ResponseHandler ResponseHandler} object used

144 kumpf 1.17     to deliver results to the CIM Server.

145 chip  1.4  

146 kumpf 1.17     @exception CIMNotSupportedException
147                @exception CIMInvalidParameterException
148                @exception CIMObjectNotFoundException
149                @exception CIMAccessDeniedException
150                @exception CIMOperationFailedException

151 chip  1.4      */
152                virtual void getInstance(

153 chip  1.9          const OperationContext & context,
154                    const CIMObjectPath & instanceReference,

155 kumpf 1.15         const Boolean includeQualifiers,
156                    const Boolean includeClassOrigin,

157 chip  1.9          const CIMPropertyList & propertyList,

158 kumpf 1.14         InstanceResponseHandler & handler) = 0;

159 chip  1.4  
160                /**

161 kumpf 1.8      \Label{enumerateInstances}
162                Return all instances of the specified class.
163            
164                <p>A typical implementation of this function will call the
165                <tt>{@link processing processing}</tt> function in the
166                <tt>{@link ResponseHandler handler}</tt> object, then
167                iterate over the system resources representing instances of
168                the CIM object, calling <tt>{@link deliver deliver}</tt> on
169                each iteration. It must call <tt>deliver</tt> with an
170                argument of type <tt>{@link CIMInstance CIMInstance}</tt>.
171                Finally, it will call <tt>{@link complete complete}</tt> to

172 kumpf 1.17     inform the CIM Server that it has delivered all known instances.</p>

173 kumpf 1.8  
174                <p>A provider can be implemented and registered to perform
175                operations for several levels of the same line of descent (e.g.,
176                CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
177                is done, the provider must return instances <i>only</i>
178                for the deepest class for which it is registered, since

179 kumpf 1.17     the CIM Server will invoke <tt>enumerateInstances</tt> for all

180 kumpf 1.8      classes at and beneath that specified in the
181                {@link CIMObjectPath classReference}.</p>

182 chip  1.4  

183 kumpf 1.8      @param context specifies the client user's context for this operation,
184                including the User ID.

185 chip  1.4  

186 kumpf 1.8      @param classReference specifies the fully qualified object path
187                to the class of interest.

188 chip  1.4  

189 kumpf 1.15     @param includeQualifiers indicates whether the returned instances must
190                include the qualifiers for the instance and properties.  Qualifiers may
191                be included even if this flag is false.

192 chip  1.4  

193 kumpf 1.15     @param includeClassOrigin indicates whether the returned instances must
194                include the class origin for each of the instance elements.

195 chip  1.4  

196 kumpf 1.5      @param propertyList If not null, this parameter

197 chip  1.4      specifies the minimum set of properties required in instances returned by this operation. Because
198                support for this parameter is optional, the instances may contain additional properties not specified

199 karl  1.18     in the list. NOTE: The provider does NOT receive the client filtering parameters
200            	localOnly or deepInheritance.  These are resolved in the CIMOM into the propertyList.

201 chip  1.4  

202 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
203                delivery of results.

204 chip  1.4  

205 kumpf 1.17     @exception CIMNotSupportedException
206                @exception CIMInvalidParameterException
207                @exception CIMObjectNotFoundException

208 kumpf 1.8      <br>should never be thrown by this function; if
209                there are no instances to return, this function should deliver an empty
210                set of instances by calling the
211                handler's <tt>{@link processing processing} </tt> and
212                <tt>{@link complete complete}</tt> functions without calling
213                <tt>{@link deliver deliver}</tt>.

214 chip  1.9  

215 kumpf 1.17     @exception CIMAccessDeniedException
216                @exception CIMOperationFailedException
217            

218 chip  1.4      */
219                virtual void enumerateInstances(

220 chip  1.9          const OperationContext & context,
221                    const CIMObjectPath & classReference,

222 kumpf 1.15         const Boolean includeQualifiers,
223                    const Boolean includeClassOrigin,

224 chip  1.9          const CIMPropertyList & propertyList,

225 kumpf 1.14         InstanceResponseHandler & handler) = 0;

226 chip  1.4  
227                /**

228 kumpf 1.8      \Label{enumerateInstanceNames}
229                Return all instance names of a single class.

230 chip  1.4  

231 kumpf 1.8      <p>Like <tt>enumerateInstances</tt>, a typical implementation
232                of <tt>enumerateInstanceNames</tt> will call the
233                <tt>{@link processing processing}</tt> function in the
234                <tt>{@link ResponseHandler handler}</tt> object, then
235                iterate over the system resources representing instances of
236                the CIM object, calling <tt>{@link deliver deliver}</tt> on
237                each iteration. It must call {@link deliver deliver} with an
238                argument of type <tt>{@link CIMObjectPath CIMObjectPath}</tt>
239                containing the information that uniquely identifies each

240 chip  1.9      instance.

241 kumpf 1.8      Finally, it will call <tt>{@link complete complete}</tt> to

242 kumpf 1.17     inform the CIM Server that it has delivered all known instances.</p>

243 kumpf 1.8  
244                <p>A provider can be implemented and registered to perform
245                operations for several levels of the same line of descent (e.g.,
246                CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
247                is done, the provider must return instance names <i>only</i>
248                for the deepest class for which it is registered, since

249 kumpf 1.17     the CIM Server will invoke <tt>enumerateInstanceNames</tt> for all

250 kumpf 1.8      classes at and beneath that specified in the
251                {@link CIMObjectPath classReference}.</p>

252 chip  1.4  

253 kumpf 1.8      @param context specifies the client user's context for this operation,
254                including the User ID.
255            
256                @param classReference specifies the fully qualified object path to
257                the class of interest.

258 chip  1.4  

259 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
260                delivery of results.

261 chip  1.4  

262 kumpf 1.17     @exception CIMNotSupportedException
263                @exception CIMInvalidParameterException
264                @exception CIMObjectNotFoundException
265                @exception CIMAccessDeniedException
266                @exception CIMOperationFailedException

267 chip  1.4      */
268                virtual void enumerateInstanceNames(

269 chip  1.9          const OperationContext & context,
270                    const CIMObjectPath & classReference,

271 kumpf 1.14         ObjectPathResponseHandler & handler) = 0;

272 chip  1.4  
273                /**

274 kumpf 1.8      \Label{modifyInstance}
275                Replace the current instance specified in the
276                instanceReference parameter.

277 chip  1.9  

278 kumpf 1.8      <p><tt>modifyInstance</tt> sets the values of properties of
279                the instance specified by the <tt>instanceReference</tt> parameter
280                to those specified in the <tt>instanceObject</tt> parameter, as
281                controlled by the <tt>propertyList</tt> parameter. If the
282                <tt>propertyList</tt>
283                is NULL, then the operation sets all properties. Otherwise,
284                it sets only those specified in the <tt>propertyList</tt>.
285                Properties specified in the <tt>propertyList</tt> but not present in
286                the <tt>instanceObject</tt> are replaced by
287                the class default values or left null.</p>

288 chip  1.9  

289 kumpf 1.8      <p>Ideally, <tt>modifyInstance</tt> is intended to be
290                an <i>atomic</i> operation on values of the instance. That is,
291                concurrent accesses to the instance by other threads should be
292                blocked during the operation, so that all of the affected property
293                values can be
294                changed without intervening accesses by concurrent requests.
295                Otherwise, other requests could obtain intermediate, and
296                possibly inconsistent, results.</p>
297            
298                <p>If the specified instance does not exist, the provider

299 kumpf 1.17     should throw an {@link CIMObjectNotFoundException ObjectNotFound}

300 kumpf 1.8      exception.

301 chip  1.9  

302 kumpf 1.8      @param context specifies the client user's context for this operation,
303                including the User ID.

304 chip  1.4  
305                @param instanceReference specifies the fully qualified object path of the instance of interest.
306            

307 kumpf 1.8      @param instanceObject contains the partial or complete set of
308                properties whose values should be changed.

309 chip  1.4  

310 kumpf 1.15     @param includeQualifiers indicates whether the instance qualifiers must
311                be updated as specified in the modified instance.  If false, no
312                qualifiers are explicitly modified by this operation.

313 chip  1.4  

314 kumpf 1.5      @param propertyList If not null, this parameter

315 chip  1.4      specifies the set of properties required to be updated in the instance. Support
316                for this parameter is NOT optional.  Providers that do not support this

317 kumpf 1.17     feature must throw a {@link CIMNotSupportedException CIMNotSupportedException} exception.

318 karl  1.18 	NOTE: The provider does NOT receive the client filtering parameters
319            	localOnly or deepInheritance.  These are resolved in the CIMOM into the propertyList.
320            	

321 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
322                delivery of results.

323 chip  1.4  

324 kumpf 1.17     @exception CIMNotSupportedException
325                @exception CIMInvalidParameterException
326                @exception CIMObjectNotFoundException
327                @exception CIMAccessDeniedException
328                @exception CIMOperationFailedException

329 chip  1.4      */
330                virtual void modifyInstance(

331 chip  1.9          const OperationContext & context,
332                    const CIMObjectPath & instanceReference,
333                    const CIMInstance & instanceObject,

334 kumpf 1.15         const Boolean includeQualifiers,

335 chip  1.9          const CIMPropertyList & propertyList,

336 kumpf 1.14         ResponseHandler & handler) = 0;

337 chip  1.4  
338                /**

339 kumpf 1.8      \Label{createInstance}
340                Create a new instance.

341 chip  1.4  

342 kumpf 1.8      <p>Create a new instance of the specified class as specified
343                by the <tt>instanceReference</tt> and <tt>instanceObject</tt>
344                parameters.</p>
345            
346                @param context specifies the client user's context for this operation,
347                including the User ID.
348            

349 kumpf 1.20     @param instanceReference Specifies the namespace and class name
350                of the instance to create.  The key bindings are not present in
351                the instanceReference, because an instance name is not defined
352                until after the instance has been created.

353 chip  1.4  
354                @param instanceObject contains the partial or complete instance to create.

355 kumpf 1.20     If a key property is null, the provider <em>must</em> supply a valid
356                value for the property or throw a {@link CIMInvalidParameterException
357                CIMInvalidParameterException}.  If any property value is invalid, the
358                provider should throw a {@link CIMInvalidParameterException
359                CIMInvalidParameterException}.

360 chip  1.4  

361 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for

362 kumpf 1.20     delivery of results.  If the operation is successful, the provider must
363                deliver the complete instance name of the created instance.

364 chip  1.4  

365 kumpf 1.17     @exception CIMNotSupportedException
366                @exception CIMInvalidParameterException

367 kumpf 1.20     @exception CIMObjectAlreadyExistsException

368 kumpf 1.17     @exception CIMAccessDeniedException
369                @exception CIMOperationFailedException

370 chip  1.4      */
371                virtual void createInstance(

372 chip  1.9          const OperationContext & context,
373                    const CIMObjectPath & instanceReference,
374                    const CIMInstance & instanceObject,

375 kumpf 1.14         ObjectPathResponseHandler & handler) = 0;

376 chip  1.4  
377                /**

378 kumpf 1.8      \Label{deleteInstance}
379                Delete the instance specified by the instanceReference parameter.

380 chip  1.4  

381 kumpf 1.8      @param context specifies the client user's context for this operation,
382                including the User ID.

383 chip  1.4  

384 kumpf 1.8      @param instanceReference specifies the fully qualified object
385                path of the instance to delete. If the specified object does
386                not exist, the provider should throw an

387 kumpf 1.17     {@link CIMObjectNotFoundException ObjectNotFound} exception.

388 chip  1.4  

389 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
390                delivery of results.

391 chip  1.4  

392 kumpf 1.17     @exception CIMNotSupportedException
393                @exception CIMInvalidParameterException
394                @exception CIMObjectNotFoundException
395                @exception CIMAccessDeniedException
396                @exception CIMOperationFailedException

397 chip  1.4      */
398                virtual void deleteInstance(

399 chip  1.9          const OperationContext & context,
400                    const CIMObjectPath & instanceReference,

401 kumpf 1.14         ResponseHandler & handler) = 0;

402 chip  1.1  };
403            
404            PEGASUS_NAMESPACE_END
405            
406            #endif