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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21
  22 module com {  module sun {  module star {  module lang {
  23
  24 /** supports connection points for connectable objects.
  25
  26     <p>Connectable objects support the following features: </p>
  27
  28     <ul>
  29         <li>outgoing interfaces, such as event sets; </li>
  30         <li>the ability to enumerate the types of the outgoing interfaces;
  31         <li>the ability to connect and disconnect sinks to the object
  32             for those outgoing types; </li>
  33         <li>the ability to enumerate the connections that exist to a
  34             particular outgoing interface.  </li>
  35     </ul>
  36
  37     <h4>When to Implement?</h4>
  38
  39     <p>To create a connectable object, you need to implement objects
  40     that provide two related interfaces: </p>
  41
  42     <ul>
  43         <li>XConnectionPointContainer </li>
  44         <li>XConnectionPoint </li>
  45     </ul>
  46
  47     <p>The XConnectionPointContainer interface is implemented
  48     on the connectable object to indicate the existence of the outgoing
  49     interfaces. It provides a sequence of sub-objects.  It also provides
  50     access to all the connection point sub-objects, each of which
  51     implements the XConnectionPoint interface. The
  52     XConnectionPoint interface provides a sequence of
  53     sub-objects.  </p>
  54
  55     <p>Each connection point is a separate sub-object to avoid circular
  56     reference counting problems.  A connection point controls how many
  57     connections (one or more) it will allow in its implementation of
  58     XConnectionPoint::advise().  </p>
  59
  60     <h4>When to use?</h4>
  61
  62     <p>A client can use the XConnectionPointContainer interface: </p>
  63
  64     -       to get a sequence of connection points for each outgoing type.
  65
  66     -       to obtain access to connection point sub-objects with the
  67             XConnectionPoint interface for each
  68             outgoing type. Through the XConnectionPoint interface,
  69             a client starts or terminates an advisory loop with the
  70             connectable object and the client's own sink.  The
  71             client can also use the XConnectionPoint
  72             interface to get a sequence of the connections that it
  73             knows about.
  74
  75     @see        XConnectionPointContainer
  76  */
  77 published interface XConnectionPoint: com::sun::star::uno::XInterface
  78 {
  79     /** @returns
  80                 the type of the outgoing interface managed by this
  81                 connection point.
  82
  83         <p>Using the XConnectionPointContainer::getConnectionPoints()
  84         method, a client can obtain an XConnectionPoint
  85         interface.  Using that interface and this method, the client
  86         can determine the type of each connection point enumerated. The
  87         type returned from this method must enable the caller to access
  88         this same connection point through
  89         XConnectionPointContainer::findConnectionPoint().
  90
  91         @see XConnectionPointContainer::findConnectionPoint
  92      */
  93     type getConnectionType();
  94
  95     /** @returns
  96             the XConnectionPointContainer interface on
  97             the parent connectable object.
  98
  99         @see XConnectionPointContainer
 100      */
 101     com::sun::star::lang::XConnectionPointContainer getConnectionPointContainer();
 102
 103     /** creates a connection between a connection point and a
 104         client's sink, where the sink implements the outgoing interface
 105         supported by this connection point.
 106
 107         <p>A few <code>add...Listener</code> methods need additional parameters
 108         to add listeners or throw exceptions. One of these methods is
 109         com::sun::star::beans::XPropertySet::addPropertyChangeListener().
 110         We ignore the problem in this interface. A solution must be provided
 111         in an additional XConnectionPoint interface.  </p>
 112
 113         @param xListener
 114             specifies the listener interface on the client's advise sink.
 115             The client's sink receives outgoing calls from the
 116             connection point container.
 117
 118         @throws ListenerExistException
 119             if it is an unicast broadcaster and a listener is already set.
 120
 121         @throws InvalidListenerException
 122             if the listener does not supply the needed interfaces.
 123
 124         @see com::sun::star::beans::XPropertySet::addPropertyChangeListener
 125      */
 126     void advise( [in] com::sun::star::uno::XInterface xListener )
 127             raises( com::sun::star::lang::ListenerExistException,
 128                     com::sun::star::lang::InvalidListenerException );
 129
 130     /** terminates a notification previously set up with advise.
 131
 132         <p>A few <code>remove...Listener</code> methods need additional
 133         parameters to add listeners or throw exceptions. One of these methods
 134         is com::sun::star::beans::XPropertySet::removePropertyChangeListener().
 135         We ignore the problem in this interface. A solution must be
 136         provided in an additional XConnectionPoint interface.  </p>
 137
 138         @param xListener
 139             specifies the listener interface on the client's advise sink.
 140
 141         @see com::sun::star::beans::XPropertySet::removePropertyChangeListener
 142      */
 143     void unadvise( [in] com::sun::star::uno::XInterface xListener );
 144
 145     /** @returns
 146                 a sequence of all currently advised connections.
 147      */
 148     sequence<com::sun::star::uno::XInterface> getConnections();
 149
 150 };
 151
 152
 153 }; }; }; };
 154
 155 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */