1 kumpf 1.4 //%/////////////////////////////////////////////////////////////////////////////

  2 mike  1.2 //

  3 kumpf 1.4 // Copyright (c) 2000, 2001, 2002 BMC Software, Hewlett-Packard Company, IBM,
  4           // The Open Group, Tivoli Systems

  5 mike  1.2 //
  6           // Permission is hereby granted, free of charge, to any person obtaining a copy
  7           // of this software and associated documentation files (the "Software"), to
  8           // deal in the Software without restriction, including without limitation the
  9           // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 10           // sell copies of the Software, and to permit persons to whom the Software is
 11           // furnished to do so, subject to the following conditions:
 12           //
 13           // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 14           // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 15           // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 16           // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 17           // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 18           // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 19           // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 20           // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 21           //
 22           //==============================================================================
 23           //
 24           // Author: Chip Vincent (cvincent@us.ibm.com)
 25           //

 26 kumpf 1.4 // Modified By: Roger Kumpf, Hewlett-Packard Company (roger_kumpf@hp.com)

 27 mike  1.2 //
 28           //%/////////////////////////////////////////////////////////////////////////////
 29           
 30           #ifndef Pegasus_ResponseHandler_h
 31           #define Pegasus_ResponseHandler_h
 32           
 33           #include <Pegasus/Common/Config.h>
 34           #include <Pegasus/Common/Array.h>

 35 kumpf 1.6 #include <Pegasus/Common/Linkage.h>

 36 kumpf 1.4 
 37           #include <Pegasus/Common/CIMInstance.h>
 38           #include <Pegasus/Common/CIMObjectPath.h>
 39           #include <Pegasus/Common/CIMParamValue.h>
 40           #include <Pegasus/Common/CIMValue.h>
 41           #include <Pegasus/Common/CIMIndication.h>
 42           #include <Pegasus/Common/CIMObject.h>
 43           #include <Pegasus/Common/CIMClass.h>

 44 kumpf 1.8 #include <Pegasus/Common/OperationContext.h>

 45 chuck 1.11 #include <Pegasus/Common/ContentLanguages.h>  //l10n
 46            

 47 mike  1.2  

 48 kumpf 1.10 

 49 mike  1.2  PEGASUS_NAMESPACE_BEGIN
 50            

 51 kumpf 1.4  /**
 52            <p>The <tt>ResponseHandler</tt> class allows a provider

 53 kumpf 1.10 to report operation progress and results to the CIM Server.

 54 kumpf 1.4  Subclasses are defined for each of the types of object

 55 kumpf 1.10 that a provider can deliver to the CIM Server.

 56 kumpf 1.4  A <tt>ResponseHandler</tt> object of the appropriate type
 57            is passed to provider
 58            functions that are invoked to process client requests (it
 59            is not passed to the <tt>{@link initialize initialize}</tt>
 60            or <tt>{@link terminate terminate}</tt> functions). It
 61            contains the following public member functions that

 62 kumpf 1.10 may be used to deliver results to the CIM Server:</p>

 63 kumpf 1.4  <ul>

 64 kumpf 1.10 <li><tt>{@link processing processing}</tt> - inform the CIM Server
 65            that delivery of results is beginning.</li>

 66 kumpf 1.4  <li><tt>{@link deliver deliver}</tt> - deliver an incremental

 67 kumpf 1.10 result to the CIM Server; the CIM Server accumulates results as
 68            they are received from the provider.</li>
 69            <li><tt>{@link complete complete}</tt> - inform the CIM Server that

 70 kumpf 1.4  process of the request is complete and that no further

 71 kumpf 1.10 results will be delivered.</li>

 72 kumpf 1.4  </ul>
 73            */
 74            

 75 kumpf 1.5  class PEGASUS_COMMON_LINKAGE ResponseHandler

 76 kumpf 1.4  {
 77            public:
 78            
 79                /**
 80                Destructor.
 81                */
 82                virtual ~ResponseHandler(void);
 83            

 84 kumpf 1.10     // This method is defined in subclasses, specialized for 
 85                // the appropriate data type.

 86 kumpf 1.4      //virtual void deliver(const T & object);
 87            

 88 kumpf 1.10     // This method is defined in subclasses, specialized for 
 89                // the appropriate data type.

 90 kumpf 1.4      //virtual void deliver(const Array<T> & objects);
 91            
 92                /**

 93 kumpf 1.10     Inform the CIM Server that delivery of results will begin.

 94 kumpf 1.4      <p>The provider must call <tt>processing</tt> before
 95                attempting to call <tt>deliver</tt>.
 96                */
 97                virtual void processing(void) = 0;

 98 chuck 1.11 
 99            // l10n
100                /**
101                Inform the CIM Server of the language(s) of the results.
102                <p>The provider may call, but is not required to call, 
103                <tt>setLanguages</tt> before attempting to call <tt>deliver</tt>.
104                */
105                virtual void setLanguages(const ContentLanguages & languages) = 0;

106 kumpf 1.4  
107                /**

108 kumpf 1.10     Inform the CIM Server that delivery of results is complete.

109 kumpf 1.4      <p>The provider must call <tt>complete</tt> when all
110                results have been delivered. It must not call <tt>deliver</tt>
111                after calling <tt>complete</tt>.</p>
112                */
113                virtual void complete(void) = 0;
114            };
115            
116            
117            //
118            // InstanceResponseHandler

119 kumpf 1.10 ///

120 kumpf 1.5  class PEGASUS_COMMON_LINKAGE InstanceResponseHandler : virtual public ResponseHandler

121 kumpf 1.4  {
122            public:

123 kumpf 1.10     /** <p>The <tt>deliver</tt> function is used by providers to
124                    deliver results to the CIM Server. For operations that require a
125                    single element result (<tt>getInstance</tt>, for example),
126                    <tt>deliver</tt> should be called only once to deliver the
127                    entire result. For operations that involve
128                    enumeration, the single-element form shown here may be
129                    used, each iteration delivering an incremental element
130                    of the total result. The Array form below may be used
131                    to deliver a larger set of result elements.</p>
132                */

133 kumpf 1.4      virtual void deliver(const CIMInstance & instance) = 0;
134            

135 kumpf 1.10     /** <p>This form of the <tt>deliver</tt> function may be used
136                    to return a set of elements to the CIM Server. The set is not
137                    required to be complete, and the provider may invoke this
138                    function multiple times, if necessary. This form should only
139                    be used when the operation requires a result consisting
140                    of more than one element, such as an enumeration.</p>
141                */

142 kumpf 1.4      virtual void deliver(const Array<CIMInstance> & instances) = 0;
143            };
144            
145            
146            //
147            // ObjectPathResponseHandler

148 kumpf 1.10 ///

149 kumpf 1.5  class PEGASUS_COMMON_LINKAGE ObjectPathResponseHandler : virtual public ResponseHandler

150 kumpf 1.4  {
151            public:

152 kumpf 1.10     /** <p>The <tt>deliver</tt> function is used by providers to
153                    deliver results to the CIM Server. For operations that require a
154                    single element result (<tt>getInstance</tt>, for example),
155                    <tt>deliver</tt> should be called only once to deliver the
156                    entire result. For operations that involve
157                    enumeration, the single-element form shown here may be
158                    used, each iteration delivering an incremental element
159                    of the total result. The Array form below may be used
160                    to deliver a larger set of result elements.</p>
161                */

162 kumpf 1.4      virtual void deliver(const CIMObjectPath & objectPath) = 0;
163            

164 kumpf 1.10     /** <p>This form of the <tt>deliver</tt> function may be used
165                    to return a set of elements to the CIM Server. The set is not
166                    required to be complete, and the provider may invoke this
167                    function multiple times, if necessary. This form should only
168                    be used when the operation requires a result consisting
169                    of more than one element, such as an enumeration.</p>
170                */

171 kumpf 1.4      virtual void deliver(const Array<CIMObjectPath> & objectPaths) = 0;
172            };
173            
174            
175            //
176            // MethodResultResponseHandler

177 kumpf 1.10 ///

178 kumpf 1.5  class PEGASUS_COMMON_LINKAGE MethodResultResponseHandler : virtual public ResponseHandler

179 kumpf 1.4  {
180            public:

181 kumpf 1.10     ///

182 kumpf 1.4      virtual void deliverParamValue(const CIMParamValue & outParamValue) = 0;
183            

184 kumpf 1.10     ///

185 kumpf 1.4      virtual void deliverParamValue(const Array<CIMParamValue> & outParamValues) = 0;
186            

187 kumpf 1.10     ///

188 kumpf 1.4      virtual void deliver(const CIMValue & returnValue) = 0;
189            };
190            
191            
192            //
193            // IndicationResponseHandler
194            //

195 kumpf 1.8  // NOTE: This class definition should not be considered complete until
196            // indication support has been completed in Pegasus.  Implementation of
197            // indication support may reveal a need for API changes in this class.

198 kumpf 1.5  class PEGASUS_COMMON_LINKAGE IndicationResponseHandler : virtual public ResponseHandler

199 kumpf 1.4  {
200            public:
201                virtual void deliver(const CIMIndication & indication) = 0;
202            
203                virtual void deliver(const Array<CIMIndication> & indications) = 0;

204 kumpf 1.8  
205                virtual void deliver(
206                    const OperationContext & context,
207                    const CIMIndication & indication) = 0;
208            
209                virtual void deliver(
210                    const OperationContext & context,
211                    const Array<CIMIndication> & indications) = 0;

212 kumpf 1.4  };
213            
214            
215            //
216            // ObjectResponseHandler
217            //

218 kumpf 1.9  // NOTE: This class definition should not be considered complete until
219            // association provider and/or query provider support has been completed
220            // in Pegasus, as those are the only APIs that use this response handler
221            // type.  Implementation of support for those provider types may reveal
222            // a need for API changes in this class.

223 kumpf 1.10 ///

224 kumpf 1.5  class PEGASUS_COMMON_LINKAGE ObjectResponseHandler : virtual public ResponseHandler

225 kumpf 1.4  {
226            public:

227 kumpf 1.10     /** <p>The <tt>deliver</tt> function is used by providers to
228                    deliver results to the CIM Server. For operations that require a
229                    single element result (<tt>getInstance</tt>, for example),
230                    <tt>deliver</tt> should be called only once to deliver the
231                    entire result. For operations that involve
232                    enumeration, the single-element form shown here may be
233                    used, each iteration delivering an incremental element
234                    of the total result. The Array form below may be used
235                    to deliver a larger set of result elements.</p>
236                */

237 kumpf 1.4      virtual void deliver(const CIMObject & object) = 0;
238            

239 kumpf 1.10     /** <p>This form of the <tt>deliver</tt> function may be used
240                    to return a set of elements to the CIM Server. The set is not
241                    required to be complete, and the provider may invoke this
242                    function multiple times, if necessary. This form should only
243                    be used when the operation requires a result consisting
244                    of more than one element, such as an enumeration.</p>
245                */

246 kumpf 1.4      virtual void deliver(const Array<CIMObject> & objects) = 0;
247            };
248            
249            

250 kumpf 1.7  #ifdef PEGASUS_INTERNALONLY
251            // This type is used in CIMPropertyProvider which Pegasus does not support

252 kumpf 1.4  //
253            // ValueResponseHandler
254            //

255 kumpf 1.5  class PEGASUS_COMMON_LINKAGE ValueResponseHandler : virtual public ResponseHandler

256 kumpf 1.4  {
257            public:
258                virtual void deliver(const CIMValue & value) = 0;
259            
260                virtual void deliver(const Array<CIMValue> & values) = 0;
261            };

262 kumpf 1.7  #endif

263 kumpf 1.4  
264            

265 kumpf 1.7  #ifdef PEGASUS_INTERNALONLY
266            // This type is used in CIMClassProvider which Pegasus does not support

267 kumpf 1.4  //
268            // ClassResponseHandler
269            //

270 kumpf 1.5  class PEGASUS_COMMON_LINKAGE ClassResponseHandler : virtual public ResponseHandler

271 mike  1.2  {
272            public:

273 kumpf 1.4      virtual void deliver(const CIMClass & classObj) = 0;

274 mike  1.2  

275 kumpf 1.4      virtual void deliver(const Array<CIMClass> & classObjs) = 0;

276 mike  1.2  };

277 kumpf 1.7  #endif

278 mike  1.2  
279            PEGASUS_NAMESPACE_END
280            
281            #endif