1 martin 1.38 //%LICENSE////////////////////////////////////////////////////////////////

  2 martin 1.39 //

  3 martin 1.38 // 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.39 //

 10 martin 1.38 // 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.39 //

 17 martin 1.38 // The above copyright notice and this permission notice shall be included
 18             // in all copies or substantial portions of the Software.

 19 martin 1.39 //

 20 martin 1.38 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

 21 martin 1.39 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 22 martin 1.38 // 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.39 //

 28 martin 1.38 //////////////////////////////////////////////////////////////////////////

 29 mike   1.14 //
 30             //%/////////////////////////////////////////////////////////////////////////////
 31             

 32 kumpf  1.22 #ifndef Pegasus_CIMProvider_h
 33             #define Pegasus_CIMProvider_h

 34 mike   1.14 
 35             #include <Pegasus/Common/Config.h>

 36 kumpf  1.22 #include <Pegasus/Common/OperationContext.h>
 37             #include <Pegasus/Provider/CIMOMHandle.h>
 38             #include <Pegasus/Provider/ProviderException.h>
 39             #include <Pegasus/Common/ResponseHandler.h>
 40             #include <Pegasus/Provider/Linkage.h>

 41 mike   1.14 
 42             PEGASUS_NAMESPACE_BEGIN
 43             

 44 kumpf  1.22 /**

 45 kumpf  1.37     CIMProvider is the base class for the provider interface.  A provider
 46                 must implement all the interfaces of the CIMProvider class and one or
 47                 more of its subclasses (such as CIMInstanceProvider).  If a provider
 48                 does not support any of the operations specified by the interfaces,
 49                 it may just throw a CIMNotSupportedException.

 50 mike   1.14 

 51 kumpf  1.37     <p>Some of the parameters that are common to the provider operation
 52                 interfaces are:

 53 kumpf  1.22 

 54 kumpf  1.37     <ul>
 55                     <li>The OperationContext parameter contains information about the
 56                     context for the specified operation, including the user name of the
 57                     client requesting the operation.  It is the provider's responsibility
 58                     to determine whether the user is authorized to perform the operation.
 59                     If the operation should not be permitted, the provider must throw
 60                     a CIMAccessDeniedException.</li>
 61             
 62                     <li>A CIMObjectPath specifies the CIM object on which the operation
 63                     is to be performed.  This parameter specifies the hostname, namespace,
 64                     classname, and key values that uniquely identify a CIM instance.</li>

 65 kumpf  1.22 

 66 kumpf  1.37         <li>A ResponseHandler is a callback handle used by the provider to
 67                     deliver response data to the CIM Server.</li>
 68                 </ul>

 69 kumpf  1.22 */

 70 mike   1.18 class PEGASUS_PROVIDER_LINKAGE CIMProvider

 71 mike   1.14 {
 72             public:

 73 kumpf  1.37     /**
 74                     Default constructor for the abstract CIMProvider class.
 75                 */
 76                 CIMProvider();

 77 mike   1.14 

 78 kumpf  1.22     /**

 79 kumpf  1.37         Destructs the CIMProvider instance.
 80                 */
 81                 virtual ~CIMProvider();

 82 mike   1.14 

 83 kumpf  1.37     /**
 84                     Initializes the provider.  This method is called each time the
 85                     provider is loaded and must complete before any of the other
 86                     provider methods (other than terminate) are called.
 87             
 88                     An exception thrown from this method indicates a provider
 89                     initialization failure which prevents it from processing operation
 90                     requests.

 91 kumpf  1.36 

 92 kumpf  1.37         @param cimom Reserved for future use.

 93 kumpf  1.22     */
 94                 virtual void initialize(CIMOMHandle & cimom) = 0;

 95 mike   1.14 
 96                 /**

 97 kumpf  1.37         Performs any cleanup required before the provider is unloaded.
 98                     This method may be called by the CIM Server at any time, including
 99                     during initialization.  No other provider methods are called after
100                     this method is invoked.
101             
102                     <p>Examples of cleanup a provider may perform in this method include:
103                     <ul>
104                         <li>Closing files and/or I/O streams</li>
105                         <li>Releasing resources such as shared memory</li>
106                         <li>Informing concurrently executing requests to complete
107                             immediately (perhaps by setting a global flag)</li>
108                         <li>Terminating subprocesses</li>
109                     </ul>
110             
111                     <p>If the PegasusCreateProvider function dynamically instantiates the
112                     provider with the "new" operator, then the terminate() method must
113                     "delete" it:
114             
115                         <pre>
116                         void MyProvider::terminate()
117                         {
118 kumpf  1.37                 ...
119                             delete this;
120                         }
121                         </pre>

122 kumpf  1.36 

123 kumpf  1.37         <p>An exception thrown from this method is considered to be a provider
124                     error and is ignored.

125 mike   1.14     */

126 kumpf  1.37     virtual void terminate() = 0;

127 mike   1.14 };
128             
129             PEGASUS_NAMESPACE_END
130             

131 kumpf  1.22 #endif