udkapi/com/sun/star/lang/XConnectionPoint.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 #ifndef __com_sun_star_lang_XConnectionPoint_idl__
  28 #define __com_sun_star_lang_XConnectionPoint_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_lang_XConnectionPointContainer_idl__
  35 #include <com/sun/star/lang/XConnectionPointContainer.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_lang_ListenerExistException_idl__
  39 #include <com/sun/star/lang/ListenerExistException.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_lang_InvalidListenerException_idl__
  43 #include <com/sun/star/lang/InvalidListenerException.idl>
  44 #endif
  45
  46
  47 //=============================================================================
  48
  49 module com {  module sun {  module star {  module lang {
  50
  51 //=============================================================================
  52
  53 // DocMerge from idl: interface com::sun::star::lang::XConnectionPoint
  54 /** supports connection points for connectable objects.
  55
  56     <p>Connectable objects support the following features: </p>
  57
  58     <ul>
  59         <li>outgoing interfaces, such as event sets; </li>
  60         <li>the ability to enumerate the types of the outgoing interfaces;
  61         <li>the ability to connect and disconnect sinks to the object
  62             for those outgoing types; </li>
  63         <li>the ability to enumerate the connections that exist to a
  64             particular outgoing interface.  </li>
  65     </ul>
  66
  67     <h4>When to Implement?<h4>
  68
  69     <p>To create a connectable object, you need to implement objects
  70     that provide two related interfaces: </p>
  71
  72     <ul>
  73         <li><type>XConnectionPointContainer</type> </li>
  74         <li><type>XConnectionPoint</type> </li>
  75     </ul>
  76
  77     <p>The <type>XConnectionPointContainer</type> interface is implemented
  78     on the connectable object to indicate the existence of the outgoing
  79     interfaces. It provides a sequence of sub-objects.  It also provides
  80     access to all the connection point sub-objects, each of which
  81     implements the <type>XConnectionPoint</type> interface. The
  82     <type>XConnectionPoint</type> interface provides a sequence of
  83     sub-objects.  </p>
  84
  85     <p>Each connection point is a separate sub-object to avoid circular
  86     reference counting problems.  A connection point controls how many
  87     connections (one or more) it will allow in its implementation of
  88     <member>XConnectionPoint::advise()</member>.  </p>
  89
  90     <h4>When to use?</h4>
  91
  92     <p>A client can use the <type>XConnectionPointContainer</type> interface: </p>
  93
  94     <UL>
  95
  96         <LI>to get a sequence of connection points for each outgoing type. </LI>
  97
  98         <LI>to obtain access to connection point sub-objects with the
  99             <type>XConnectionPoint</type> interface for each
 100             outgoing type. Through the XConnectionPoint interface,
 101             a client starts or terminates an advisory loop with the
 102             connectable object and the client's own sink.  The
 103             client can also use the <type>XConnectionPoint</type>
 104             interface to get a sequence of the connections that it
 105             knows about. </LI>
 106     </UL>
 107
 108     @see        XConnectionPointContainer
 109  */
 110 published interface XConnectionPoint: com::sun::star::uno::XInterface
 111 {
 112     //-------------------------------------------------------------------------
 113
 114     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::getConnectionType
 115     /** @returns
 116                 the type of the outgoing interface managed by this
 117                 connection point.
 118
 119         <p>Using the <member>XConnectionPointContainer::getConnectionPoints</member>
 120         method, a client can obtain an <type>XConnectionPoint</type>
 121         interface.  Using that interface and this method, the client
 122         can determine the type of each connection point enumerated. The
 123         type returned from this method must enable the caller to access
 124         this same connection point through
 125         <member>XConnectionPointContainer::findConnectionPoint</member>.
 126
 127         @see XConnectionPointContainer::findConnectionPoint
 128      */
 129     type getConnectionType();
 130
 131     //-------------------------------------------------------------------------
 132
 133     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::getConnectionPointContainer
 134     /** @returns
 135             the <type>XConnectionPointContainer</type> interface on
 136             the parent connectable object.
 137
 138         @see XConnectionPointContainer
 139      */
 140     com::sun::star::lang::XConnectionPointContainer getConnectionPointContainer();
 141
 142     //-------------------------------------------------------------------------
 143
 144     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::advise
 145     /** creates a connection between a connection point and a
 146         client's sink, where the sink implements the outgoing interface
 147         supported by this connection point.
 148
 149         <p>A few <code>add...Listener</code> methods need additional parameters
 150         to add listeners or throw exceptions. One of these methods is
 151         <member scope="com::sun::star::beans">XPropertySet::addPropertyChangeListener</member>.
 152         We ignore the problem in this interface. A solution must be provided
 153         in an additional <type>XConnectionPoint</type> interface.  </p>
 154
 155         @param xListener
 156             specifies the listener interface on the client's advise sink.
 157             The client's sink receives outgoing calls from the
 158             connection point container.
 159
 160         @throws ListenerExistException
 161             if it is a unicast broadcaster and a listener is already set.
 162
 163         @throws InvalidListenerException
 164             if the listener does not supply the needed interfaces.
 165
 166         @see com::sun::star::beans::XPropertySet::addPropertyChangeListener
 167      */
 168     void advise( [in] com::sun::star::uno::XInterface xListener )
 169             raises( com::sun::star::lang::ListenerExistException,
 170                     com::sun::star::lang::InvalidListenerException );
 171
 172     //-------------------------------------------------------------------------
 173
 174     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::unadvise
 175     /** terminates a notification previously set up with advise.
 176
 177         <p>A few <code>remove...Listener</code> methods need additional
 178         parameters to add listeners or throw exceptions. One of these methods
 179         is <member scope="com::sun::star::beans">XPropertySet::removePropertyChangeListener</member>.
 180         We ignore the problem in this interface. A solution must be
 181         provided in an additional <type>XConnectionPoint</type> interface.  </p>
 182
 183         @param listener
 184             specifies the listener interface on the client's advise sink.
 185
 186         @see com::sun::star::beans::XPropertySet::removePropertyChangeListener
 187      */
 188     void unadvise( [in] com::sun::star::uno::XInterface xListener );
 189
 190     //-------------------------------------------------------------------------
 191
 192     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::getConnections
 193     /** @returns
 194                 a sequence of all currently advised connections.
 195      */
 196     sequence<com::sun::star::uno::XInterface> getConnections();
 197
 198 };
 199
 200 //=============================================================================
 201
 202 }; }; }; };
 203
 204 #endif