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 49module 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 */ 110published 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 205