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