1 karl  1.22 //%2004////////////////////////////////////////////////////////////////////////

  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 chip  1.1  //
 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 karl  1.19 // 

 17 chip  1.1  // 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            //%/////////////////////////////////////////////////////////////////////////////
 29            
 30            #ifndef Pegasus_CIMInstanceProvider_h
 31            #define Pegasus_CIMInstanceProvider_h
 32            
 33            #include <Pegasus/Common/Config.h>

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

 35 chip  1.1  
 36            #include <Pegasus/Common/Array.h>

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

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

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

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

 41 chip  1.1  
 42            PEGASUS_NAMESPACE_BEGIN

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

 44 kumpf 1.8  manipulation of instances of a CIM object class and their
 45            properties.
 46            
 47            <p>The Instance Provider is the most common provider, and

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

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

 55 chip  1.9  functions inherited from the

 56 kumpf 1.16 {@link CIMProvider CIMProvider} interface,

 57 kumpf 1.8  the functions in the Instance Provider interface are:</p>
 58            
 59            <p><ul>
 60            <li>{@link getInstance getInstance}</li>
 61            <li>{@link enumerateInstances enumerateInstances}</li>

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

 63 kumpf 1.8  <li>{@link modifyInstance modifyInstance}</li>
 64            <li>{@link createInstance createInstance}</li>
 65            <li>{@link deleteInstance deleteInstance}</li>
 66            </ul></p>
 67            
 68            <p>The Instance Provider receives operation requests from

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

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

 75 chip  1.1  */

 76 kumpf 1.16 class PEGASUS_PROVIDER_LINKAGE CIMInstanceProvider : public virtual CIMProvider

 77 chip  1.1  {
 78            public:

 79 kumpf 1.8      /**
 80                Constructor.
 81                The constructor should not do anything.
 82                */

 83 chip  1.4      CIMInstanceProvider(void);

 84 kumpf 1.8  
 85                /**
 86                Destructor.
 87                The destructor should not do anything.
 88                */

 89 chip  1.4      virtual ~CIMInstanceProvider(void);

 90 chip  1.1  

 91 chip  1.4      /**

 92 kumpf 1.8      \Label{getInstance}
 93                Return a single instance.

 94 chip  1.1  

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

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

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

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

105 chip  1.9  

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

113 chip  1.1  

114 kumpf 1.8      @param context specifies the client user's context for this operation,
115                including the User ID.
116            
117                @param instanceReference specifies the fully qualified object path
118                of the instance of interest.

119 chip  1.4  

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

126 chip  1.4  

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

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

138 chip  1.4  

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

140 kumpf 1.17     to deliver results to the CIM Server.

141 chip  1.4  

142 kumpf 1.17     @exception CIMNotSupportedException
143                @exception CIMInvalidParameterException
144                @exception CIMObjectNotFoundException
145                @exception CIMAccessDeniedException
146                @exception CIMOperationFailedException

147 chip  1.4      */
148                virtual void getInstance(

149 chip  1.9          const OperationContext & context,
150                    const CIMObjectPath & instanceReference,

151 kumpf 1.15         const Boolean includeQualifiers,
152                    const Boolean includeClassOrigin,

153 chip  1.9          const CIMPropertyList & propertyList,

154 kumpf 1.14         InstanceResponseHandler & handler) = 0;

155 chip  1.4  
156                /**

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

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

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

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

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

178 chip  1.4  

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

181 chip  1.4  

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

184 chip  1.4  

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

188 chip  1.4  

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

191 chip  1.4  

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

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

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

197 chip  1.4  

198 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
199                delivery of results.

200 chip  1.4  

201 kumpf 1.17     @exception CIMNotSupportedException
202                @exception CIMInvalidParameterException
203                @exception CIMObjectNotFoundException

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

210 chip  1.9  

211 kumpf 1.17     @exception CIMAccessDeniedException
212                @exception CIMOperationFailedException
213            

214 chip  1.4      */
215                virtual void enumerateInstances(

216 chip  1.9          const OperationContext & context,
217                    const CIMObjectPath & classReference,

218 kumpf 1.15         const Boolean includeQualifiers,
219                    const Boolean includeClassOrigin,

220 chip  1.9          const CIMPropertyList & propertyList,

221 kumpf 1.14         InstanceResponseHandler & handler) = 0;

222 chip  1.4  
223                /**

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

226 chip  1.4  

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

236 chip  1.9      instance.

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

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

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

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

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

248 chip  1.4  

249 kumpf 1.8      @param context specifies the client user's context for this operation,
250                including the User ID.
251            
252                @param classReference specifies the fully qualified object path to
253                the class of interest.

254 chip  1.4  

255 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
256                delivery of results.

257 chip  1.4  

258 kumpf 1.17     @exception CIMNotSupportedException
259                @exception CIMInvalidParameterException
260                @exception CIMObjectNotFoundException
261                @exception CIMAccessDeniedException
262                @exception CIMOperationFailedException

263 chip  1.4      */
264                virtual void enumerateInstanceNames(

265 chip  1.9          const OperationContext & context,
266                    const CIMObjectPath & classReference,

267 kumpf 1.14         ObjectPathResponseHandler & handler) = 0;

268 chip  1.4  
269                /**

270 kumpf 1.8      \Label{modifyInstance}
271                Replace the current instance specified in the
272                instanceReference parameter.

273 chip  1.9  

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

284 chip  1.9  

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

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

296 kumpf 1.8      exception.

297 chip  1.9  

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

300 chip  1.4  
301                @param instanceReference specifies the fully qualified object path of the instance of interest.
302            

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

305 chip  1.4  

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

309 chip  1.4  

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

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

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

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

317 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
318                delivery of results.

319 chip  1.4  

320 kumpf 1.17     @exception CIMNotSupportedException
321                @exception CIMInvalidParameterException
322                @exception CIMObjectNotFoundException
323                @exception CIMAccessDeniedException
324                @exception CIMOperationFailedException

325 chip  1.4      */
326                virtual void modifyInstance(

327 chip  1.9          const OperationContext & context,
328                    const CIMObjectPath & instanceReference,
329                    const CIMInstance & instanceObject,

330 kumpf 1.15         const Boolean includeQualifiers,

331 chip  1.9          const CIMPropertyList & propertyList,

332 kumpf 1.14         ResponseHandler & handler) = 0;

333 chip  1.4  
334                /**

335 kumpf 1.8      \Label{createInstance}
336                Create a new instance.

337 chip  1.4  

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

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

349 chip  1.4  
350                @param instanceObject contains the partial or complete instance to create.

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

356 chip  1.4  

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

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

360 chip  1.4  

361 kumpf 1.17     @exception CIMNotSupportedException
362                @exception CIMInvalidParameterException

363 kumpf 1.20     @exception CIMObjectAlreadyExistsException

364 kumpf 1.17     @exception CIMAccessDeniedException
365                @exception CIMOperationFailedException

366 chip  1.4      */
367                virtual void createInstance(

368 chip  1.9          const OperationContext & context,
369                    const CIMObjectPath & instanceReference,
370                    const CIMInstance & instanceObject,

371 kumpf 1.14         ObjectPathResponseHandler & handler) = 0;

372 chip  1.4  
373                /**

374 kumpf 1.8      \Label{deleteInstance}
375                Delete the instance specified by the instanceReference parameter.

376 chip  1.4  

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

379 chip  1.4  

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

383 kumpf 1.17     {@link CIMObjectNotFoundException ObjectNotFound} exception.

384 chip  1.4  

385 kumpf 1.8      @param handler {@link ResponseHandler ResponseHandler} object for
386                delivery of results.

387 chip  1.4  

388 kumpf 1.17     @exception CIMNotSupportedException
389                @exception CIMInvalidParameterException
390                @exception CIMObjectNotFoundException
391                @exception CIMAccessDeniedException
392                @exception CIMOperationFailedException

393 chip  1.4      */
394                virtual void deleteInstance(

395 chip  1.9          const OperationContext & context,
396                    const CIMObjectPath & instanceReference,

397 kumpf 1.14         ResponseHandler & handler) = 0;

398 chip  1.1  };
399            
400            PEGASUS_NAMESPACE_END
401            
402            #endif