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