1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef INCLUDED_UCBHELPER_HANDLEINTERACTIONREQUEST_HXX
25 #define INCLUDED_UCBHELPER_HANDLEINTERACTIONREQUEST_HXX
26 
27 #include "com/sun/star/uno/Exception.hpp"
28 #include "com/sun/star/uno/Reference.hxx"
29 #include "rtl/ref.hxx"
30 #include "sal/types.h"
31 
32 #ifndef INCLUDED_UTILITY
33 #include <utility>
34 #define INCLUDED_UTILITY
35 #endif
36 
37 namespace com { namespace sun { namespace star { namespace ucb {
38     class XCommandEnvironment;
39 } } } }
40 namespace ucbhelper {
41     class InteractionSupplyAuthentication;
42     class SimpleAuthenticationRequest;
43     class SimpleInteractionRequest;
44     class SimpleCertificateValidationRequest;
45 }
46 
47 /** Pass a <type scope="ucbhelper">SimpleInteractionRequest</type> to an
48     <type scope="com::sun::star::task">XInteractionHandler</type>, and handle
49     (by throwing the request as an exception) those cases where an interaction
50     handler is either not available or does not handle the request.
51 
52     @param rRequest
53     a <type scope="ucbhelper">SimpleInteractionRequest</type>.  Must not be
54     <NULL/>.
55 
56     @param rEnvironment
57     At the moment, only the
58     <type scope="com::sun::star::task">XInteractionHandler</type> part is
59     used.  May be <NULL/>.
60 
61     @param bThrowOnAbort
62     determines what is done if the interaction handler selects a
63     <const scope="ucbhelper">CONTINUATION_ABORT</const> continuation:  If
64     <TRUE/>, an appropriate
65     <type scope="com::sun::star::ucb">CommandFailedException</type> is thrown.
66     If <FALSE/>, <const scope="ucbhelper">CONTINUATION_ABORT</const> is passed
67     to the caller of this function.
68 
69     @returns
70     the constant (defined in ucbhelper/simpelinteractionrequest.hxx) that
71     corresponds to the continuation selected by the interaction handler.
72     The constant <const scope="ucbhelper">CONTINUATION_UNKNOWN</const> will
73     never be returned.
74 
75     @throws
76     <ul>
77     <li>the exception specified by the request, if an interaction handler is
78     either not available or does not handle the request;</li>
79     <li>a <type scope="com::sun::star::ucb">CommandFailedException</type> if
80     the interaction handler selects a
81     <const scope="ucbhelper">CONTINUATION_ABORT</const> continuation and
82     <code>bThrowOnAbort</code> is <TRUE/>;</li>
83     <li>a <type scope="com::sun::star::uno">RuntimeException</type> if such an
84     exception is thrown by code called from within this function.</li>
85     </ul>
86  */
87 namespace ucbhelper {
88 
89 sal_Int32
90 handleInteractionRequest(
91     rtl::Reference< ucbhelper::SimpleInteractionRequest > const & rRequest,
92     com::sun::star::uno::Reference<
93             com::sun::star::ucb::XCommandEnvironment > const &
94         rEnvironment,
95     bool bThrowOnAbort = true)
96     SAL_THROW((com::sun::star::uno::Exception));
97 
98 }
99 
100 /** Pass a <type scope="ucbhelper">SimpleAuthenticationRequest</type> to an
101     <type scope="com::sun::star::task">XInteractionHandler</type>, and handle
102     (by throwing the request as an exception) those cases where an interaction
103     handler is either not available or does not handle the request.
104 
105     @param rRequest
106     a <type scope="ucbhelper">SimpleAuthenticationRequest</type>.  Must not be
107     <NULL/>.
108 
109     @param rEnvironment
110     At the moment, only the
111     <type scope="com::sun::star::task">XInteractionHandler</type> part is
112     used.  May be <NULL/>.
113 
114     @param bThrowOnAbort
115     determines what is done if the interaction handler selects a
116     <const scope="ucbhelper">CONTINUATION_ABORT</const> continuation:  If
117     <TRUE/>, an appropriate
118     <type scope="com::sun::star::ucb">CommandFailedException</type> is thrown.
119     If <FALSE/>, <const scope="ucbhelper">CONTINUATION_ABORT</const> is passed
120     to the caller of this function.
121 
122     @returns
123     either a pair consisting of one of the constants
124     <const scope="ucbhelper">CONTINUATION_ABORT</const> or
125     <const scope="ucbhelper">CONTINUATION_RETRY</const> (defined in
126     ucbhelper/simpelinteractionrequest.hxx) and an empty reference, or a pair
127     consisting of the constant
128     <const scope="ucbhelper">CONTINUATION_UNKNOWN</const> and a reference to
129     an <type scope="ucbhelper">InteractionSupplyAuthentication</type> that
130     contains the supplied data.
131 
132     @throws
133     <ul>
134     <li>the exception specified by the request, if an interaction handler is
135     either not available or does not handle the request;</li>
136     <li>a <type scope="com::sun::star::ucb">CommandFailedException</type> if
137     the interaction handler selects a
138     <const scope="ucbhelper">CONTINUATION_ABORT</const> continuation and
139     <code>bThrowOnAbort</code> is <TRUE/>;</li>
140     <li>a <type scope="com::sun::star::uno">RuntimeException</type> if such an
141     exception is thrown by code called from within this function.</li>
142     </ul>
143  */
144 namespace ucbhelper {
145 
146 std::pair< sal_Int32,
147            rtl::Reference< ucbhelper::InteractionSupplyAuthentication > >
148 handleInteractionRequest(
149     rtl::Reference< ucbhelper::SimpleAuthenticationRequest > const & rRequest,
150     com::sun::star::uno::Reference<
151             com::sun::star::ucb::XCommandEnvironment > const &
152         rEnvironment,
153     bool bThrowOnAbort = true)
154     SAL_THROW((com::sun::star::uno::Exception));
155 
156 }
157 
158 /** Pass a <type scope="ucbhelper">SimpleCertificateValidationRequest</type> to an
159     <type scope="com::sun::star::task">XInteractionHandler</type>, and handle
160     (by throwing the request as an exception) those cases where an interaction
161     handler is either not available or does not handle the request.
162 
163     @param rRequest
164     a <type scope="ucbhelper">SimpleCertificateValidationRequest</type>.  Must not be
165     <NULL/>.
166 
167     @param rEnvironment
168     At the moment, only the
169     <type scope="com::sun::star::task">XInteractionHandler</type> part is
170     used.  May be <NULL/>.
171 
172     @param bThrowOnAbort
173     determines what is done if the interaction handler selects a
174     <const scope="ucbhelper">CONTINUATION_ABORT</const> continuation:  If
175     <TRUE/>, an appropriate
176     <type scope="com::sun::star::ucb">CommandFailedException</type> is thrown.
177     If <FALSE/>, <const scope="ucbhelper">CONTINUATION_ABORT</const> is passed
178     to the caller of this function.
179 
180    @returns
181     the constant (defined in ucbhelper/simpelinteractionrequest.hxx) that
182     corresponds to the continuation selected by the interaction handler.
183     The constant <const scope="ucbhelper">CONTINUATION_UNKNOWN</const> will
184     never be returned.
185 
186     @throws
187     <ul>
188     <li>the exception specified by the request, if an interaction handler is
189     either not available or does not handle the request;</li>
190     <li>a <type scope="com::sun::star::ucb">CommandFailedException</type> if
191     the interaction handler selects a
192     <const scope="ucbhelper">CONTINUATION_ABORT</const> continuation and
193     <code>bThrowOnAbort</code> is <TRUE/>;</li>
194     <li>a <type scope="com::sun::star::uno">RuntimeException</type> if such an
195     exception is thrown by code called from within this function.</li>
196     </ul>
197  */
198 namespace ucbhelper {
199 
200 sal_Int32
201 handleInteractionRequest(
202     rtl::Reference< ucbhelper::SimpleCertificateValidationRequest > const & rRequest,
203     com::sun::star::uno::Reference<
204             com::sun::star::ucb::XCommandEnvironment > const &
205         rEnvironment,
206     bool bThrowOnAbort = true)
207     SAL_THROW((com::sun::star::uno::Exception));
208 
209 }
210 #endif // INCLUDED_UCBHELPER_HANDLEINTERACTIONREQUEST_HXX
211