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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21 module com { module sun { module star { module mail {
  22
  23 /**
  24    Represents a mail server abstraction.
  25
  26    @since OOo 2.0
  27  */
  28 interface XMailService: ::com::sun::star::uno::XInterface {
  29
  30     /**
  31         Returns all connection types which are supported to
  32         connect to the mail service. At least support insecure
  33         connections must be supported. Currently defined
  34         connection types are (the values should be handled
  35         case insensitive):
  36         "Insecure" - insecure connections
  37         "SSL" - Secure Socket Layer 2.0/3.0 based connection
  38
  39         @returns
  40         a sequence of supported connection types.
  41     */
  42     sequence<string> getSupportedConnectionTypes();
  43
  44     /**
  45         Register a connection listener.
  46
  47         @param xListener
  48         [in] a listener that will be informed about connection events.
  49
  50         @see com::sun::star::mail::XConnectionListener
  51     */
  52     void addConnectionListener([in] XConnectionListener xListener);
  53
  54     /**
  55         Unregister a connection listener.
  56
  57         @param xListener
  58         [in] a listener that no longer need to be informed about connection events.
  59
  60         @see com::sun::star::mail::XConnectionListener
  61     */
  62     void removeConnectionListener([in] XConnectionListener xListener);
  63
  64     /**
  65         Return the context of the current connection. The context
  66         contains information like the server name, port, connection type
  67         etc.
  68
  69         @pre
  70         <code>isConnected</code> returns true.
  71
  72         @returns
  73         the current connection context.
  74
  75         @throws com::sun::star::io::NotConnectedException
  76         if no connection is currently established.
  77
  78         @see com::sun::star::mail::connectUser
  79         @see com::sun::star::io::NotConnectedException
  80     */
  81     com::sun::star::uno::XCurrentContext getCurrentConnectionContext()
  82         raises(com::sun::star::io::NotConnectedException);
  83
  84     /**
  85         Connect to a mail service. Only one connection to a mail service
  86         can be established at a time.
  87
  88         @param xConnectionContext
  89         [in] an interface used to query for connection related information.
  90         The context must contain the following values:
  91         <ul>
  92             <li>
  93                 <b>ServerName</b> of type 'string'.
  94             </li>
  95             <li>
  96                 <b>Port</b> of type 'long'.
  97             </li>
  98             <li>
  99                 <b>ConnectionType</b> of type 'string'.
 100                 A list of supported connection types can be queried using
 101                 getSupportedConnectionTypes().
 102             </li>
 103             <li>
 104                 <b>Timeout</b> of type 'long' (Optional).
 105                 Specifies a timeout in seconds for blocking operations,
 106                 like the connection attempt.
 107             </li>
 108         </ul>
 109
 110         @param xAuthenticator
 111         [in] an interface used to query for the necessary user information
 112         needed to login to the mail server. If no authentication is required
 113         the xAuthenticator must return an empty user name and an empty password.
 114
 115         @throws com::sun::star::lang::IllegalArgumentException
 116         if the provided connection context contains invalid values or
 117         misses required connection parameters.
 118
 119         @throws com::sun::star::io::AlreadyConnectedException
 120         on a try to connect to an already connect mail server.
 121
 122         @throws com::sun::star::io::UnknownHostException
 123         usually if the IP address of the mail server could not be
 124         determined. Possible causes are a broken network connection,
 125         a wrong server name, an unreachable DNS server, etc.
 126
 127         @throws com::sun::star::io::NoRouteToHostException
 128         if an error occurred to connect to the remote mail server.
 129         Typically the remote mail server cannot be reach because of an
 130         intervening firewall, or if an intermediate router is down,
 131         the network connection is broken, etc.
 132
 133         @throws com::sun::star::io::ConnectException
 134         if an error occurred while attempting to connect to the remote
 135         mail server. Typically the connection was refused remotely,
 136         because the mail server is not listening on the remote address/port.
 137
 138         @throws com::sun::star::auth::AuthenticationException
 139         if the specified user could not be logged in.
 140
 141         @throws com::sun::star::mail::MailException
 142         for other errors during login.
 143
 144         @see com::sun::star::uno::XCurrentContext
 145         @see com::sun::star::mail::XAuthenticator
 146         @see com::sun::star::lang::IllegalArgumentException
 147         @see com::sun::star::io::AlreadyConnectedException
 148         @see com::sun::star::io::UnknownHostException
 149         @see com::sun::star::io::NoRouteToHostException
 150         @see com::sun::star::io::ConnectException
 151         @see com::sun::star::auth::AuthenticationException
 152         @see com::sun::star::mail::IllegalStateException
 153         @see com::sun::star::mail::MailException
 154     */
 155     void connect([in] com::sun::star::uno::XCurrentContext xConnectionContext, [in] XAuthenticator xAuthenticator)
 156         raises(com::sun::star::lang::IllegalArgumentException,
 157                com::sun::star::io::AlreadyConnectedException,
 158                com::sun::star::io::UnknownHostException,
 159                com::sun::star::io::NoRouteToHostException,
 160                com::sun::star::io::ConnectException,
 161                com::sun::star::auth::AuthenticationFailedException,
 162                com::sun::star::mail::MailException);
 163
 164     /**
 165         Disconnect from a mail service.
 166
 167         @throws com::sun::star::mail::MailException
 168         if errors occur during disconnecting.
 169     */
 170     void disconnect()
 171         raises(com::sun::star::mail::MailException);
 172
 173     /**
 174         Returns whether a connection to a mail service
 175         currently exist or not.
 176
 177         @returns
 178         `TRUE` if a connection to a mail service is established.
 179     */
 180     boolean isConnected();
 181 };
 182
 183 }; }; }; };
 184
 185 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */