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 mday  1.10.6.1 #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 mday  1.10.6.1 
 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