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 OOo 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        "ServerName" of type 'string', "Port" of type 'long', "ConnectionType"
147        of type 'string'. A list of supported connection types can be queried
148        using <code>getSupportedConnectionTypes</code>.
149
150        @param xAuthenticator
151        [in] an interface used to query for the necessary user information
152        needed to login to the mail server. If no authentication is required
153        the xAuthenticator must return an empty user name and an empty password.
154
155        @throws com::sun::star::lang::IllegalArgumentException
156        if the provided connection context contains invalid values or
157        misses required connection parameters.
158
159        @throws com::sun::star::io::AlreadyConnectedException
160        on a try to connect to an already connect mail server.
161
162        @throws com::sun::star::io::UnknownHostException
163        usually if the IP address of the mail server could not be
164        determined. Possible causes are a broken network connection,
165        a wrong server name, an unreachable DNS server, etc.
166
167        @throws com::sun::star::io::NoRouteToHostException
168        if an error occured to connect to the remote mail server.
169        Typically the remote mail server cannot be reach because of an
170        intervening firewall, or if an intermediate router is down,
171        the network connection is broken, etc.
172
173        @throws com::sun::star::io::ConnectException
174        if an error occured while attempting to connect to the remote
175        mail server. Typically the connection was refused remotely,
176        because the mail server is not listening on the remote address/port.
177
178        @throws com::sun::star::auth::AuthenticationException
179        if the specified user could not be logged in.
180
181        @throws com::sun::star::mail::MailException
182        for other errors during login.
183
184        @see com::sun::star::uno::XCurrentContext
185        @see com::sun::star::mail::XAuthenticator
186        @see com::sun::star::lang::IllegalArgumentException
187        @see com::sun::star::io::AlreadyConnectedException
188        @see com::sun::star::io::UnknownHostException
189        @see com::sun::star::io::NoRouteToHostException
190        @see com::sun::star::io::ConnectException
191        @see com::sun::star::auth::AuthenticationException
192        @see com::sun::star::mail::IllegalStateException
193        @see com::sun::star::mail::MailException
194    */
195    void connect([in] com::sun::star::uno::XCurrentContext xConnectionContext, [in] XAuthenticator xAuthenticator)
196        raises(com::sun::star::lang::IllegalArgumentException,
197               com::sun::star::io::AlreadyConnectedException,
198               com::sun::star::io::UnknownHostException,
199               com::sun::star::io::NoRouteToHostException,
200               com::sun::star::io::ConnectException,
201               com::sun::star::auth::AuthenticationFailedException,
202               com::sun::star::mail::MailException);
203
204    /**
205        Disconnect from a mail service.
206
207        @throws com::sun::star::mail::MailException
208        if errors occur during disconnecting.
209    */
210    void disconnect()
211        raises(com::sun::star::mail::MailException);
212
213    /**
214        Returns whether a connection to a mail service
215        currently exist or not.
216
217        @returns
218        <TRUE/> if a connection to a mail service is established.
219    */
220    boolean isConnected();
221};
222
223}; }; }; };
224
225#endif
226