1 karl  1.21 //%2003////////////////////////////////////////////////////////////////////////

  2 chip  1.1  //

  3 karl  1.21 // 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            // IBM Corp.; EMC Corporation, The Open Group.

  7 chip  1.1  //
  8            // Permission is hereby granted, free of charge, to any person obtaining a copy
  9            // of this software and associated documentation files (the "Software"), to
 10            // deal in the Software without restriction, including without limitation the
 11            // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 12            // sell copies of the Software, and to permit persons to whom the Software is
 13            // furnished to do so, subject to the following conditions:

 14 karl  1.21 // 

 15 chip  1.1  // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 16            // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 17            // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 18            // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 19            // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 20            // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 21            // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 22            // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 23            //
 24            //==============================================================================
 25            //
 26            // Author: Chip Vincent (cvincent@us.ibm.com)
 27            //

 28 chip  1.11 // Modified By:

 29 chip  1.1  //
 30            //%/////////////////////////////////////////////////////////////////////////////
 31            
 32            #ifndef Pegasus_CIMIndicationProvider_h
 33            #define Pegasus_CIMIndicationProvider_h
 34            
 35            #include <Pegasus/Common/Config.h>

 36 kumpf 1.20 #include <Pegasus/Provider/CIMProvider.h>

 37 chip  1.1  
 38            #include <Pegasus/Common/Array.h>

 39 kumpf 1.7  #include <Pegasus/Common/CIMObjectPath.h>

 40 chip  1.1  #include <Pegasus/Common/CIMDateTime.h>

 41 chip  1.11 #include <Pegasus/Common/CIMIndication.h>

 42 kumpf 1.17 #include <Pegasus/Provider/Linkage.h>

 43 chip  1.1  
 44            PEGASUS_NAMESPACE_BEGIN
 45            
 46            /**

 47 kumpf 1.23     This class defines the set of methods implemented by an indication
 48                provider.  A provider that derives from this class must implement all
 49                methods.  A minimal method implementation simply throws a
 50                CIMNotSupportedException.

 51 chip  1.1  */

 52 kumpf 1.20 class PEGASUS_PROVIDER_LINKAGE CIMIndicationProvider : public virtual CIMProvider

 53 chip  1.1  {
 54            public:

 55 kumpf 1.23     /** Constructs a CIMIndicationProvider instance with

 56 karl  1.22         null values (default constructor).
 57                */

 58 chip  1.8      CIMIndicationProvider(void);

 59 kumpf 1.23 
 60                /** Destructs the CIMIndicationProvider.

 61 karl  1.22     */

 62 chip  1.8      virtual ~CIMIndicationProvider(void);

 63 chip  1.1  

 64 kumpf 1.23     /** Instructs the provider to begin generating indications.  One or
 65                    more createSubscription calls may precede the call to this method.
 66                    (On start-up, createSubscription is called for each active
 67                    subscription before the enableIndications method is called, so that
 68                    the provider knows about all outstanding subscriptions before it
 69                    begins generating indications.)
 70            
 71                    An exception thrown by this method is considered a provider error
 72                    and does not affect CIM Server behavior.
 73            
 74                    @param handler An IndicationResponseHandler used by the provider to
 75                    deliver the indications it generates.  The IndicationResponseHandler
 76                    object remains valid until the disableIndications method is called.
 77                    After disableIndications is called, the behavior of the
 78                    IndicationResponseHandler is undefined.

 79 chip  1.8      */

 80 kumpf 1.23     virtual void enableIndications(IndicationResponseHandler & handler) = 0;

 81 karl  1.22 

 82 kumpf 1.23     /** Tells the provider to stop generating indications.  After this call,
 83                    the IndicationResponseHandler given to the provider in the
 84                    enableIndications method is no longer valid and its behavior is
 85                    undefined.  Information regarding active subscriptions no longer
 86                    applies to the provider and should be discarded at this time.
 87                    (The provider will receive new createSubscription calls to restore
 88                    necessary state before enableIndications is called again.)

 89 chip  1.8  

 90 kumpf 1.23         An exception thrown by this method is considered a provider error
 91                    and does not affect CIM Server behavior.

 92 chip  1.8      */

 93 chip  1.11     virtual void disableIndications(void) = 0;

 94 chip  1.8  

 95 karl  1.22     /** Tells the provider to monitor for indications matching the specified

 96 kumpf 1.23         subscription.  The provider may reject the subscription by throwing a

 97 kumpf 1.24         CIMNotSupportedException.  An indication provider must reject the 
 98                    subscription as not supported if the provider cannot carry out the 
 99                    specified RepeatNotificationPolicy with the specified 
100                    RepeatNotificationInterval, RepeatNotificationGap and
101                    RepeatNotificationCount.

102 kumpf 1.23 
103                    Note that it is not necessary for a simple indication provider to
104                    take any action on createSubscription, modifySubscription, or
105                    deleteSubscription.  It may simply generate indications (or not)
106                    based on the enableIndications and disableIndications calls.
107            
108                    An indication provider is not required to retain or make use of any
109                    specific subscription information.  (A provider that accepts a
110                    subscription with a RepeatNotificationPolicy value other than "None",
111                    however, requires this data for proper operation.)
112            
113                    An indication should only be generated once regardless of the
114                    number of active subscriptions.  The indication will be sent to
115                    each applicable handler.  If an indication should not be sent to all
116                    subscribers (such as when the provider has accepted one or more
117                    subscriptions with a RepeatNotificationPolicy defined), the provider
118                    must include in a SubscriptionInstanceNamesContainer the list of
119                    subscriptions for which the indication is intended.
120            

121 karl  1.22         @param context Similar to that in the other provider interfaces.
122                    Of particular interest to indication providers are the
123                    SubscriptionInstanceContainer and SubscriptionFilterConditionContainer
124                    containers.  The SubscriptionInstanceContainer contains the full
125                    CIM_IndicationSubscription instance (including, for example, more
126                    information about repeat notification policies).  The

127 kumpf 1.23         SubscriptionFilterConditionContainer contains the query string and
128                    query language from the CIM_IndicationFilter instance.
129            
130                    @param subscriptionName Specifies the object path of the
131                    CIM_IndicationSubscription instance for which this provider is
132                    requested to generate indications.
133            

134 karl  1.22         @param classNames Contains a list of indication class names for

135 kumpf 1.23         which this provider has registered as an indication provider and are

136 karl  1.22         included in the CIM_IndicationFilter for this subscription instance.

137 kumpf 1.23         A provider may use this as medium-level data for controlling which

138 karl  1.22         indications it generates.

139 kumpf 1.23 
140                    @param propertyList Specifies which properties of the specified
141                    class names must be (minimally) included in the indications
142                    generated for this subscription.
143            
144                    @param repeatNotificationPolicy Contains the value of the property
145                    with the same name in the CIM_IndicationSubscription instance.  Most
146                    providers will probably not support repeat notification policies, and
147                    should throw a CIMNotSupportedException if the value is anything
148                    other than "None".

149 chip  1.8      */

150 chip  1.9      virtual void createSubscription(

151 chip  1.14         const OperationContext & context,
152                    const CIMObjectPath & subscriptionName,
153                    const Array<CIMObjectPath> & classNames,
154                    const CIMPropertyList & propertyList,
155                    const Uint16 repeatNotificationPolicy) = 0;

156 chip  1.8  

157 kumpf 1.23     /** Informs the provider that the specified subscription instance has
158                    changed.
159            

160 karl  1.22         @param context Similar to that in the other provider interfaces.
161                    Of particular interest to indication providers are the
162                    SubscriptionInstanceContainer and SubscriptionFilterConditionContainer
163                    containers.  The SubscriptionInstanceContainer contains the full
164                    CIM_IndicationSubscription instance (including, for example, more
165                    information about repeat notification policies).  The

166 kumpf 1.23         SubscriptionFilterConditionContainer contains the query string and
167                    query language from the CIM_IndicationFilter instance.
168            
169                    @param subscriptionName Specifies the object path of the
170                    CIM_IndicationSubscription instance that is being modified and for
171                    which this provider has been requested to generate indications.
172            

173 karl  1.22         @param classNames Contains a list of indication class names for

174 kumpf 1.23         which this provider has registered as an indication provider and are

175 karl  1.22         included in the CIM_IndicationFilter for this subscription instance.

176 kumpf 1.23         A provider can use this as medium-level data for controlling which

177 karl  1.22         indications it generates.

178 kumpf 1.23 
179                    @param propertyList Specifies which properties of the specified
180                    class names must be (minimally) included in the indications generated
181                    for this subscription.
182            
183                    @param repeatNotificationPolicy Contains the value of the property
184                    with the same name in the CIM_IndicationSubscription instance.  Most
185                    providers will probably not support repeat notification policies, and
186                    should throw a CIMNotSupportedException if the value is anything
187                    other than "None".

188 chip  1.11     */

189 chip  1.9      virtual void modifySubscription(

190 chip  1.14         const OperationContext & context,
191                    const CIMObjectPath & subscriptionName,
192                    const Array<CIMObjectPath> & classNames,
193                    const CIMPropertyList & propertyList,
194                    const Uint16 repeatNotificationPolicy) = 0;

195 chip  1.8  

196 kumpf 1.23     /** Instructs the provider to stop monitoring for indications matching
197                    the specified subscription.
198            
199                    An exception thrown by this method is considered a provider error
200                    and does not affect CIM Server behavior.
201            

202 karl  1.22         @param context Similar to that in the other provider interfaces.
203                    Of particular interest to indication providers are the
204                    SubscriptionInstanceContainer and SubscriptionFilterConditionContainer
205                    containers.  The SubscriptionInstanceContainer contains the full
206                    CIM_IndicationSubscription instance (including, for example, more
207                    information about repeat notification policies).  The

208 kumpf 1.23         SubscriptionFilterConditionContainer contains the query string and
209                    query language from the CIM_IndicationFilter instance.
210            
211                    @param subscriptionName Specifies the object path of the
212                    CIM_IndicationSubscription instance for which this provider is
213                    requested to stop generating indications.
214            

215 karl  1.22         @param classNames Contains a list of indication class names for

216 kumpf 1.23         which this provider has registered as an indication provider and are

217 karl  1.22         included in the CIM_IndicationFilter for this subscription instance.

218 kumpf 1.23         A provider can use this as medium-level data for controlling which
219                    indications it generates.

220 chip  1.11     */

221 chip  1.10     virtual void deleteSubscription(

222 chip  1.14         const OperationContext & context,
223                    const CIMObjectPath & subscriptionName,
224                    const Array<CIMObjectPath> & classNames) = 0;

225 chip  1.5  };
226            

227 chip  1.1  PEGASUS_NAMESPACE_END
228            

229 chip  1.3  #endif