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 __com_sun_star_mail_XMailService_idl__
25#define __com_sun_star_mail_XMailService_idl__
26
27#ifndef __com_sun_star_uno_XInterface_idl__
28#include <com/sun/star/uno/XInterface.idl>
29#endif
30
31#ifndef __com_sun_star_mail_XAuthenticator_idl__
32#include <com/sun/star/mail/XAuthenticator.idl>
33#endif
34
35#ifndef __com_sun_star_auth_AuthenticationFailedException_idl__
36#include <com/sun/star/auth/AuthenticationFailedException.idl>
37#endif
38
39#ifndef __com_sun_star_io_AlreadyConnectedException_idl__
40#include <com/sun/star/io/AlreadyConnectedException.idl>
41#endif
42
43#ifndef __com_sun_star_io_NotConnectedException_idl__
44#include <com/sun/star/io/NotConnectedException.idl>
45#endif
46
47#ifndef __com_sun_star_io_UnknownHostException_idl__
48#include <com/sun/star/io/UnknownHostException.idl>
49#endif
50
51#ifndef __com_sun_star_io_NoRouteToHostException_idl__
52#include <com/sun/star/io/NoRouteToHostException.idl>
53#endif
54
55#ifndef __com_sun_star_io_ConnectException_idl__
56#include <com/sun/star/io/ConnectException.idl>
57#endif
58
59#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
60#include <com/sun/star/lang/IllegalArgumentException.idl>
61#endif
62
63#ifndef __com_sun_star_mail_XConnectionListener_idl__
64#include <com/sun/star/mail/XConnectionListener.idl>
65#endif
66
67#ifndef __com_sun_star_mail_MailException_idl__
68#include <com/sun/star/mail/MailException.idl>
69#endif
70
71#ifndef __com_sun_star_uno_XCurrentContext_idl__
72#include <com/sun/star/uno/XCurrentContext.idl>
73#endif
74
75
76module com { module sun { module star { module mail {
77
78/**
79   Represents a mail server abstraction.
80
81   @since OpenOffice 2.0
82 */
83interface XMailService: ::com::sun::star::uno::XInterface {
84
85    /**
86        Returns all connection types which are supported to
87        connect to the mail service. At least support insecure
88        connections must be supported. Currently defined
89        connection types are (the values should be handled
90        case insensitive):
91        "Insecure" - insecure connections
92        "Ssl" - Secure Socket Layer 2.0/3.0 based connection
93
94        @returns
95        a sequence of supported connection types.
96    */
97    sequence<string> getSupportedConnectionTypes();
98
99    /**
100        Register a connection listener.
101
102        @param xListener
103        [in] a listener that will be informed about connection events.
104
105        @see com::sun::star::mail::XConnectionListener
106    */
107    void addConnectionListener([in] XConnectionListener xListener);
108
109    /**
110        Unregister a connection listener.
111
112        @param xListener
113        [in] a listener that no longer need to be informed about connection events.
114
115        @see com::sun::star::mail::XConnectionListener
116    */
117    void removeConnectionListener([in] XConnectionListener xListener);
118
119    /**
120        Return the context of the current connnection. The context
121        contains information like the server name, port, connection type
122        etc.
123
124        @precond
125        <code>isConnected</code> returns true.
126
127        @returns
128        the current connection context.
129
130        @throws com::sun::star::io::NotConnectedException
131        if no connection is currently established.
132
133        @see com::sun::star::mail::connectUser
134        @see com::sun::star::io::NotConnectedException
135    */
136    com::sun::star::uno::XCurrentContext getCurrentConnectionContext()
137        raises(com::sun::star::io::NotConnectedException);
138
139    /**
140        Connect to a mail service. Only one connection to a mail service
141        can be established at a time.
142
143        @param xConnectionContext
144        [in] an interface used to query for connection related information.
145        The context must contain the following values:
146        <ul>
147            <li>
148                <b>ServerName</b> of type 'string'.
149            </li>
150            <li>
151                <b>Port</b> of type 'long'.
152            </li>
153            <li>
154                <b>ConnectionType</b> of type 'string'.
155                A list of supported connection types can be queried using
156                <member>getSupportedConnectionTypes</member>.
157            </li>
158            <li>
159                <b>Timeout</b> of type 'long' (Optional).
160                Specifies a timeout in seconds for blocking operations,
161                like the connection attempt.
162            </li>
163        </ul>
164
165        @param xAuthenticator
166        [in] an interface used to query for the necessary user information
167        needed to login to the mail server. If no authentication is required
168        the xAuthenticator must return an empty user name and an empty password.
169
170        @throws com::sun::star::lang::IllegalArgumentException
171        if the provided connection context contains invalid values or
172        misses required connection parameters.
173
174        @throws com::sun::star::io::AlreadyConnectedException
175        on a try to connect to an already connect mail server.
176
177        @throws com::sun::star::io::UnknownHostException
178        usually if the IP address of the mail server could not be
179        determined. Possible causes are a broken network connection,
180        a wrong server name, an unreachable DNS server, etc.
181
182        @throws com::sun::star::io::NoRouteToHostException
183        if an error occured to connect to the remote mail server.
184        Typically the remote mail server cannot be reach because of an
185        intervening firewall, or if an intermediate router is down,
186        the network connection is broken, etc.
187
188        @throws com::sun::star::io::ConnectException
189        if an error occured while attempting to connect to the remote
190        mail server. Typically the connection was refused remotely,
191        because the mail server is not listening on the remote address/port.
192
193        @throws com::sun::star::auth::AuthenticationException
194        if the specified user could not be logged in.
195
196        @throws com::sun::star::mail::MailException
197        for other errors during login.
198
199        @see com::sun::star::uno::XCurrentContext
200        @see com::sun::star::mail::XAuthenticator
201        @see com::sun::star::lang::IllegalArgumentException
202        @see com::sun::star::io::AlreadyConnectedException
203        @see com::sun::star::io::UnknownHostException
204        @see com::sun::star::io::NoRouteToHostException
205        @see com::sun::star::io::ConnectException
206        @see com::sun::star::auth::AuthenticationException
207        @see com::sun::star::mail::IllegalStateException
208        @see com::sun::star::mail::MailException
209    */
210    void connect([in] com::sun::star::uno::XCurrentContext xConnectionContext, [in] XAuthenticator xAuthenticator)
211        raises(com::sun::star::lang::IllegalArgumentException,
212               com::sun::star::io::AlreadyConnectedException,
213               com::sun::star::io::UnknownHostException,
214               com::sun::star::io::NoRouteToHostException,
215               com::sun::star::io::ConnectException,
216               com::sun::star::auth::AuthenticationFailedException,
217               com::sun::star::mail::MailException);
218
219    /**
220        Disconnect from a mail service.
221
222        @throws com::sun::star::mail::MailException
223        if errors occur during disconnecting.
224    */
225    void disconnect()
226        raises(com::sun::star::mail::MailException);
227
228    /**
229        Returns whether a connection to a mail service
230        currently exist or not.
231
232        @returns
233        <TRUE/> if a connection to a mail service is established.
234    */
235    boolean isConnected();
236};
237
238}; }; }; };
239
240#endif
241