1 karl  1.29 //%2006////////////////////////////////////////////////////////////////////////

  2 chip  1.1  //

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

  7 karl  1.27 // 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.28 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10            // EMC Corporation; VERITAS Software Corporation; The Open Group.

 11 karl  1.29 // 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.21 // 

 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_CIMIndicationProvider_h
 35            #define Pegasus_CIMIndicationProvider_h
 36            
 37            #include <Pegasus/Common/Config.h>

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

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

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

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

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

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

 45 chip  1.1  
 46            PEGASUS_NAMESPACE_BEGIN
 47            
 48            /**

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

 53 chip  1.1  */

 54 kumpf 1.30 class PEGASUS_PROVIDER_LINKAGE CIMIndicationProvider :
 55                public virtual CIMProvider

 56 chip  1.1  {
 57            public:

 58 kumpf 1.23     /** Constructs a CIMIndicationProvider instance with

 59 karl  1.22         null values (default constructor).
 60                */

 61 kumpf 1.30     CIMIndicationProvider();

 62 kumpf 1.23 
 63                /** Destructs the CIMIndicationProvider.

 64 karl  1.22     */

 65 kumpf 1.30     virtual ~CIMIndicationProvider();

 66 chip  1.1  

 67 kumpf 1.23     /** Instructs the provider to begin generating indications.  One or
 68                    more createSubscription calls may precede the call to this method.
 69                    (On start-up, createSubscription is called for each active
 70                    subscription before the enableIndications method is called, so that
 71                    the provider knows about all outstanding subscriptions before it
 72                    begins generating indications.)
 73            

 74 kumpf 1.25         The provider must set the namespace and class name in the object path
 75                    of the generated indication instance (to allow the Indication Processor
 76                    to filter generated indications based on the Filter SourceNamespace and
 77                    Query indication class name), as in the following example:
 78            
 79                    <pre>
 80                     CIMObjectPath path(String::EMPTY,
 81                                       CIMNamespaceName("root/IndicationSource"),
 82                                       CIMName("IndicationClassName"),
 83                                       Array<CIMKeyBinding>());
 84                    indicationInstance.setPath(path);
 85                    </pre>
 86            
 87                    where "root/IndicationSource" is the namespace from which the
 88                    indication was generated, and "IndicationClassName" is the class name
 89                    of the generated indication.  Note that indication instance paths never
 90                    have key bindings.
 91            

 92 kumpf 1.23         An exception thrown by this method is considered a provider error
 93                    and does not affect CIM Server behavior.
 94            
 95                    @param handler An IndicationResponseHandler used by the provider to
 96                    deliver the indications it generates.  The IndicationResponseHandler
 97                    object remains valid until the disableIndications method is called.
 98                    After disableIndications is called, the behavior of the
 99                    IndicationResponseHandler is undefined.

100 chip  1.8      */

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

102 karl  1.22 

103 kumpf 1.23     /** Tells the provider to stop generating indications.  After this call,
104                    the IndicationResponseHandler given to the provider in the
105                    enableIndications method is no longer valid and its behavior is
106                    undefined.  Information regarding active subscriptions no longer
107                    applies to the provider and should be discarded at this time.
108                    (The provider will receive new createSubscription calls to restore
109                    necessary state before enableIndications is called again.)

110 chip  1.8  

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

113 chip  1.8      */

114 kumpf 1.30     virtual void disableIndications() = 0;

115 chip  1.8  

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

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

118 kumpf 1.30         CIMNotSupportedException.  An indication provider must reject the
119                    subscription as not supported if the provider cannot carry out the
120                    specified RepeatNotificationPolicy with the specified

121 kumpf 1.24         RepeatNotificationInterval, RepeatNotificationGap and
122                    RepeatNotificationCount.

123 kumpf 1.23 
124                    Note that it is not necessary for a simple indication provider to
125                    take any action on createSubscription, modifySubscription, or
126                    deleteSubscription.  It may simply generate indications (or not)
127                    based on the enableIndications and disableIndications calls.
128            
129                    An indication provider is not required to retain or make use of any
130                    specific subscription information.  (A provider that accepts a
131                    subscription with a RepeatNotificationPolicy value other than "None",
132                    however, requires this data for proper operation.)
133            
134                    An indication should only be generated once regardless of the
135                    number of active subscriptions.  The indication will be sent to
136                    each applicable handler.  If an indication should not be sent to all
137                    subscribers (such as when the provider has accepted one or more
138                    subscriptions with a RepeatNotificationPolicy defined), the provider
139                    must include in a SubscriptionInstanceNamesContainer the list of
140                    subscriptions for which the indication is intended.
141            

142 karl  1.22         @param context Similar to that in the other provider interfaces.
143                    Of particular interest to indication providers are the
144                    SubscriptionInstanceContainer and SubscriptionFilterConditionContainer
145                    containers.  The SubscriptionInstanceContainer contains the full
146                    CIM_IndicationSubscription instance (including, for example, more
147                    information about repeat notification policies).  The

148 kumpf 1.23         SubscriptionFilterConditionContainer contains the query string and
149                    query language from the CIM_IndicationFilter instance.
150            
151                    @param subscriptionName Specifies the object path of the
152                    CIM_IndicationSubscription instance for which this provider is
153                    requested to generate indications.
154            

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

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

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

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

159 karl  1.22         indications it generates.

160 kumpf 1.23 
161                    @param propertyList Specifies which properties of the specified
162                    class names must be (minimally) included in the indications
163                    generated for this subscription.
164            
165                    @param repeatNotificationPolicy Contains the value of the property
166                    with the same name in the CIM_IndicationSubscription instance.  Most
167                    providers will probably not support repeat notification policies, and
168                    should throw a CIMNotSupportedException if the value is anything
169                    other than "None".

170 chip  1.8      */

171 chip  1.9      virtual void createSubscription(

172 chip  1.14         const OperationContext & context,
173                    const CIMObjectPath & subscriptionName,
174                    const Array<CIMObjectPath> & classNames,
175                    const CIMPropertyList & propertyList,
176                    const Uint16 repeatNotificationPolicy) = 0;

177 chip  1.8  

178 kumpf 1.23     /** Informs the provider that the specified subscription instance has
179                    changed.
180            

181 karl  1.22         @param context Similar to that in the other provider interfaces.
182                    Of particular interest to indication providers are the
183                    SubscriptionInstanceContainer and SubscriptionFilterConditionContainer
184                    containers.  The SubscriptionInstanceContainer contains the full
185                    CIM_IndicationSubscription instance (including, for example, more
186                    information about repeat notification policies).  The

187 kumpf 1.23         SubscriptionFilterConditionContainer contains the query string and
188                    query language from the CIM_IndicationFilter instance.
189            
190                    @param subscriptionName Specifies the object path of the
191                    CIM_IndicationSubscription instance that is being modified and for
192                    which this provider has been requested to generate indications.
193            

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

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

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

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

198 karl  1.22         indications it generates.

199 kumpf 1.23 
200                    @param propertyList Specifies which properties of the specified
201                    class names must be (minimally) included in the indications generated
202                    for this subscription.
203            
204                    @param repeatNotificationPolicy Contains the value of the property
205                    with the same name in the CIM_IndicationSubscription instance.  Most
206                    providers will probably not support repeat notification policies, and
207                    should throw a CIMNotSupportedException if the value is anything
208                    other than "None".

209 chip  1.11     */

210 chip  1.9      virtual void modifySubscription(

211 chip  1.14         const OperationContext & context,
212                    const CIMObjectPath & subscriptionName,
213                    const Array<CIMObjectPath> & classNames,
214                    const CIMPropertyList & propertyList,
215                    const Uint16 repeatNotificationPolicy) = 0;

216 chip  1.8  

217 kumpf 1.23     /** Instructs the provider to stop monitoring for indications matching
218                    the specified subscription.
219            
220                    An exception thrown by this method is considered a provider error
221                    and does not affect CIM Server behavior.
222            

223 karl  1.22         @param context Similar to that in the other provider interfaces.
224                    Of particular interest to indication providers are the
225                    SubscriptionInstanceContainer and SubscriptionFilterConditionContainer
226                    containers.  The SubscriptionInstanceContainer contains the full
227                    CIM_IndicationSubscription instance (including, for example, more
228                    information about repeat notification policies).  The

229 kumpf 1.23         SubscriptionFilterConditionContainer contains the query string and
230                    query language from the CIM_IndicationFilter instance.
231            
232                    @param subscriptionName Specifies the object path of the
233                    CIM_IndicationSubscription instance for which this provider is
234                    requested to stop generating indications.
235            

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

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

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

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

241 chip  1.11     */

242 chip  1.10     virtual void deleteSubscription(

243 chip  1.14         const OperationContext & context,
244                    const CIMObjectPath & subscriptionName,
245                    const Array<CIMObjectPath> & classNames) = 0;

246 chip  1.5  };
247            

248 chip  1.1  PEGASUS_NAMESPACE_END
249            

250 chip  1.3  #endif