xref: /trunk/main/offapi/com/sun/star/mail/XMailServer.idl (revision a893be29)
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_XMailServer_idl__
25#define __com_sun_star_mail_XMailServer_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_mail_XMailMessage_idl__
36#include <com/sun/star/mail/XMailMessage.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_ucb_InteractiveIOException_idl__
68#include <com/sun/star/ucb/InteractiveIOException.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_mail_SendMailMessageFailedException_idl__
76#include <com/sun/star/mail/SendMailMessageFailedException.idl>
77#endif
78
79#ifndef __com_sun_star_mail_XConnectionListener_idl__
80#include <com/sun/star/mail/XConnectionListener.idl>
81#endif
82
83#ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__
84#include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
85#endif
86
87module com { module sun { module star { module mail {
88
89/**
90   Represents a mail server abstraction.
91
92   @see com::sun::star::mail::XMailMessage
93
94   @since OpenOffice 2.0
95 */
96interface XMailServer: ::com::sun::star::uno::XInterface {
97
98    /**
99        The complete domain name of the mail server.
100    */
101    [attribute, readonly] string Name;
102
103    /**
104        The port number that will be used to connect to the mail server.
105        If no port number has been set the default port number 25 will
106        be used.
107    */
108    [attribute] long Port;
109
110    /**
111        Returns all connection types which are supported by the
112        mail server. Possible connection types are for instance
113        secure connections like 'SSL' or 'TLS'.
114
115        @returns
116        a sequence of supported connection types.
117    */
118    sequence<string> getSupportedConnectionTypes();
119
120    /**
121        Set the connection type that will be used to connect to the
122        mail server. The supported connection types may be queried
123        using <code>getSupportedConnectionTypes()</code>.
124        If no connection types has explicitly been set the default
125        connection type will be used.
126
127        @param sConnectionType
128        [in] identifies the connection that should be used to connect
129        to the mail server.
130
131        @throws com::sun::star::lang::IllegalArgumentException
132        if the provided connection type is not supported.
133
134        @see getSupportedConnectionTypes
135        @see isConnectionTypeSupported
136    */
137    void setConnectionType([in] string sConnectionType)
138        raises (com::sun::star::lang::IllegalArgumentException);
139
140    /**
141        Allow a client to query if a certain connection type is
142        supported.
143
144        @param sConnectionType
145        [in] query if a certain connection type is supported.
146
147        @returns
148        <TRUE/> if the specified connection type is supported.
149    */
150    boolean isConnectionTypeSupported([in] string sConnectionType);
151
152    /**
153        Register a connection listener.
154
155        @param xListener
156        [in] a listener that will be informed about connection events.
157
158        @see com::sun::star::mail::XConnectionListener
159    */
160    void addConnectionListener([in] XConnectionListener xListener);
161
162    /**
163        Unregister a connection listener.
164
165        @param xListener
166        [in] a listener that no longer need to be informed about connection events.
167
168        @see com::sun::star::mail::XConnectionListener
169    */
170    void removeConnectionListener([in] XConnectionListener xListener);
171
172    /**
173        Login a user to the mail server. Only one user may logged in
174        at a time. An attempt to login while another user is logged in
175        causes an exception to be thrown.
176
177        @param xAuthenticator
178        [in] an interface used to query for the necessary user information
179        needed to login to the mail server.
180
181        @throws com::sun::star::io::AlreadyConnectedException
182        on a try to connect to an already connect mail server.
183
184        @throws com::sun::star::io::UnknownHostException
185        usually if the IP address of the mail server could not be
186        determined. Possible causes are a broken network connection,
187        a wrong server name, an unreachable DNS server, etc.
188
189        @throws com::sun::star::io::NoRouteToHostException
190        if an error occurred to connect to the remote mail server.
191        Typically the remote mail server cannot be reach because of an
192        intervening firewall, or if an intermediate router is down,
193        the network connection is broken, etc.
194
195        @throws com::sun::star::io::ConnectException
196        if an error occurred while attempting to connect to the remote
197        mail server. Typically the connection was refused remotely,
198        because the mail server is not listening on the remote address/port.
199
200        @throws com::sun::star::auth::AuthenticationException
201        if the specified user could not be logged in.
202
203        @throws com::sun::star::mail::IllegalStateException
204        if a user is currently logged in.
205
206        @throws com::sun::star::mail::MailException
207        for other errors during login.
208
209        @see com::sun::star::mail::XAuthenticator
210        @see com::sun::star::io::AlreadyConnectedException
211        @see com::sun::star::io::UnknownHostException
212        @see com::sun::star::io::NoRouteToHostException
213        @see com::sun::star::io::ConnectException
214        @see com::sun::star::auth::AuthenticationException
215        @see com::sun::star::mail::IllegalStateException
216        @see com::sun::star::mail::MailException
217    */
218    void connectUser([in] XAuthenticator xAuthenticator)
219        raises(com::sun::star::io::AlreadyConnectedException,
220               com::sun::star::io::UnknownHostException,
221               com::sun::star::io::NoRouteToHostException,
222               com::sun::star::io::ConnectException,
223               com::sun::star::auth::AuthenticationFailedException,
224               com::sun::star::mail::MailException);
225
226    /**
227        Logoff the currently logged in user.
228
229        @throws com::sun::star::mail::MessagingException
230        if errors occur during logoff.
231    */
232    void disconnectUser()
233        raises(com::sun::star::mail::MailException);
234
235    /**
236        Returns whether a user is currently logged in to the mail server or not.
237
238        @returns
239        <TRUE/> if a user is currently logged in to the mail server.
240    */
241    boolean isUserConnected();
242
243    /**
244        Send a mail message to its recipients.
245
246        @throws com::sun::star::io::NotConnectedException
247        if no user is currently connected to the mail server.
248
249        @throws com::sun::star::mail::SendMailMessageFailedException
250        if the message could not be sent because of invalid recipient
251        addresses. The e-mail addresses of recipients have to conform to
252        <a href="http://www.ietf.org/rfc/rfc822.txt">RFC&nbsp;822</a>.
253
254        @throws com::sun::star::mail::MailException
255        is thrown on other errors that may happen during sending.
256        A possible reason may be for instance that a file attachment
257        specified in a mail message could not be found or accessed.
258
259        @throws com::sun::star::datatransfer::UnsupportedFlavorException
260        is thrown when the body of the mail message is provided in an
261        unsupported mime content type or may be thrown if one of the file
262        attachments specifies an unspupported mime content type.
263
264        @see com::sun::star::io::NotConnectedExceptionException
265        @see com::sun::star::mail::SendMailMessageFailedException
266        @see com::sun::star::mail::MailException
267        @see com::sun::star::datatransfer::UnsupportedFlavorException
268    */
269    void sendMailMessage([in] XMailMessage xMailMessage)
270        raises(com::sun::star::io::NotConnectedException, com::sun::star::mail::SendMailMessageFailedException, com::sun::star::mail::MailException, com::sun::star::datatransfer::UnsupportedFlavorException);
271};
272
273}; }; }; };
274
275#endif
276