Line data Source code
1 : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : /*
3 : * This file is part of the LibreOffice project.
4 : *
5 : * This Source Code Form is subject to the terms of the Mozilla Public
6 : * License, v. 2.0. If a copy of the MPL was not distributed with this
7 : * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 : *
9 : * This file incorporates work covered by the following license notice:
10 : *
11 : * Licensed to the Apache Software Foundation (ASF) under one or more
12 : * contributor license agreements. See the NOTICE file distributed
13 : * with this work for additional information regarding copyright
14 : * ownership. The ASF licenses this file to you under the Apache
15 : * License, Version 2.0 (the "License"); you may not use this file
16 : * except in compliance with the License. You may obtain a copy of
17 : * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 : */
19 :
20 : #ifndef INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
21 : #define INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
22 :
23 : #include <vector>
24 :
25 : #include <com/sun/star/task/XInteractionHandler.hpp>
26 :
27 : #include <com/sun/star/task/XInteractionRequest.hpp>
28 : #include <cppuhelper/implbase1.hxx>
29 : #include <ucbhelper/ucbhelperdllapi.h>
30 :
31 :
32 : namespace ucbhelper{
33 :
34 :
35 : /** @short it wraps any other interaction handler and intercept
36 : its handle() requests.
37 :
38 : @descr This class can be used as:
39 : - instance if special interactions must be suppressed
40 : only
41 : - or as base class if interactions must be modified.
42 : */
43 6990 : class UCBHELPER_DLLPUBLIC InterceptedInteraction : public ::cppu::WeakImplHelper1< ::com::sun::star::task::XInteractionHandler >
44 : {
45 :
46 : // types
47 : public:
48 :
49 76890 : struct InterceptedRequest
50 : {
51 :
52 : /** @short marks an Handle as invalid.
53 : */
54 : static const sal_Int32 INVALID_HANDLE = -1;
55 :
56 :
57 : /** @short contains the interaction request, which should be intercepted. */
58 : ::com::sun::star::uno::Any Request;
59 :
60 :
61 : /** @short specify the fix continuation, which must be selected, if the
62 : interaction could be intercepted successfully.
63 : */
64 : ::com::sun::star::uno::Type Continuation;
65 :
66 :
67 : /** @short specify, if both interactions must have the same type
68 : or can be derived from.
69 :
70 : @descr Interaction base on exceptions - and exceptions are real types.
71 : So they can be checked in its type. These parameter "MatchExact"
72 : influence the type-check in the following way:
73 : TRUE => the exception will be intercepted only
74 : if it supports exactly the same type ...
75 : or
76 : FALSE => derived exceptions will be intercepted too.
77 :
78 : @attention This parameter does not influence the check of the continuation
79 : type! The continuation must be matched exactly every time ...
80 : */
81 : bool MatchExact;
82 :
83 :
84 : /** @short its an unique identifier, which must be managed by the outside code.
85 :
86 : @descr If there is a derived class, which overwrites the InterceptedInteraction::intercepted()
87 : method, it will be called with a reference to an InterceptedRequest struct.
88 : Then it can use the handle to react without checking the request type again.
89 : */
90 : sal_Int32 Handle;
91 :
92 :
93 : /** @short default ctor.
94 :
95 : @descr Such constructed object can't be used really.
96 : Might it will crash if its used!
97 : Dont forget to initialize all(!) members ...
98 : */
99 6990 : InterceptedRequest()
100 6990 : {
101 6990 : MatchExact = false;
102 6990 : Handle = INVALID_HANDLE;
103 6990 : }
104 :
105 :
106 : /** @short initialize this instance.
107 :
108 : @param nHandle
109 : used to identify every intercepted request
110 :
111 : @param aRequest
112 : must contain an exception object, which can be checked
113 : in its uno-type against the later handled interaction.
114 :
115 : @param aContinuation
116 : must contain a continuation object, which is used
117 : in its uno-type to locate the same continuation
118 : inside the list of possible ones.
119 :
120 : @param bMatchExact
121 : influence the type check of the interception request.
122 : Its not used to check the continuation!
123 : */
124 : InterceptedRequest( sal_Int32 nHandle ,
125 : const ::com::sun::star::uno::Any& aRequest ,
126 : const ::com::sun::star::uno::Type& aContinuation,
127 : bool bMatchExact )
128 : {
129 : Handle = nHandle;
130 : Request = aRequest;
131 : Continuation = aContinuation;
132 : MatchExact = bMatchExact;
133 : }
134 : };
135 :
136 :
137 : /** @short represent the different states, which can occur
138 : as result of an interception.
139 :
140 : @see impl_interceptRequest()
141 : */
142 : enum EInterceptionState
143 : {
144 : /** none of the specified interceptions match the incoming request */
145 : E_NOT_INTERCEPTED,
146 : /** the request could be intercepted - but the specified continuation could not be located.
147 : Thats normally an error of the programmer. May be the interaction request does not use
148 : the right set of continuations ... or the interception list contains the wrong continuation. */
149 : E_NO_CONTINUATION_FOUND,
150 : /** the request could be intercepted and the specified continuation could be selected successfully. */
151 : E_INTERCEPTED
152 : };
153 :
154 :
155 : // member
156 : protected:
157 :
158 :
159 : /** @short reference to the intercepted interaction handler.
160 :
161 : @descr NULL is allowed for this member!
162 : All interaction will be aborted then ...
163 : expecting th handle() was overwritten by
164 : a derived class.
165 : */
166 : ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionHandler > m_xInterceptedHandler;
167 :
168 :
169 : /** @short these list contains the requests, which should be intercepted.
170 : */
171 : ::std::vector< InterceptedRequest > m_lInterceptions;
172 :
173 :
174 : // native interface
175 : public:
176 :
177 :
178 : /** @short initialize a new instance with default values.
179 : */
180 : InterceptedInteraction();
181 :
182 :
183 : /** @short initialize a new instance with real values.
184 :
185 : @param xInterceptedHandler
186 : the outside interaction handler, which should
187 : be intercepted here.
188 :
189 : @param lInterceptions
190 : the list of intercepted requests.
191 : */
192 : InterceptedInteraction(const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionHandler >& xInterceptedHandler,
193 : const ::std::vector< InterceptedRequest >& lInterceptions );
194 :
195 :
196 : /** @short initialize a new instance with the interaction handler,
197 : which should be intercepted.
198 :
199 : @attention If such interaction handler isn't set here,
200 : all incoming requests will be aborted ...
201 : if the right continuation is available!
202 :
203 : @param xInterceptedHandler
204 : the outside interaction handler, which should
205 : be intercepted here.
206 : */
207 : void setInterceptedHandler(const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionHandler >& xInterceptedHandler);
208 :
209 :
210 : /** @short set a new list of intercepted interactions.
211 :
212 : @attention If the interface method handle() will be overwritten by
213 : a derived class, the functionality behind these static list
214 : can't be used.
215 :
216 : @param lInterceptions
217 : the list of intercepted requests.
218 : */
219 : void setInterceptions(const ::std::vector< InterceptedRequest >& lInterceptions);
220 :
221 :
222 : /** @short extract a requested continuation from te list of available ones.
223 :
224 : @param lContinuations
225 : the list of available continuations.
226 :
227 : @param aType
228 : is used to locate the right continuation,
229 : by checking its interface type.
230 :
231 : @return A valid reference to the continuation, if it could be located ...
232 : or an empty reference otherwise.
233 : */
234 : static ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionContinuation > extractContinuation(
235 : const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionContinuation > >& lContinuations,
236 : const ::com::sun::star::uno::Type& aType );
237 :
238 :
239 : // useable for derived classes
240 : protected:
241 :
242 :
243 : /** @short can be overwritten by a derived class to handle interceptions
244 : outside.
245 :
246 : @descr This base implementation checks, if the request could be intercepted
247 : successfully. Then this method intercepted() is called.
248 : The default implementation returns "NOT_INTERCEPTED" every time.
249 : So the method impl_interceptRequest() uses the right continuation automatically.
250 :
251 : If this method was overwritten and something different "NO_INTERCEPTED"
252 : is returned, the method impl_interceptRequest() will return immediately with
253 : the result, which is returned by this intercepted() method.
254 : Then the continuations must be selected inside the intercepted() call!
255 :
256 : @param rRequest
257 : it points to the intercepted request (means the item of the
258 : set interception list). e.g. its "Handle" member can be used
259 : to identify it and react very easy, without the need to check the
260 : type of the exception ...
261 :
262 : @param xOrgRequest
263 : points to the original interaction, which was intercepted.
264 : It provides access to the exception and the list of possible
265 : continuations.
266 :
267 : @return The result of this operation.
268 : Note: If E_NOT_INTERCEPTED is returned the default handling of the base class
269 : will be used automatically for this request!
270 : */
271 : virtual EInterceptionState intercepted(const InterceptedRequest& rRequest ,
272 : const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionRequest >& xOrgRequest);
273 :
274 :
275 : // uno interface
276 : public:
277 :
278 :
279 : /** @short implements the default handling of this class...
280 : or can be overwritten by any derived class.
281 :
282 : @descr If no further class is derived from this one
283 : -> the default implementation is used. Then the
284 : internal list of requests is used to handle different
285 : interactions automatically.
286 : (see impl_interceptRequest())
287 :
288 : If this method was overwritten by a derived implementation
289 : -> the new implementation has to do everything by itself.
290 : Of course it can access all members/helpers and work with it.
291 : But the default implementation is not used automatically then.
292 :
293 : @param xRequest
294 : the interaction request, which should be intercepted.
295 : */
296 : virtual void SAL_CALL handle(const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionRequest >& xRequest)
297 : throw(::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
298 :
299 :
300 : // helper
301 : private:
302 :
303 :
304 : /** @short implements the default handling:
305 : - intercept or forward to internal handler.
306 : */
307 : UCBHELPER_DLLPRIVATE void impl_handleDefault(const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionRequest >& xRequest);
308 :
309 :
310 : /** @short implements the interception of requests.
311 :
312 : @descr The incoming request will be analyzed, if it match
313 : any request of the m_lIntercepions list.
314 : If an interception could be found, its continuation will be
315 : searched and selected.
316 :
317 : The method return the state of that operation.
318 : But it doesn't call the intercepted and here set
319 : interaction handler. That has to be done in the outside method.
320 :
321 : @param xRequest
322 : the interaction request, which should be intercepted.
323 :
324 : @return A identifier, which inidicates if the request was intercepted,
325 : the continuation was found and selected ... or not.
326 : */
327 : UCBHELPER_DLLPRIVATE EInterceptionState impl_interceptRequest(const ::com::sun::star::uno::Reference< ::com::sun::star::task::XInteractionRequest >& xRequest);
328 : };
329 :
330 : } // namespace ucbhelper
331 :
332 : #endif // INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
333 :
334 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
