/src/libreoffice/include/ucbhelper/interceptedinteraction.hxx

Source
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#ifndef INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
#define INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX

#include <vector>

#include <com/sun/star/task/XInteractionHandler.hpp>

#include <cppuhelper/implbase.hxx>
#include <ucbhelper/ucbhelperdllapi.h>

namespace com::sun::star::task { class XInteractionRequest; }


namespace ucbhelper{


/** @short  it wraps any other interaction handler and intercept
            its handle() requests.

    @descr  This class can be used as:
            - instance if special interactions must be suppressed
              only
            - or as base class if interactions must be modified.
 */
// extra struct to work around MSVC linking issue
struct InterceptedInteraction_Base : public ::cppu::WeakImplHelper< css::task::XInteractionHandler > {};

class UCBHELPER_DLLPUBLIC InterceptedInteraction : public InterceptedInteraction_Base
{

    // types
    public:

        struct InterceptedRequest
        {

            /** @short  marks an Handle as invalid.
             */
            static const sal_Int32 INVALID_HANDLE = -1;


            /** @short  contains the interaction request, which should be intercepted. */
            css::uno::Any Request;


            /** @short  specify the fix continuation, which must be selected, if the
                        interaction could be intercepted successfully.
              */
            css::uno::Type Continuation;


            /** @short  it's a unique identifier, which must be managed by the outside code.

                @descr  If there is a derived class, which overwrites the InterceptedInteraction::intercepted()
                        method, it will be called with a reference to an InterceptedRequest struct.
                        Then it can use the handle to react without checking the request type again.
             */
            sal_Int32 Handle;


            /** @short  default ctor.

                @descr  Such constructed object can't be used really.
                        Might it will crash if it's used!
                        Don't forget to initialize all(!) members...
             */
            InterceptedRequest()
            {
                Handle     = INVALID_HANDLE;
            }
            InterceptedRequest(css::uno::Any Request_, css::uno::Type Continuation_, sal_Int32 Handle_)
                : Request(std::move(Request_)), Continuation(std::move(Continuation_)), Handle(Handle_)
            {
            }

        };


        /** @short  represent the different states, which can occur
                    as result of an interception.

            @see    impl_interceptRequest()
         */
        enum EInterceptionState
        {
            /** none of the specified interceptions match the incoming request */
            E_NOT_INTERCEPTED,
            /** the request could be intercepted - but the specified continuation could not be located.
                That's normally an error of the programmer. May be the interaction request does not use
                the right set of continuations ... or the interception list contains the wrong continuation. */
            E_NO_CONTINUATION_FOUND,
            /** the request could be intercepted and the specified continuation could be selected successfully. */
            E_INTERCEPTED
        };


    // member
    protected:


        /** @short  reference to the intercepted interaction handler.

            @descr  NULL is allowed for this member!
                    All interaction will be aborted then ...
                    expecting th handle() was overwritten by
                    a derived class.
         */
        css::uno::Reference< css::task::XInteractionHandler > m_xInterceptedHandler;


        /** @short  these list contains the requests, which should be intercepted.
         */
        ::std::vector< InterceptedRequest > m_lInterceptions;


    // native interface
    public:


        /** @short  initialize a new instance with default values.
         */
        InterceptedInteraction();


        /** @short  initialize a new instance with the interaction handler,
                    which should be intercepted.

            @attention  If such interaction handler isn't set here,
                        all incoming requests will be aborted ...
                        if the right continuation is available!

            @param  xInterceptedHandler
                    the outside interaction handler, which should
                    be intercepted here.
         */
        void setInterceptedHandler(const css::uno::Reference< css::task::XInteractionHandler >& xInterceptedHandler);


        /** @short  set a new list of intercepted interactions.

            @attention  If the interface method handle() will be overwritten by
                        a derived class, the functionality behind these static list
                        can't be used.

            @param  lInterceptions
                    the list of intercepted requests.
         */
        void setInterceptions(::std::vector< InterceptedRequest >&& lInterceptions);


        /** @short  extract a requested continuation from the list of available ones.

            @param  lContinuations
                    the list of available continuations.

            @param  aType
                    is used to locate the right continuation,
                    by checking its interface type.

            @return A valid reference to the continuation, if it could be located...
                    or an empty reference otherwise.
         */
        static css::uno::Reference< css::task::XInteractionContinuation > extractContinuation(
                    const css::uno::Sequence< css::uno::Reference< css::task::XInteractionContinuation > >& lContinuations,
                    const css::uno::Type&                                                                                             aType         );


    // usable for derived classes
    protected:


        /** @short  can be overwritten by a derived class to handle interceptions
                    outside.

            @descr  This base implementation checks, if the request could be intercepted
                    successfully. Then this method intercepted() is called.
                    The default implementation returns "NOT_INTERCEPTED" every time.
                    So the method impl_interceptRequest() uses the right continuation automatically.

                    If this method was overwritten and something different "NO_INTERCEPTED"
                    is returned, the method impl_interceptRequest() will return immediately with
                    the result, which is returned by this intercepted() method.
                    Then the continuations must be selected inside the intercepted() call!

            @param  rRequest
                    it points to the intercepted request (means the item of the
                    set interception list). e.g. its "Handle" member can be used
                    to identify it and react very easy, without the need to check the
                    type of the exception ...

            @param  xOrgRequest
                    points to the original interaction, which was intercepted.
                    It provides access to the exception and the list of possible
                    continuations.

            @return The result of this operation.
                    Note: If E_NOT_INTERCEPTED is returned the default handling of the base class
                    will be used automatically for this request!
         */
        virtual EInterceptionState intercepted(const InterceptedRequest&                                                             rRequest   ,
                                               const css::uno::Reference< css::task::XInteractionRequest >& xOrgRequest);


    // uno interface
    public:


        /** @short  implements the default handling of this class...
                    or can be overwritten by any derived class.

            @descr  If no further class is derived from this one
                    -> the default implementation is used. Then the
                    internal list of requests is used to handle different
                    interactions automatically.
                    (see impl_interceptRequest())

                    If this method was overwritten by a derived implementation
                    -> the new implementation has to do everything by itself.
                    Of course it can access all members/helpers and work with it.
                    But the default implementation is not used automatically then.

            @param  xRequest
                    the interaction request, which should be intercepted.
         */
        virtual void SAL_CALL handle(const css::uno::Reference< css::task::XInteractionRequest >& xRequest) override;


    // helper
    private:


        /** @short  implements the default handling:
                    - intercept or forward to internal handler.
         */
        UCBHELPER_DLLPRIVATE void impl_handleDefault(const css::uno::Reference< css::task::XInteractionRequest >& xRequest);


        /** @short  implements the interception of requests.

            @descr  The incoming request will be analyzed, if it match
                    any request of the m_lIntercepions list.
                    If an interception could be found, its continuation will be
                    searched and selected.

                    The method return the state of that operation.
                    But it doesn't call the intercepted and here set
                    interaction handler. That has to be done in the outside method.

            @param  xRequest
                    the interaction request, which should be intercepted.

            @return A identifier, which indicates if the request was intercepted,
                    the continuation was found and selected... or not.
         */
        UCBHELPER_DLLPRIVATE EInterceptionState impl_interceptRequest(const css::uno::Reference< css::task::XInteractionRequest >& xRequest);
};

} // namespace ucbhelper

#endif // INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Coverage Report

Created: 2025-11-16 09:57

Line	Count	Source
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 <cppuhelper/implbase.hxx>
28		#include <ucbhelper/ucbhelperdllapi.h>
29
30		namespace com::sun::star::task { class XInteractionRequest; }
31
32
33		namespace ucbhelper{
34
35
36		/** @short it wraps any other interaction handler and intercept
37		its handle() requests.
38
39		@descr This class can be used as:
40		- instance if special interactions must be suppressed
41		only
42		- or as base class if interactions must be modified.
43		*/
44		// extra struct to work around MSVC linking issue
45		struct InterceptedInteraction_Base : public ::cppu::WeakImplHelper< css::task::XInteractionHandler > {};
46
47		class UCBHELPER_DLLPUBLIC InterceptedInteraction : public InterceptedInteraction_Base
48		{
49
50		// types
51		public:
52
53		struct InterceptedRequest
54		{
55
56		/** @short marks an Handle as invalid.
57		*/
58		static const sal_Int32 INVALID_HANDLE = -1;
59
60
61		/** @short contains the interaction request, which should be intercepted. */
62		css::uno::Any Request;
63
64
65		/** @short specify the fix continuation, which must be selected, if the
66		interaction could be intercepted successfully.
67		*/
68		css::uno::Type Continuation;
69
70
71		/** @short it's a unique identifier, which must be managed by the outside code.
72
73		@descr If there is a derived class, which overwrites the InterceptedInteraction::intercepted()
74		method, it will be called with a reference to an InterceptedRequest struct.
75		Then it can use the handle to react without checking the request type again.
76		*/
77		sal_Int32 Handle;
78
79
80		/** @short default ctor.
81
82		@descr Such constructed object can't be used really.
83		Might it will crash if it's used!
84		Don't forget to initialize all(!) members...
85		*/
86		InterceptedRequest()
87	23.2k	{
88	23.2k	Handle = INVALID_HANDLE;
89	23.2k	}
90		InterceptedRequest(css::uno::Any Request_, css::uno::Type Continuation_, sal_Int32 Handle_)
91	950k	: Request(std::move(Request_)), Continuation(std::move(Continuation_)), Handle(Handle_)
92	950k	{
93	950k	}
94
95		};
96
97
98		/** @short represent the different states, which can occur
99		as result of an interception.
100
101		@see impl_interceptRequest()
102		*/
103		enum EInterceptionState
104		{
105		/** none of the specified interceptions match the incoming request */
106		E_NOT_INTERCEPTED,
107		/** the request could be intercepted - but the specified continuation could not be located.
108		That's normally an error of the programmer. May be the interaction request does not use
109		the right set of continuations ... or the interception list contains the wrong continuation. */
110		E_NO_CONTINUATION_FOUND,
111		/** the request could be intercepted and the specified continuation could be selected successfully. */
112		E_INTERCEPTED
113		};
114
115
116		// member
117		protected:
118
119
120		/** @short reference to the intercepted interaction handler.
121
122		@descr NULL is allowed for this member!
123		All interaction will be aborted then ...
124		expecting th handle() was overwritten by
125		a derived class.
126		*/
127		css::uno::Reference< css::task::XInteractionHandler > m_xInterceptedHandler;
128
129
130		/** @short these list contains the requests, which should be intercepted.
131		*/
132		::std::vector< InterceptedRequest > m_lInterceptions;
133
134
135		// native interface
136		public:
137
138
139		/** @short initialize a new instance with default values.
140		*/
141		InterceptedInteraction();
142
143
144		/** @short initialize a new instance with the interaction handler,
145		which should be intercepted.
146
147		@attention If such interaction handler isn't set here,
148		all incoming requests will be aborted ...
149		if the right continuation is available!
150
151		@param xInterceptedHandler
152		the outside interaction handler, which should
153		be intercepted here.
154		*/
155		void setInterceptedHandler(const css::uno::Reference< css::task::XInteractionHandler >& xInterceptedHandler);
156
157
158		/** @short set a new list of intercepted interactions.
159
160		@attention If the interface method handle() will be overwritten by
161		a derived class, the functionality behind these static list
162		can't be used.
163
164		@param lInterceptions
165		the list of intercepted requests.
166		*/
167		void setInterceptions(::std::vector< InterceptedRequest >&& lInterceptions);
168
169
170		/** @short extract a requested continuation from the list of available ones.
171
172		@param lContinuations
173		the list of available continuations.
174
175		@param aType
176		is used to locate the right continuation,
177		by checking its interface type.
178
179		@return A valid reference to the continuation, if it could be located...
180		or an empty reference otherwise.
181		*/
182		static css::uno::Reference< css::task::XInteractionContinuation > extractContinuation(
183		const css::uno::Sequence< css::uno::Reference< css::task::XInteractionContinuation > >& lContinuations,
184		const css::uno::Type& aType );
185
186
187		// usable for derived classes
188		protected:
189
190
191		/** @short can be overwritten by a derived class to handle interceptions
192		outside.
193
194		@descr This base implementation checks, if the request could be intercepted
195		successfully. Then this method intercepted() is called.
196		The default implementation returns "NOT_INTERCEPTED" every time.
197		So the method impl_interceptRequest() uses the right continuation automatically.
198
199		If this method was overwritten and something different "NO_INTERCEPTED"
200		is returned, the method impl_interceptRequest() will return immediately with
201		the result, which is returned by this intercepted() method.
202		Then the continuations must be selected inside the intercepted() call!
203
204		@param rRequest
205		it points to the intercepted request (means the item of the
206		set interception list). e.g. its "Handle" member can be used
207		to identify it and react very easy, without the need to check the
208		type of the exception ...
209
210		@param xOrgRequest
211		points to the original interaction, which was intercepted.
212		It provides access to the exception and the list of possible
213		continuations.
214
215		@return The result of this operation.
216		Note: If E_NOT_INTERCEPTED is returned the default handling of the base class
217		will be used automatically for this request!
218		*/
219		virtual EInterceptionState intercepted(const InterceptedRequest& rRequest ,
220		const css::uno::Reference< css::task::XInteractionRequest >& xOrgRequest);
221
222
223		// uno interface
224		public:
225
226
227		/** @short implements the default handling of this class...
228		or can be overwritten by any derived class.
229
230		@descr If no further class is derived from this one
231		-> the default implementation is used. Then the
232		internal list of requests is used to handle different
233		interactions automatically.
234		(see impl_interceptRequest())
235
236		If this method was overwritten by a derived implementation
237		-> the new implementation has to do everything by itself.
238		Of course it can access all members/helpers and work with it.
239		But the default implementation is not used automatically then.
240
241		@param xRequest
242		the interaction request, which should be intercepted.
243		*/
244		virtual void SAL_CALL handle(const css::uno::Reference< css::task::XInteractionRequest >& xRequest) override;
245
246
247		// helper
248		private:
249
250
251		/** @short implements the default handling:
252		- intercept or forward to internal handler.
253		*/
254		UCBHELPER_DLLPRIVATE void impl_handleDefault(const css::uno::Reference< css::task::XInteractionRequest >& xRequest);
255
256
257		/** @short implements the interception of requests.
258
259		@descr The incoming request will be analyzed, if it match
260		any request of the m_lIntercepions list.
261		If an interception could be found, its continuation will be
262		searched and selected.
263
264		The method return the state of that operation.
265		But it doesn't call the intercepted and here set
266		interaction handler. That has to be done in the outside method.
267
268		@param xRequest
269		the interaction request, which should be intercepted.
270
271		@return A identifier, which indicates if the request was intercepted,
272		the continuation was found and selected... or not.
273		*/
274		UCBHELPER_DLLPRIVATE EInterceptionState impl_interceptRequest(const css::uno::Reference< css::task::XInteractionRequest >& xRequest);
275		};
276
277		} // namespace ucbhelper
278
279		#endif // INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
280
281		/* vim:set shiftwidth=4 softtabstop=4 expandtab: */