xref: /aoo4110/main/offapi/com/sun/star/mail/XMailService.idl (revision b1cdbd2c)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/



#ifndef __com_sun_star_mail_XMailService_idl__
#define __com_sun_star_mail_XMailService_idl__

#ifndef __com_sun_star_uno_XInterface_idl__
#include <com/sun/star/uno/XInterface.idl>
#endif

#ifndef __com_sun_star_mail_XAuthenticator_idl__
#include <com/sun/star/mail/XAuthenticator.idl>
#endif

#ifndef __com_sun_star_auth_AuthenticationFailedException_idl__
#include <com/sun/star/auth/AuthenticationFailedException.idl>
#endif

#ifndef __com_sun_star_io_AlreadyConnectedException_idl__
#include <com/sun/star/io/AlreadyConnectedException.idl>
#endif

#ifndef __com_sun_star_io_NotConnectedException_idl__
#include <com/sun/star/io/NotConnectedException.idl>
#endif

#ifndef __com_sun_star_io_UnknownHostException_idl__
#include <com/sun/star/io/UnknownHostException.idl>
#endif

#ifndef __com_sun_star_io_NoRouteToHostException_idl__
#include <com/sun/star/io/NoRouteToHostException.idl>
#endif

#ifndef __com_sun_star_io_ConnectException_idl__
#include <com/sun/star/io/ConnectException.idl>
#endif

#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif

#ifndef __com_sun_star_mail_XConnectionListener_idl__
#include <com/sun/star/mail/XConnectionListener.idl>
#endif

#ifndef __com_sun_star_mail_MailException_idl__
#include <com/sun/star/mail/MailException.idl>
#endif

#ifndef __com_sun_star_uno_XCurrentContext_idl__
#include <com/sun/star/uno/XCurrentContext.idl>
#endif


module com { module sun { module star { module mail {

/**
   Represents a mail server abstraction.

   @since OpenOffice 2.0
 */
interface XMailService: ::com::sun::star::uno::XInterface {

    /**
        Returns all connection types which are supported to
        connect to the mail service. At least support insecure
        connections must be supported. Currently defined
        connection types are (the values should be handled
        case insensitive):
        "Insecure" - insecure connections
        "Ssl" - Secure Socket Layer 2.0/3.0 based connection

        @returns
        a sequence of supported connection types.
    */
    sequence<string> getSupportedConnectionTypes();

    /**
        Register a connection listener.

        @param xListener
        [in] a listener that will be informed about connection events.

        @see com::sun::star::mail::XConnectionListener
    */
    void addConnectionListener([in] XConnectionListener xListener);

    /**
        Unregister a connection listener.

        @param xListener
        [in] a listener that no longer need to be informed about connection events.

        @see com::sun::star::mail::XConnectionListener
    */
    void removeConnectionListener([in] XConnectionListener xListener);

    /**
        Return the context of the current connnection. The context
        contains information like the server name, port, connection type
        etc.

        @precond
        <code>isConnected</code> returns true.

        @returns
        the current connection context.

        @throws com::sun::star::io::NotConnectedException
        if no connection is currently established.

        @see com::sun::star::mail::connectUser
        @see com::sun::star::io::NotConnectedException
    */
    com::sun::star::uno::XCurrentContext getCurrentConnectionContext()
        raises(com::sun::star::io::NotConnectedException);

    /**
        Connect to a mail service. Only one connection to a mail service
        can be established at a time.

        @param xConnectionContext
        [in] an interface used to query for connection related information.
        The context must contain the following values:
        <ul>
            <li>
                <b>ServerName</b> of type 'string'.
            </li>
            <li>
                <b>Port</b> of type 'long'.
            </li>
            <li>
                <b>ConnectionType</b> of type 'string'.
                A list of supported connection types can be queried using
                <member>getSupportedConnectionTypes</member>.
            </li>
            <li>
                <b>Timeout</b> of type 'long' (Optional).
                Specifies a timeout in seconds for blocking operations,
                like the connection attempt.
            </li>
        </ul>

        @param xAuthenticator
        [in] an interface used to query for the necessary user information
        needed to login to the mail server. If no authentication is required
        the xAuthenticator must return an empty user name and an empty password.

        @throws com::sun::star::lang::IllegalArgumentException
        if the provided connection context contains invalid values or
        misses required connection parameters.

        @throws com::sun::star::io::AlreadyConnectedException
        on a try to connect to an already connect mail server.

        @throws com::sun::star::io::UnknownHostException
        usually if the IP address of the mail server could not be
        determined. Possible causes are a broken network connection,
        a wrong server name, an unreachable DNS server, etc.

        @throws com::sun::star::io::NoRouteToHostException
        if an error occured to connect to the remote mail server.
        Typically the remote mail server cannot be reach because of an
        intervening firewall, or if an intermediate router is down,
        the network connection is broken, etc.

        @throws com::sun::star::io::ConnectException
        if an error occured while attempting to connect to the remote
        mail server. Typically the connection was refused remotely,
        because the mail server is not listening on the remote address/port.

        @throws com::sun::star::auth::AuthenticationException
        if the specified user could not be logged in.

        @throws com::sun::star::mail::MailException
        for other errors during login.

        @see com::sun::star::uno::XCurrentContext
        @see com::sun::star::mail::XAuthenticator
        @see com::sun::star::lang::IllegalArgumentException
        @see com::sun::star::io::AlreadyConnectedException
        @see com::sun::star::io::UnknownHostException
        @see com::sun::star::io::NoRouteToHostException
        @see com::sun::star::io::ConnectException
        @see com::sun::star::auth::AuthenticationException
        @see com::sun::star::mail::IllegalStateException
        @see com::sun::star::mail::MailException
    */
    void connect([in] com::sun::star::uno::XCurrentContext xConnectionContext, [in] XAuthenticator xAuthenticator)
        raises(com::sun::star::lang::IllegalArgumentException,
               com::sun::star::io::AlreadyConnectedException,
               com::sun::star::io::UnknownHostException,
               com::sun::star::io::NoRouteToHostException,
               com::sun::star::io::ConnectException,
               com::sun::star::auth::AuthenticationFailedException,
               com::sun::star::mail::MailException);

    /**
        Disconnect from a mail service.

        @throws com::sun::star::mail::MailException
        if errors occur during disconnecting.
    */
    void disconnect()
        raises(com::sun::star::mail::MailException);

    /**
        Returns whether a connection to a mail service
        currently exist or not.

        @returns
        <TRUE/> if a connection to a mail service is established.
    */
    boolean isConnected();
};

}; }; }; };

#endif