1 chip 1.1 //%//-*-c++-*-///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2000, 2001 The Open group, BMC Software, Tivoli Systems, IBM
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a copy
6 // of this software and associated documentation files (the "Software"), to
7 // deal in the Software without restriction, including without limitation the
8 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 // sell copies of the Software, and to permit persons to whom the Software is
10 // furnished to do so, subject to the following conditions:
11 //
12 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
13 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
14 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
15 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
16 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
18 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
19 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20 //
21 //==============================================================================
22 chip 1.1 //
23 // Author: Chip Vincent (cvincent@us.ibm.com)
24 //
25 // Modified By:
26 //
27 //%/////////////////////////////////////////////////////////////////////////////
28
29 #ifndef Pegasus_CIMIndicationProvider_h
30 #define Pegasus_CIMIndicationProvider_h
31
32 #include <Pegasus/Common/Config.h>
33 #include <Pegasus/Common/CIMIndication.h>
34 #include <Pegasus/Provider/CIMBaseProvider.h>
35
36 #include <Pegasus/Common/Array.h>
37 #include <Pegasus/Common/String.h>
38 #include <Pegasus/Common/CIMReference.h>
39 #include <Pegasus/Common/CIMDateTime.h>
40
41 PEGASUS_NAMESPACE_BEGIN
42
43 chip 1.1 /**
|
44 chip 1.3 This class defines the set of methods implemented by an indication provider. A providers that derives
45 from this class must implement all methods. The minimal method implementation simply throw the
46 NotSupported exception.
47
48 In general, the CIMOM classifies the provider as asynchronous or synchronous depending on the methods
49 implemented by the provider. An asynchronous indication provider supports provideIndication,
50 updateIndication, and cancelIndication. A synchronous provider supports checkIndication. A provider
51 can support both interfaces.
52
53 The CIMOM first attempts to call provideIndication, given at least once subscription exists.
54 If the provider does not support the method, the CIMOM assumes the provider generates indications
55 synchronously using checkIndication. If the provider does not support any of the methods of this
56 interface, is not considered an indication provider and an error is generated.
|
57 chip 1.1 */
|
58 chip 1.3 class PEGASUS_PROVIDER_LINKAGE CIMIndicationProvider : public virtual CIMBaseProvider
|
59 chip 1.1 {
60 public:
|
61 chip 1.3 CIMIndicationProvider(void);
62 virtual ~CIMIndicationProvider(void);
|
63 chip 1.1
|
64 chip 1.3 /**
65 Instructs the provider to begin generating indications of the type specified in
66 the classReference parameter.
67
68 This method is invoked when the CIMOM has at least one active subscription that
69 links the indication type with a handler. Once this method has been invoked, changes
70 to the active subscriptions are communicated via the updateIndication method. The
71 cancelIndication method is invoked when all active subscriptions have been removed.
72
73 For example, assume that two subscriptions exist that point to the following filters.
|
74 chip 1.1
75 <pre>
|
76 chip 1.3 <code>"SELECT Property1 FROM Sample_Indication WHERE Property1="foo" WITHIN 30000"</code>
77 <code>"SELECT Property2 FROM Sample_Indication WHERE Property1="bar" WITHIN 60000"</code>
|
78 chip 1.1 </pre>
79
|
80 chip 1.3 The contents of the paramters (in string form) to this method might look like the following.
|
81 chip 1.1
82 <pre>
|
83 chip 1.3 <code>classReference = "localhost/root/cimv2:Sample_Indication"</code>
84 <code>minimumInterval = "00000000003000.000000:000" (30 minutes)</code>
85 <code>maximumInterval = "00000000006000.000000:000" (60 minutes)</code>
86 <code>propertyList = "Property1", "Property2"</code>
|
87 chip 1.1 </pre>
88
|
89 chip 1.3 NOTE: The WHERE clause is not evaluated by the provider. Providers generate indications according
90 to predefined events and are not specified by indication filters. The existence of a filter simply
91 notifies a provider that some client is interested in indications of a specified type. The filters
92 specify the criteria for indication delivery, not creation.
93
94 Assuming the above parameters, the provider should attach to some resource and begin monitoring
95 every 30 seconds (optimally). When some predefined event occurs (a circumstance that merits an
96 indication), the provider should create and indication containing the properties listed in the
97 propertyList parameter. The provider then delivers the indication to the handler associated with the
98 indication type and continues monitoring. A call to updateIndication means that the indication
99 generation information (minimumInterval, maximumInterval, and propertyList) has changed, and a call
100 to cancelIndication notifies the provider to discontinue monitoring (no subscriptions exist).
101
102 NOTE: Under normal circumstances the provider should not call handler.complete() in this method;
103 it should be called in cancelIndication. Calling this method implies no more results are available
104 and will effectively disable result forwarding for the handler.
|
105 chip 1.1
|
106 chip 1.3 @param contex contains security and locale information relevant for the lifetime
107 of this operation.
|
108 chip 1.1
|
109 chip 1.3 @param classReference provides a fully qualified reference of the indication
110 class of interest.
|
111 chip 1.1
|
112 chip 1.3 @param minimumInterval specifies the minimum requested indication delivery frequency. This is an
113 optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.
|
114 chip 1.1
|
115 chip 1.3 @param maximumInterval specifies the maximum requested indication delivery frequency. This is an
116 optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.
|
117 chip 1.1
|
118 chip 1.3 @param propertyList specifies the properties of interest within the class
119 identified by the classReference parameter.
120
121 @param handler asynchronusly processes the results of this operation.
|
122 chip 1.1
123 @exception NotImplemented
124 @exception InvalidArgument
|
125 chip 1.3 */
126 virtual void provideIndication(
127 const OperationContext & context,
128 const CIMReference & classReference,
129 const CIMDateTime & minimumInterval,
130 const CIMDateTime & maximumInterval,
131 const Array<String> & propertyList,
132 ResponseHandler<CIMIndication> & handler) = 0;
133
134 /**
135 Instructs the provider update the information regarding the indication of the type specified
136 in the classReference parameter.
137
138 Once the provideIndication method has been called, the CIMOM communicated significant changes
139 to the indication generatation information (minimumInterval, maximumInterval, and propertyList)
|
140 chip 1.1 via this method.
141
|
142 chip 1.3 Assuming provideIndications was called with the parameters in the sample above, and a new
143 subscription is created for the following filter.
|
144 chip 1.1
145 <pre>
|
146 chip 1.3 <code>"SELECT Property1, Property3 FROM Sample_Indication WHERE Property1="bar" WITHIN 60000"</code>
|
147 chip 1.1 </pre>
148
|
149 chip 1.3 The contents of the paramters (in string form) to this method might look like the following.
|
150 chip 1.1
151 <pre>
|
152 chip 1.3 <code>classReference = "localhost/root/cimv2:Sample_Indication"</code>
153 <code>minimumInterval = "00000000003000.000000:000" (30 minutes)</code>
154 <code>maximumInterval = "00000000006000.000000:000" (60 minutes)</code>
155 <code>propertyList = "Property1", "Property2", "Property3"</code>
|
156 chip 1.1 </pre>
157
|
158 chip 1.3 NOTE: The WHERE clause is not evaluated by the provider. Providers generate indications according
159 to predefined events and are not specified by indication filters. The existence of a filter simply
160 notifies a provider that some client is interested in indications of a specified type. The filters
161 specify the criteria for indication delivery, not creation.
162
163 Assuming the above parameters, the provider should adjust add Property3 to any indications
164 generated from this point forward.
165
166 New subscriptions associated to existing filters do not result in calls to the provider.
167
168 NOTE: Under normal circumstances the provider should not call handler.complete() in this method;
169 it should be called in cancelIndication. Calling this method implies no more results are available
170 and will effectively disable result forwarding for the handler.
|
171 chip 1.1
172 @param context contains security and locale information
173 relevant for the lifetime of this operation.
174
|
175 chip 1.3 @param classReference provides a fully qualified reference of the indication
176 class of interest.
177
178 @param minimumInterval specifies the minimum requested indication delivery frequency. This is an
179 optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.
|
180 chip 1.1
|
181 chip 1.3 @param maximumInterval specifies the maximum requested indication delivery frequency. This is an
182 optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.
|
183 chip 1.1
|
184 chip 1.3 @param propertyList specifies the properties of interest within the class
185 identified by the classReference parameter.
|
186 chip 1.1
|
187 chip 1.3 @param handler asynchronusly processes the results of this operation.
|
188 chip 1.1
189 @exception NotImplemented
190 @exception InvalidArgument
|
191 chip 1.3 */
192 virtual void updateIndication(
193 const OperationContext & context,
194 const CIMReference & classReference,
195 const CIMDateTime & minimumInterval,
196 const CIMDateTime & maximumInterval,
197 const Array<String> & propertyList,
198 ResponseHandler<CIMIndication> & handler) = 0;
199
200 /**
201 Instructs the provider to stop providing indications of the type specified in the
202 classReference parameter.
203
204 This method is called after provideIndication and implies that either no
205 subscriptions exist or that the CIMOM is shutting down. The provider should release
206 resources associated with generating indications of the type specified in
207 classReference. If a subscription is later created, provideIndications will be
208 called again.
209
210 Upon completion of this method, the provider should call handler.complete (the CIMOM
211 will call it, if necessary) at which point the handle is no longer guaranteed to be
212 chip 1.3 valid. Usage of the handle after complete is undefined.
|
213 chip 1.1
|
214 chip 1.3 @param context contains security and locale information relevant for the lifetime
215 of this operation.
|
216 chip 1.1
|
217 chip 1.3 @param classReference provides a fully qualified reference of the indication
218 class of interest.
|
219 chip 1.1
|
220 chip 1.3 @param handler asynchronusly processes the results of this operation.
|
221 chip 1.1
222 @exception NotImplemented
223 @exception InvalidArgument
|
224 chip 1.3 */
225 virtual void cancelIndication(
226 const OperationContext & context,
227 const CIMReference & classReference,
228 ResponseHandler<CIMIndication> & handler) = 0;
229
230 /**
231 Instructs the provider to check the managed resource and immediately generate indications,
232 if necessary, and complete.
233
234 This method is called periodically by the CIMOM to allow the provider to create indications
235 without actively monitoring a resource. Because the method executes on the CIMOM's thread,
236 the provider should attempt to complete the method prompty to allow the CIMOM to service
237 other providers.
|
238 chip 1.1
239 @param context contains security and locale information
240 relevant for the lifetime of this operation.
241
|
242 chip 1.3 @param classReference provides a fully qualified reference of the indication
243 class of interest.
|
244 chip 1.1
|
245 chip 1.3 @param The propertyList specifies the properties of interest within the class
246 identified by the classReference parameter.
|
247 chip 1.1
|
248 chip 1.3 @param handler asynchronusly processes the results of this operation.
|
249 chip 1.1
250 @exception NotImplemented
251 @exception InvalidArgument
|
252 chip 1.3 */
253 virtual void checkIndication(
254 const OperationContext & context,
255 const CIMReference & classReference,
256 const Array<String> & propertyList,
257 ResponseHandler<CIMIndication> & handler) = 0;
|
258 chip 1.1 };
259
260 PEGASUS_NAMESPACE_END
261
|
262 chip 1.3 #endif
|
Return to
CIMIndicationProvider.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Provider