1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27
28#ifndef __com_sun_star_mail_XMailService_idl__
29#define __com_sun_star_mail_XMailService_idl__
30
31#ifndef __com_sun_star_uno_XInterface_idl__
32#include <com/sun/star/uno/XInterface.idl>
33#endif
34
35#ifndef __com_sun_star_mail_XAuthenticator_idl__
36#include <com/sun/star/mail/XAuthenticator.idl>
37#endif
38
39#ifndef __com_sun_star_auth_AuthenticationFailedException_idl__
40#include <com/sun/star/auth/AuthenticationFailedException.idl>
41#endif
42
43#ifndef __com_sun_star_io_AlreadyConnectedException_idl__
44#include <com/sun/star/io/AlreadyConnectedException.idl>
45#endif
46
47#ifndef __com_sun_star_io_NotConnectedException_idl__
48#include <com/sun/star/io/NotConnectedException.idl>
49#endif
50
51#ifndef __com_sun_star_io_UnknownHostException_idl__
52#include <com/sun/star/io/UnknownHostException.idl>
53#endif
54
55#ifndef __com_sun_star_io_NoRouteToHostException_idl__
56#include <com/sun/star/io/NoRouteToHostException.idl>
57#endif
58
59#ifndef __com_sun_star_io_ConnectException_idl__
60#include <com/sun/star/io/ConnectException.idl>
61#endif
62
63#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
64#include <com/sun/star/lang/IllegalArgumentException.idl>
65#endif
66
67#ifndef __com_sun_star_mail_XConnectionListener_idl__
68#include <com/sun/star/mail/XConnectionListener.idl>
69#endif
70
71#ifndef __com_sun_star_mail_MailException_idl__
72#include <com/sun/star/mail/MailException.idl>
73#endif
74
75#ifndef __com_sun_star_uno_XCurrentContext_idl__
76#include <com/sun/star/uno/XCurrentContext.idl>
77#endif
78
79
80module com { module sun { module star { module mail {
81
82/**
83   Represents a mail server abstraction.
84
85   @since OOo 2.0
86 */
87interface XMailService: ::com::sun::star::uno::XInterface {
88
89    /**
90        Returns all connection types which are supported to
91        connect to the mail service. At least support insecure
92        connections must be supported. Currently defined
93        connection types are (the values should be handled
94        case insensitive):
95        "Insecure" - insecure connections
96        "Ssl" - Secure Socket Layer 2.0/3.0 based connection
97
98        @returns
99        a sequence of supported connection types.
100    */
101    sequence<string> getSupportedConnectionTypes();
102
103    /**
104        Register a connection listener.
105
106        @param xListener
107        [in] a listener that will be informed about connection events.
108
109        @see com::sun::star::mail::XConnectionListener
110    */
111    void addConnectionListener([in] XConnectionListener xListener);
112
113    /**
114        Unregister a connection listener.
115
116        @param xListener
117        [in] a listener that no longer need to be informed about connection events.
118
119        @see com::sun::star::mail::XConnectionListener
120    */
121    void removeConnectionListener([in] XConnectionListener xListener);
122
123    /**
124        Return the context of the current connnection. The context
125        contains information like the server name, port, connection type
126        etc.
127
128        @precond
129        <code>isConnected</code> returns true.
130
131        @returns
132        the current connection context.
133
134        @throws com::sun::star::io::NotConnectedException
135        if no connection is currently established.
136
137        @see com::sun::star::mail::connectUser
138        @see com::sun::star::io::NotConnectedException
139    */
140    com::sun::star::uno::XCurrentContext getCurrentConnectionContext()
141        raises(com::sun::star::io::NotConnectedException);
142
143    /**
144        Connect to a mail service. Only one connection to a mail service
145        can be established at a time.
146
147        @param xConnectionContext
148        [in] an interface used to query for connection related information.
149        The context must contain the following values:
150        "ServerName" of type 'string', "Port" of type 'long', "ConnectionType"
151        of type 'string'. A list of supported connection types can be queried
152        using <code>getSupportedConnectionTypes</code>.
153
154        @param xAuthenticator
155        [in] an interface used to query for the necessary user information
156        needed to login to the mail server. If no authentication is required
157        the xAuthenticator must return an empty user name and an empty password.
158
159        @throws com::sun::star::lang::IllegalArgumentException
160        if the provided connection context contains invalid values or
161        misses required connection parameters.
162
163        @throws com::sun::star::io::AlreadyConnectedException
164        on a try to connect to an already connect mail server.
165
166        @throws com::sun::star::io::UnknownHostException
167        usually if the IP address of the mail server could not be
168        determined. Possible causes are a broken network connection,
169        a wrong server name, an unreachable DNS server, etc.
170
171        @throws com::sun::star::io::NoRouteToHostException
172        if an error occured to connect to the remote mail server.
173        Typically the remote mail server cannot be reach because of an
174        intervening firewall, or if an intermediate router is down,
175        the network connection is broken, etc.
176
177        @throws com::sun::star::io::ConnectException
178        if an error occured while attempting to connect to the remote
179        mail server. Typically the connection was refused remotely,
180        because the mail server is not listening on the remote address/port.
181
182        @throws com::sun::star::auth::AuthenticationException
183        if the specified user could not be logged in.
184
185        @throws com::sun::star::mail::MailException
186        for other errors during login.
187
188        @see com::sun::star::uno::XCurrentContext
189        @see com::sun::star::mail::XAuthenticator
190        @see com::sun::star::lang::IllegalArgumentException
191        @see com::sun::star::io::AlreadyConnectedException
192        @see com::sun::star::io::UnknownHostException
193        @see com::sun::star::io::NoRouteToHostException
194        @see com::sun::star::io::ConnectException
195        @see com::sun::star::auth::AuthenticationException
196        @see com::sun::star::mail::IllegalStateException
197        @see com::sun::star::mail::MailException
198    */
199    void connect([in] com::sun::star::uno::XCurrentContext xConnectionContext, [in] XAuthenticator xAuthenticator)
200        raises(com::sun::star::lang::IllegalArgumentException,
201               com::sun::star::io::AlreadyConnectedException,
202               com::sun::star::io::UnknownHostException,
203               com::sun::star::io::NoRouteToHostException,
204               com::sun::star::io::ConnectException,
205               com::sun::star::auth::AuthenticationFailedException,
206               com::sun::star::mail::MailException);
207
208    /**
209        Disconnect from a mail service.
210
211        @throws com::sun::star::mail::MailException
212        if errors occur during disconnecting.
213    */
214    void disconnect()
215        raises(com::sun::star::mail::MailException);
216
217    /**
218        Returns whether a connection to a mail service
219        currently exist or not.
220
221        @returns
222        <TRUE/> if a connection to a mail service is established.
223    */
224    boolean isConnected();
225};
226
227}; }; }; };
228
229#endif
230