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 kumpf 1.25         Constructor.
 85                    The constructor should not do anything.

 86 kumpf 1.8      */

 87 kumpf 1.25     CIMInstanceProvider();

 88 kumpf 1.8  
 89                /**

 90 kumpf 1.25         Destructor.
 91                    The destructor should not do anything.

 92 kumpf 1.8      */

 93 kumpf 1.25     virtual ~CIMInstanceProvider();

 94 chip  1.1  

 95 chip  1.4      /**

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

 98 chip  1.1  

 99 kumpf 1.25         <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                    and deliver this to the CIM Server via the
105                    <tt>{@link ResponseHandler ResponseHandler}</tt>
106                    callback. If the specified instance does not exist, this
107                    function should throw an
108                    <tt>{@link CIMObjectNotFoundException CIMObjectNotFoundException}.</tt>
109                    </p>
110            
111                    <p>A provider can be implemented and registered to perform
112                    operations for
113                    several levels of the same line of descent (e.g.,
114                    CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
115                    is done, care must be taken to return the same set of key
116                    values regardless of which class was specified in the
117                    operation.</p>
118            
119                    @param context specifies the client user's context for this operation,
120 kumpf 1.25         including the User ID.
121            
122                    @param instanceReference specifies the fully qualified object path
123                    of the instance of interest.
124            
125                    @param includeQualifiers indicates whether the returned instance must
126                    include the qualifiers for the instance and properties.  Qualifiers may
127                    be included even if this flag is false.
128            
129                    @param includeClassOrigin indicates whether the returned instance must
130                    include the class origin for each of the instance elements.
131            
132                    @param propertyList if not null, this parameter
133                    specifies the minimum set of properties required in instances
134                    returned by this operation. Because
135                    support for this parameter is optional, the instances may contain
136                    additional properties not specified in the list.
137                    NOTE: The provider does NOT receive the client filtering parameter
138                    localOnly.  This is resolved in the CIMOM into the propertyList so
139                    that the property list represents the complete set of properties to
140                    be returned.
141 kumpf 1.25         If the propertyList is NULL all properties are returned.  If it is
142                    nonNULL but empty, no properites are to be returned.
143            
144                    @param handler a {@link ResponseHandler ResponseHandler} object used
145                    to deliver results to the CIM Server.
146            
147                    @exception CIMNotSupportedException
148                    @exception CIMInvalidParameterException
149                    @exception CIMObjectNotFoundException
150                    @exception CIMAccessDeniedException
151                    @exception CIMOperationFailedException

152 chip  1.4      */
153                virtual void getInstance(

154 kumpf 1.25         const OperationContext& context,
155                    const CIMObjectPath& instanceReference,

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

158 kumpf 1.25         const CIMPropertyList& propertyList,
159                    InstanceResponseHandler& handler) = 0;

160 chip  1.4  
161                /**

162 kumpf 1.25         \Label{enumerateInstances}
163                    Return all instances of the specified class.

164 kumpf 1.8  

165 kumpf 1.25         <p>A typical implementation of this function will call the
166                    <tt>{@link processing processing}</tt> function in the
167                    <tt>{@link ResponseHandler handler}</tt> object, then
168                    iterate over the system resources representing instances of
169                    the CIM object, calling <tt>{@link deliver deliver}</tt> on
170                    each iteration. It must call <tt>deliver</tt> with an
171                    argument of type <tt>{@link CIMInstance CIMInstance}</tt>.
172                    Finally, it will call <tt>{@link complete complete}</tt> to
173                    inform the CIM Server that it has delivered all known instances.</p>
174            
175                    <p>A provider can be implemented and registered to perform
176                    operations for several levels of the same line of descent (e.g.,
177                    CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
178                    is done, the provider must return instances <i>only</i>
179                    for the deepest class for which it is registered, since
180                    the CIM Server will invoke <tt>enumerateInstances</tt> for all
181                    classes at and beneath that specified in the
182                    {@link CIMObjectPath classReference}.</p>
183            
184                    @param context specifies the client user's context for this operation,
185                    including the User ID.
186 kumpf 1.25 
187                    @param classReference specifies the fully qualified object path
188                    to the class of interest.
189            
190                    @param includeQualifiers indicates whether the returned instances must
191                    include the qualifiers for the instance and properties.  Qualifiers may
192                    be included even if this flag is false.
193            
194                    @param includeClassOrigin indicates whether the returned instances must
195                    include the class origin for each of the instance elements.
196            
197                    @param propertyList If not null, this parameter specifies the minimum
198                    set of properties required in instances returned by this operation.
199                    Because support for this parameter is optional, the instances may
200                    contain additional properties not specified in the list. NOTE: The
201                    provider does NOT receive the client filtering parameters localOnly
202                    or deepInheritance.  These are resolved in the CIM Server into the
203                    propertyList.
204            
205                    @param handler {@link ResponseHandler ResponseHandler} object for
206                    delivery of results.
207 kumpf 1.25 
208                    @exception CIMNotSupportedException
209                    @exception CIMInvalidParameterException
210                    @exception CIMObjectNotFoundException
211                    <br>should never be thrown by this function; if
212                    there are no instances to return, this function should deliver an empty
213                    set of instances by calling the
214                    handler's <tt>{@link processing processing} </tt> and
215                    <tt>{@link complete complete}</tt> functions without calling
216                    <tt>{@link deliver deliver}</tt>.

217 kumpf 1.17 

218 kumpf 1.25         @exception CIMAccessDeniedException
219                    @exception CIMOperationFailedException

220 chip  1.4      */
221                virtual void enumerateInstances(

222 kumpf 1.25         const OperationContext& context,
223                    const CIMObjectPath& classReference,

224 kumpf 1.15         const Boolean includeQualifiers,
225                    const Boolean includeClassOrigin,

226 kumpf 1.25         const CIMPropertyList& propertyList,
227                    InstanceResponseHandler& handler) = 0;

228 chip  1.4  
229                /**

230 kumpf 1.25         \Label{enumerateInstanceNames}
231                    Return all instance names of a single class.

232 chip  1.4  

233 kumpf 1.25         <p>Like <tt>enumerateInstances</tt>, a typical implementation
234                    of <tt>enumerateInstanceNames</tt> will call the
235                    <tt>{@link processing processing}</tt> function in the
236                    <tt>{@link ResponseHandler handler}</tt> object, then
237                    iterate over the system resources representing instances of
238                    the CIM object, calling <tt>{@link deliver deliver}</tt> on
239                    each iteration. It must call {@link deliver deliver} with an
240                    argument of type <tt>{@link CIMObjectPath CIMObjectPath}</tt>
241                    containing the information that uniquely identifies each
242                    instance.
243                    Finally, it will call <tt>{@link complete complete}</tt> to
244                    inform the CIM Server that it has delivered all known instances.</p>
245            
246                    <p>A provider can be implemented and registered to perform
247                    operations for several levels of the same line of descent (e.g.,
248                    CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
249                    is done, the provider must return instance names <i>only</i>
250                    for the deepest class for which it is registered, since
251                    the CIM Server will invoke <tt>enumerateInstanceNames</tt> for all
252                    classes at and beneath that specified in the
253                    {@link CIMObjectPath classReference}.</p>
254 kumpf 1.25 
255                    @param context specifies the client user's context for this operation,
256                    including the User ID.
257            
258                    @param classReference specifies the fully qualified object path to
259                    the class of interest.
260            
261                    @param handler {@link ResponseHandler ResponseHandler} object for
262                    delivery of results.
263            
264                    @exception CIMNotSupportedException
265                    @exception CIMInvalidParameterException
266                    @exception CIMObjectNotFoundException
267                    @exception CIMAccessDeniedException
268                    @exception CIMOperationFailedException

269 chip  1.4      */
270                virtual void enumerateInstanceNames(

271 kumpf 1.25         const OperationContext& context,
272                    const CIMObjectPath& classReference,
273                    ObjectPathResponseHandler& handler) = 0;

274 chip  1.4  
275                /**

276 kumpf 1.25         \Label{modifyInstance}
277                    Replace the current instance specified in the
278                    instanceReference parameter.
279            
280                    <p><tt>modifyInstance</tt> sets the values of properties of
281                    the instance specified by the <tt>instanceReference</tt> parameter
282                    to those specified in the <tt>instanceObject</tt> parameter, as
283                    controlled by the <tt>propertyList</tt> parameter. If the
284                    <tt>propertyList</tt>
285                    is NULL, then the operation sets all properties. Otherwise,
286                    it sets only those specified in the <tt>propertyList</tt>.
287                    Properties specified in the <tt>propertyList</tt> but not present in
288                    the <tt>instanceObject</tt> are replaced by
289                    the class default values or left null.</p>
290            
291                    <p>Ideally, <tt>modifyInstance</tt> is intended to be
292                    an <i>atomic</i> operation on values of the instance. That is,
293                    concurrent accesses to the instance by other threads should be
294                    blocked during the operation, so that all of the affected property
295                    values can be
296                    changed without intervening accesses by concurrent requests.
297 kumpf 1.25         Otherwise, other requests could obtain intermediate, and
298                    possibly inconsistent, results.</p>
299            
300                    <p>If the specified instance does not exist, the provider
301                    should throw an {@link CIMObjectNotFoundException ObjectNotFound}
302                    exception.
303            
304                    @param context specifies the client user's context for this operation,
305                    including the User ID.
306            
307                    @param instanceReference specifies the fully qualified object path
308                    of the instance of interest.
309            
310                    @param instanceObject contains the partial or complete set of
311                    properties whose values should be changed.
312            
313                    @param includeQualifiers indicates whether the instance qualifiers must
314                    be updated as specified in the modified instance.  If false, no
315                    qualifiers are explicitly modified by this operation.
316            
317                    @param propertyList If not null, this parameter specifies the set
318 kumpf 1.25         of properties required to be updated in the instance. Support for
319                    this parameter is NOT optional.  Providers that do not support this
320                    feature must throw a
321                    {@link CIMNotSupportedException CIMNotSupportedException} exception.
322                    NOTE: The provider does NOT receive the client filtering parameters
323                    localOnly or deepInheritance.  These are resolved in the CIMOM into
324                    the propertyList.
325            
326                    @param handler {@link ResponseHandler ResponseHandler} object for
327                    delivery of results.
328            
329                    @exception CIMNotSupportedException
330                    @exception CIMInvalidParameterException
331                    @exception CIMObjectNotFoundException
332                    @exception CIMAccessDeniedException
333                    @exception CIMOperationFailedException

334 chip  1.4      */
335                virtual void modifyInstance(

336 kumpf 1.25         const OperationContext& context,
337                    const CIMObjectPath& instanceReference,
338                    const CIMInstance& instanceObject,

339 kumpf 1.15         const Boolean includeQualifiers,

340 kumpf 1.25         const CIMPropertyList& propertyList,
341                    ResponseHandler& handler) = 0;

342 chip  1.4  
343                /**

344 kumpf 1.25         \Label{createInstance}
345                    Create a new instance.

346 chip  1.4  

347 kumpf 1.25         <p>Create a new instance of the specified class as specified
348                    by the <tt>instanceReference</tt> and <tt>instanceObject</tt>
349                    parameters.</p>
350            
351                    @param context specifies the client user's context for this operation,
352                    including the User ID.
353            
354                    @param instanceReference Specifies the namespace and class name
355                    of the instance to create.  The key bindings are not present in
356                    the instanceReference, because an instance name is not defined
357                    until after the instance has been created.
358            
359                    @param instanceObject contains the partial or complete instance to
360                    create.  If a key property is null, the provider <em>must</em> supply
361                    a valid value for the property or throw a
362                    {@link CIMInvalidParameterException CIMInvalidParameterException}.
363                    If any property value is invalid, the provider should throw a
364                    {@link CIMInvalidParameterException CIMInvalidParameterException}.
365            
366                    @param handler {@link ResponseHandler ResponseHandler} object for
367                    delivery of results.  If the operation is successful, the provider must
368 kumpf 1.25         deliver the complete instance name of the created instance.
369            
370                    @exception CIMNotSupportedException
371                    @exception CIMInvalidParameterException
372                    @exception CIMObjectAlreadyExistsException
373                    @exception CIMAccessDeniedException
374                    @exception CIMOperationFailedException

375 chip  1.4      */
376                virtual void createInstance(

377 kumpf 1.25         const OperationContext& context,
378                    const CIMObjectPath& instanceReference,
379                    const CIMInstance& instanceObject,
380                    ObjectPathResponseHandler& handler) = 0;

381 chip  1.4  
382                /**

383 kumpf 1.25         \Label{deleteInstance}
384                    Delete the instance specified by the instanceReference parameter.

385 chip  1.4  

386 kumpf 1.25         @param context specifies the client user's context for this operation,
387                    including the User ID.

388 chip  1.4  

389 kumpf 1.25         @param instanceReference specifies the fully qualified object
390                    path of the instance to delete. If the specified object does
391                    not exist, the provider should throw an
392                    {@link CIMObjectNotFoundException ObjectNotFound} exception.
393            
394                    @param handler {@link ResponseHandler ResponseHandler} object for
395                    delivery of results.
396            
397                    @exception CIMNotSupportedException
398                    @exception CIMInvalidParameterException
399                    @exception CIMObjectNotFoundException
400                    @exception CIMAccessDeniedException
401                    @exception CIMOperationFailedException

402 chip  1.4      */
403                virtual void deleteInstance(

404 kumpf 1.25         const OperationContext& context,
405                    const CIMObjectPath& instanceReference,
406                    ResponseHandler& handler) = 0;

407 chip  1.1  };
408            
409            PEGASUS_NAMESPACE_END
410            
411            #endif