udkapi/com/sun/star/lang/XConnectionPoint.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XConnectionPoint.idl,v $
  10  * $Revision: 1.16 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_lang_XConnectionPoint_idl__
  31 #define __com_sun_star_lang_XConnectionPoint_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_lang_XConnectionPointContainer_idl__
  38 #include <com/sun/star/lang/XConnectionPointContainer.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_lang_ListenerExistException_idl__
  42 #include <com/sun/star/lang/ListenerExistException.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_lang_InvalidListenerException_idl__
  46 #include <com/sun/star/lang/InvalidListenerException.idl>
  47 #endif
  48
  49
  50 //=============================================================================
  51
  52 module com {  module sun {  module star {  module lang {
  53
  54 //=============================================================================
  55
  56 // DocMerge from idl: interface com::sun::star::lang::XConnectionPoint
  57 /** supports connection points for connectable objects.
  58
  59     <p>Connectable objects support the following features: </p>
  60
  61     <ul>
  62         <li>outgoing interfaces, such as event sets; </li>
  63         <li>the ability to enumerate the types of the outgoing interfaces;
  64         <li>the ability to connect and disconnect sinks to the object
  65             for those outgoing types; </li>
  66         <li>the ability to enumerate the connections that exist to a
  67             particular outgoing interface.  </li>
  68     </ul>
  69
  70     <h4>When to Implement?<h4>
  71
  72     <p>To create a connectable object, you need to implement objects
  73     that provide two related interfaces: </p>
  74
  75     <ul>
  76         <li><type>XConnectionPointContainer</type> </li>
  77         <li><type>XConnectionPoint</type> </li>
  78     </ul>
  79
  80     <p>The <type>XConnectionPointContainer</type> interface is implemented
  81     on the connectable object to indicate the existence of the outgoing
  82     interfaces. It provides a sequence of sub-objects.  It also provides
  83     access to all the connection point sub-objects, each of which
  84     implements the <type>XConnectionPoint</type> interface. The
  85     <type>XConnectionPoint</type> interface provides a sequence of
  86     sub-objects.  </p>
  87
  88     <p>Each connection point is a separate sub-object to avoid circular
  89     reference counting problems.  A connection point controls how many
  90     connections (one or more) it will allow in its implementation of
  91     <member>XConnectionPoint::advise()</member>.  </p>
  92
  93     <h4>When to use?</h4>
  94
  95     <p>A client can use the <type>XConnectionPointContainer</type> interface: </p>
  96
  97     <UL>
  98
  99         <LI>to get a sequence of connection points for each outgoing type. </LI>
 100
 101         <LI>to obtain access to connection point sub-objects with the
 102             <type>XConnectionPoint</type> interface for each
 103             outgoing type. Through the XConnectionPoint interface,
 104             a client starts or terminates an advisory loop with the
 105             connectable object and the client's own sink.  The
 106             client can also use the <type>XConnectionPoint</type>
 107             interface to get a sequence of the connections that it
 108             knows about. </LI>
 109     </UL>
 110
 111     @see                XConnectionPointContainer
 112  */
 113 published interface XConnectionPoint: com::sun::star::uno::XInterface
 114 {
 115     //-------------------------------------------------------------------------
 116
 117     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::getConnectionType
 118     /** @returns
 119                 the type of the outgoing interface managed by this
 120                 connection point.
 121
 122         <p>Using the <member>XConnectionPointContainer::getConnectionPoints</member>
 123         method, a client can obtain an <type>XConnectionPoint</type>
 124         interface.  Using that interface and this method, the client
 125         can determine the type of each connection point enumerated. The
 126         type returned from this method must enable the caller to access
 127         this same connection point through
 128         <member>XConnectionPointContainer::findConnectionPoint</member>.
 129
 130         @see XConnectionPointContainer::findConnectionPoint
 131      */
 132     type getConnectionType();
 133
 134     //-------------------------------------------------------------------------
 135
 136     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::getConnectionPointContainer
 137     /** @returns
 138             the <type>XConnectionPointContainer</type> interface on
 139             the parent connectable object.
 140
 141         @see XConnectionPointContainer
 142      */
 143     com::sun::star::lang::XConnectionPointContainer getConnectionPointContainer();
 144
 145     //-------------------------------------------------------------------------
 146
 147     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::advise
 148     /** creates a connection between a connection point and a
 149         client's sink, where the sink implements the outgoing interface
 150         supported by this connection point.
 151
 152         <p>A few <code>add...Listener</code> methods need additional parameters
 153         to add listeners or throw exceptions. One of these methods is
 154         <member scope="com::sun::star::beans">XPropertySet::addPropertyChangeListener</member>.
 155         We ignore the problem in this interface. A solution must be provided
 156         in an additional <type>XConnectionPoint</type> interface.  </p>
 157
 158         @param xListener
 159             specifies the listener interface on the client's advise sink.
 160             The client's sink receives outgoing calls from the
 161             connection point container.
 162
 163         @throws ListenerExistException
 164             if it is a unicast broadcaster and a listener is already set.
 165
 166         @throws InvalidListenerException
 167             if the listener does not supply the needed interfaces.
 168
 169         @see com::sun::star::beans::XPropertySet::addPropertyChangeListener
 170      */
 171     void advise( [in] com::sun::star::uno::XInterface xListener )
 172             raises( com::sun::star::lang::ListenerExistException,
 173                     com::sun::star::lang::InvalidListenerException );
 174
 175     //-------------------------------------------------------------------------
 176
 177     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::unadvise
 178     /** terminates a notification previously set up with advise.
 179
 180         <p>A few <code>remove...Listener</code> methods need additional
 181         parameters to add listeners or throw exceptions. One of these methods
 182         is <member scope="com::sun::star::beans">XPropertySet::removePropertyChangeListener</member>.
 183         We ignore the problem in this interface. A solution must be
 184         provided in an additional <type>XConnectionPoint</type> interface.  </p>
 185
 186         @param listener
 187             specifies the listener interface on the client's advise sink.
 188
 189         @see com::sun::star::beans::XPropertySet::removePropertyChangeListener
 190      */
 191     void unadvise( [in] com::sun::star::uno::XInterface xListener );
 192
 193     //-------------------------------------------------------------------------
 194
 195     // DocMerge from idl: method com::sun::star::lang::XConnectionPoint::getConnections
 196     /** @returns
 197                 a sequence of all currently advised connections.
 198      */
 199     sequence<com::sun::star::uno::XInterface> getConnections();
 200
 201 };
 202
 203 //=============================================================================
 204
 205 }; }; }; };
 206
 207 #endif