/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   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 .
 */



module com {  module sun {  module star {  module lang {

/** supports connection points for connectable objects.

    <p>Connectable objects support the following features: </p>

    <ul>
        <li>outgoing interfaces, such as event sets; </li>
        <li>the ability to enumerate the types of the outgoing interfaces;
        <li>the ability to connect and disconnect sinks to the object
            for those outgoing types; </li>
        <li>the ability to enumerate the connections that exist to a
            particular outgoing interface.  </li>
    </ul>

    <h4>When to Implement?</h4>

    <p>To create a connectable object, you need to implement objects
    that provide two related interfaces: </p>

    <ul>
        <li>XConnectionPointContainer </li>
        <li>XConnectionPoint </li>
    </ul>

    <p>The XConnectionPointContainer interface is implemented
    on the connectable object to indicate the existence of the outgoing
    interfaces. It provides a sequence of sub-objects.  It also provides
    access to all the connection point sub-objects, each of which
    implements the XConnectionPoint interface. The
    XConnectionPoint interface provides a sequence of
    sub-objects.  </p>

    <p>Each connection point is a separate sub-object to avoid circular
    reference counting problems.  A connection point controls how many
    connections (one or more) it will allow in its implementation of
    XConnectionPoint::advise().  </p>

    <h4>When to use?</h4>

    <p>A client can use the XConnectionPointContainer interface: </p>

    -       to get a sequence of connection points for each outgoing type.

    -       to obtain access to connection point sub-objects with the
            XConnectionPoint interface for each
            outgoing type. Through the XConnectionPoint interface,
            a client starts or terminates an advisory loop with the
            connectable object and the client's own sink.  The
            client can also use the XConnectionPoint
            interface to get a sequence of the connections that it
            knows about.

    @see        XConnectionPointContainer
 */
published interface XConnectionPoint: com::sun::star::uno::XInterface
{
    /** @returns
                the type of the outgoing interface managed by this
                connection point.

        <p>Using the XConnectionPointContainer::getConnectionPoints()
        method, a client can obtain an XConnectionPoint
        interface.  Using that interface and this method, the client
        can determine the type of each connection point enumerated. The
        type returned from this method must enable the caller to access
        this same connection point through
        XConnectionPointContainer::findConnectionPoint().

        @see XConnectionPointContainer::findConnectionPoint
     */
    type getConnectionType();

    /** @returns
            the XConnectionPointContainer interface on
            the parent connectable object.

        @see XConnectionPointContainer
     */
    com::sun::star::lang::XConnectionPointContainer getConnectionPointContainer();

    /** creates a connection between a connection point and a
        client's sink, where the sink implements the outgoing interface
        supported by this connection point.

        <p>A few <code>add...Listener</code> methods need additional parameters
        to add listeners or throw exceptions. One of these methods is
        com::sun::star::beans::XPropertySet::addPropertyChangeListener().
        We ignore the problem in this interface. A solution must be provided
        in an additional XConnectionPoint interface.  </p>

        @param xListener
            specifies the listener interface on the client's advise sink.
            The client's sink receives outgoing calls from the
            connection point container.

        @throws ListenerExistException
            if it is an unicast broadcaster and a listener is already set.

        @throws InvalidListenerException
            if the listener does not supply the needed interfaces.

        @see com::sun::star::beans::XPropertySet::addPropertyChangeListener
     */
    void advise( [in] com::sun::star::uno::XInterface xListener )
            raises( com::sun::star::lang::ListenerExistException,
                    com::sun::star::lang::InvalidListenerException );

    /** terminates a notification previously set up with advise.

        <p>A few <code>remove...Listener</code> methods need additional
        parameters to add listeners or throw exceptions. One of these methods
        is com::sun::star::beans::XPropertySet::removePropertyChangeListener().
        We ignore the problem in this interface. A solution must be
        provided in an additional XConnectionPoint interface.  </p>

        @param xListener
            specifies the listener interface on the client's advise sink.

        @see com::sun::star::beans::XPropertySet::removePropertyChangeListener
     */
    void unadvise( [in] com::sun::star::uno::XInterface xListener );

    /** @returns
                a sequence of all currently advised connections.
     */
    sequence<com::sun::star::uno::XInterface> getConnections();

};


}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */