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

   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
  80 module com { module sun { module star { module mail {
  81
  82 /**
  83    Represents a mail server abstraction.
  84
  85    @since OOo 2.0.0
  86  */
  87 interface 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