offapi/com/sun/star/mail/XMailServer.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XMailServer.idl,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_mail_XMailServer_idl__
  32 #define __com_sun_star_mail_XMailServer_idl__
  33
  34 #ifndef __com_sun_star_uno_XInterface_idl__
  35 #include <com/sun/star/uno/XInterface.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_mail_XAuthenticator_idl__
  39 #include <com/sun/star/mail/XAuthenticator.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_mail_XMailMessage_idl__
  43 #include <com/sun/star/mail/XMailMessage.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_auth_AuthenticationFailedException_idl__
  47 #include <com/sun/star/auth/AuthenticationFailedException.idl>
  48 #endif
  49
  50 #ifndef __com_sun_star_io_AlreadyConnectedException_idl__
  51 #include <com/sun/star/io/AlreadyConnectedException.idl>
  52 #endif
  53
  54 #ifndef __com_sun_star_io_NotConnectedException_idl__
  55 #include <com/sun/star/io/NotConnectedException.idl>
  56 #endif
  57
  58 #ifndef __com_sun_star_io_UnknownHostException_idl__
  59 #include <com/sun/star/io/UnknownHostException.idl>
  60 #endif
  61
  62 #ifndef __com_sun_star_io_NoRouteToHostException_idl__
  63 #include <com/sun/star/io/NoRouteToHostException.idl>
  64 #endif
  65
  66 #ifndef __com_sun_star_io_ConnectException_idl__
  67 #include <com/sun/star/io/ConnectException.idl>
  68 #endif
  69
  70 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  71 #include <com/sun/star/lang/IllegalArgumentException.idl>
  72 #endif
  73
  74 #ifndef __com_sun_star_ucb_InteractiveIOException_idl__
  75 #include <com/sun/star/ucb/InteractiveIOException.idl>
  76 #endif
  77
  78 #ifndef __com_sun_star_mail_MailException_idl__
  79 #include <com/sun/star/mail/MailException.idl>
  80 #endif
  81
  82 #ifndef __com_sun_star_mail_SendMailMessageFailedException_idl__
  83 #include <com/sun/star/mail/SendMailMessageFailedException.idl>
  84 #endif
  85
  86 #ifndef __com_sun_star_mail_XConnectionListener_idl__
  87 #include <com/sun/star/mail/XConnectionListener.idl>
  88 #endif
  89
  90 #ifndef __com_sun_star_datatransfer_UnsupportedFlavorException_idl__
  91 #include <com/sun/star/datatransfer/UnsupportedFlavorException.idl>
  92 #endif
  93
  94 module com { module sun { module star { module mail {
  95
  96 /**
  97    Represents a mail server abstraction.
  98
  99    @see com::sun::star::mail::XMailMessage
 100
 101    @since OOo 2.0.0
 102  */
 103 interface XMailServer: ::com::sun::star::uno::XInterface {
 104
 105     /**
 106         The complete domain name of the mail server.
 107     */
 108     [attribute, readonly] string Name;
 109
 110     /**
 111         The port number that will be used to connect to the mail server.
 112         If no port number has been set the default port number 25 will
 113         be used.
 114     */
 115     [attribute] long Port;
 116
 117     /**
 118         Returns all connection types which are supported by the
 119         mail server. Possible connection types are for instance
 120         secure connections like 'SSL' or 'TLS'.
 121
 122         @returns
 123         a sequence of supported connection types.
 124     */
 125     sequence<string> getSupportedConnectionTypes();
 126
 127     /**
 128         Set the connection type that will be used to connect to the
 129         mail server. The supported connection types may be queried
 130         using <code>getSupportedConnectionTypes()</code>.
 131         If no connection types has explicitly been set the default
 132         connection type will be used.
 133
 134         @param sConnectionType
 135         [in] identifies the connection that should be used to connect
 136         to the mail server.
 137
 138         @throws com::sun::star::lang::IllegalArgumentException
 139         if the provided connection type is not supported.
 140
 141         @see getSupportedConnectionTypes
 142         @see isConnectionTypeSupported
 143     */
 144     void setConnectionType([in] string sConnectionType)
 145         raises (com::sun::star::lang::IllegalArgumentException);
 146
 147     /**
 148         Allow a client to query if a certain connection type is
 149         supported.
 150
 151         @param sConnectionType
 152         [in] query if a certain connection type is supported.
 153
 154         @returns
 155         <TRUE/> if the specified connection type is supported.
 156     */
 157     boolean isConnectionTypeSupported([in] string sConnectionType);
 158
 159     /**
 160         Register a connection listener.
 161
 162         @param xListener
 163         [in] a listener that will be informed about connection events.
 164
 165         @see com::sun::star::mail::XConnectionListener
 166     */
 167     void addConnectionListener([in] XConnectionListener xListener);
 168
 169     /**
 170         Unregister a connection listener.
 171
 172         @param xListener
 173         [in] a listener that no longer need to be informed about connection events.
 174
 175         @see com::sun::star::mail::XConnectionListener
 176     */
 177     void removeConnectionListener([in] XConnectionListener xListener);
 178
 179     /**
 180         Login a user to the mail server. Only one user may logged in
 181         at a time. An attempt to login while another user is logged in
 182         causes an exception to be thrown.
 183
 184         @param xAuthenticator
 185         [in] an interface used to query for the necessary user information
 186         needed to login to the mail server.
 187
 188         @throws com::sun::star::io::AlreadyConnectedException
 189         on a try to connect to an already connect mail server.
 190
 191         @throws com::sun::star::io::UnknownHostException
 192         usually if the IP address of the mail server could not be
 193         determined. Possible causes are a broken network connection,
 194         a wrong server name, an unreachable DNS server, etc.
 195
 196         @throws com::sun::star::io::NoRouteToHostException
 197         if an error occured to connect to the remote mail server.
 198         Typically the remote mail server cannot be reach because of an
 199         intervening firewall, or if an intermediate router is down,
 200         the network connection is broken, etc.
 201
 202         @throws com::sun::star::io::ConnectException
 203         if an error occured while attempting to connect to the remote
 204         mail server. Typically the connection was refused remotely,
 205         because the mail server is not listening on the remote address/port.
 206
 207         @throws com::sun::star::auth::AuthenticationException
 208         if the specified user could not be logged in.
 209
 210         @throws com::sun::star::mail::IllegalStateException
 211         if a user is currently logged in.
 212
 213         @throws com::sun::star::mail::MailException
 214         for other errors during login.
 215
 216         @see com::sun::star::mail::XAuthenticator
 217         @see com::sun::star::io::AlreadyConnectedException
 218         @see com::sun::star::io::UnknownHostException
 219         @see com::sun::star::io::NoRouteToHostException
 220         @see com::sun::star::io::ConnectException
 221         @see com::sun::star::auth::AuthenticationException
 222         @see com::sun::star::mail::IllegalStateException
 223         @see com::sun::star::mail::MailException
 224     */
 225     void connectUser([in] XAuthenticator xAuthenticator)
 226         raises(com::sun::star::io::AlreadyConnectedException,
 227                com::sun::star::io::UnknownHostException,
 228                com::sun::star::io::NoRouteToHostException,
 229                com::sun::star::io::ConnectException,
 230                com::sun::star::auth::AuthenticationFailedException,
 231                com::sun::star::mail::MailException);
 232
 233     /**
 234         Logoff the currently logged in user.
 235
 236         @throws com::sun::star::mail::MessagingException
 237         if errors occur during logoff.
 238     */
 239     void disconnectUser()
 240         raises(com::sun::star::mail::MailException);
 241
 242     /**
 243         Returns whether a user is currently logged in to the mail server or not.
 244
 245         @returns
 246         <TRUE/> if a user is currently logged in to the mail server.
 247     */
 248     boolean isUserConnected();
 249
 250     /**
 251         Send a mail message to its recipients.
 252
 253         @throws com::sun::star::io::NotConnectedException
 254         if no user is currently connected to the mail server.
 255
 256         @throws com::sun::star::mail::SendMailMessageFailedException
 257         if the message could not be sent because of invalid recipient
 258         addresses. The e-mail addresses of recipients have to conform to
 259         <a href="http://www.ietf.org/rfc/rfc822.txt">RFC&nbsp;822</a>.
 260
 261         @throws com::sun::star::mail::MailException
 262         is thrown on other errors that may happen during sending.
 263         A possible reason may be for instance that a file attachment
 264         specified in a mail message could not be found or accessed.
 265
 266         @throws com::sun::star::datatransfer::UnsupportedFlavorException
 267         is thrown when the body of the mail message is provided in an
 268         unsupported mime content type or may be thrown if one of the file
 269         attachments specifies an unspupported mime content type.
 270
 271         @see com::sun::star::io::NotConnectedExceptionException
 272         @see com::sun::star::mail::SendMailMessageFailedException
 273         @see com::sun::star::mail::MailException
 274         @see com::sun::star::datatransfer::UnsupportedFlavorException
 275     */
 276     void sendMailMessage([in] XMailMessage xMailMessage)
 277         raises(com::sun::star::io::NotConnectedException, com::sun::star::mail::SendMailMessageFailedException, com::sun::star::mail::MailException, com::sun::star::datatransfer::UnsupportedFlavorException);
 278 };
 279
 280 }; }; }; };
 281
 282 #endif