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_uno_XAggregation_idl__ 24*b1cdbd2cSJim Jagielski#define __com_sun_star_uno_XAggregation_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//============================================================================= 31*b1cdbd2cSJim Jagielski 32*b1cdbd2cSJim Jagielskimodule com { module sun { module star { module uno { 33*b1cdbd2cSJim Jagielski 34*b1cdbd2cSJim Jagielski//============================================================================= 35*b1cdbd2cSJim Jagielski/** Objects which implement this interface can become aggregates of 36*b1cdbd2cSJim Jagielski a delegator. 37*b1cdbd2cSJim Jagielski 38*b1cdbd2cSJim Jagielski <p>That means if an object "A" aggregates "B", "A" can provide all 39*b1cdbd2cSJim Jagielski or some of the interfaces of "B". Whenever the method 40*b1cdbd2cSJim Jagielski <member>XInterface::queryInterface()</member> 41*b1cdbd2cSJim Jagielski is called on either of the objects, the call will be forwarded 42*b1cdbd2cSJim Jagielski to object "A". Object "A" now can determine whether to use the 43*b1cdbd2cSJim Jagielski interfaces of "A" or "B" or neither. Actually, any number of 44*b1cdbd2cSJim Jagielski aggregates can be used, even nested ones (aggregated objects which are 45*b1cdbd2cSJim Jagielski delegators by themselves). 46*b1cdbd2cSJim Jagielski 47*b1cdbd2cSJim Jagielski <p>The following rules are to be observed: 48*b1cdbd2cSJim Jagielski <ol> 49*b1cdbd2cSJim Jagielski <li>All calls to <member>XInterface::acquire()</member> 50*b1cdbd2cSJim Jagielski which are made before the delegator was set (using the method 51*b1cdbd2cSJim Jagielski <member>XAggregation::setDelegator()</member>) must not be taken back 52*b1cdbd2cSJim Jagielski (using the method <member>XInterface::release()</member>) 53*b1cdbd2cSJim Jagielski before the delegation is removed by calling 54*b1cdbd2cSJim Jagielski <code>xAggregation->setDelegator(NULL)</code>. 55*b1cdbd2cSJim Jagielski 56*b1cdbd2cSJim Jagielski <li>The constructor of a delegator has to increment its 57*b1cdbd2cSJim Jagielski own reference count by calling its method 58*b1cdbd2cSJim Jagielski <member>XInterface::acquire()</member> 59*b1cdbd2cSJim Jagielski before it sets itself to any aggregate using the method 60*b1cdbd2cSJim Jagielski <member>XAggregation::setDelegator()</member>. After that 61*b1cdbd2cSJim Jagielski call it has to reset its own reference count without the 62*b1cdbd2cSJim Jagielski destructor getting called. 63*b1cdbd2cSJim Jagielski 64*b1cdbd2cSJim Jagielski <li>The destructor of a delegator has to reset the delegator in 65*b1cdbd2cSJim Jagielski its aggregated objects by calling their method 66*b1cdbd2cSJim Jagielski <member>XAggregation::setDelegator()</member> with 67*b1cdbd2cSJim Jagielski <const>NULL</const> before it releases its reference to 68*b1cdbd2cSJim Jagielski its aggregated objects. 69*b1cdbd2cSJim Jagielski </ol> 70*b1cdbd2cSJim Jagielski 71*b1cdbd2cSJim Jagielski @deprecated 72*b1cdbd2cSJim Jagielski Aggregation will no longer be supported as a high-level concept of UNO. 73*b1cdbd2cSJim Jagielski You may still have the option to implement an UNO object consisting of 74*b1cdbd2cSJim Jagielski several single objects in your specific programming language, though this 75*b1cdbd2cSJim Jagielski depends on your programming language. 76*b1cdbd2cSJim Jagielski*/ 77*b1cdbd2cSJim Jagielskipublished interface XAggregation: com::sun::star::uno::XInterface 78*b1cdbd2cSJim Jagielski{ 79*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 80*b1cdbd2cSJim Jagielski /** sets the object to which all calls to the method 81*b1cdbd2cSJim Jagielski <member>XInterface::queryInterface()</member> 82*b1cdbd2cSJim Jagielski have to be forwarded. @ 83*b1cdbd2cSJim Jagielski 84*b1cdbd2cSJim Jagielski @param xDelegator 85*b1cdbd2cSJim Jagielski specifies the object which handles the calls to 86*b1cdbd2cSJim Jagielski <member>XInterface::queryInterface()</member>. 87*b1cdbd2cSJim Jagielski If <var>xDelegator</var> is <const>NULL</const>, the delegator is 88*b1cdbd2cSJim Jagielski removed and thus the object becomes its own delegator and has 89*b1cdbd2cSJim Jagielski to handle calls to the method 90*b1cdbd2cSJim Jagielski <member>XInterface::queryInterface()</member> 91*b1cdbd2cSJim Jagielski itself. 92*b1cdbd2cSJim Jagielski 93*b1cdbd2cSJim Jagielski @see XAggregation::queryAggregation 94*b1cdbd2cSJim Jagielski */ 95*b1cdbd2cSJim Jagielski void setDelegator( [in] com::sun::star::uno::XInterface pDelegator ); 96*b1cdbd2cSJim Jagielski 97*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 98*b1cdbd2cSJim Jagielski /** is similar to <member>XInterface::queryInterface()</member>, 99*b1cdbd2cSJim Jagielski but it is to be processed directly without being forwarded to the 100*b1cdbd2cSJim Jagielski delegator. @ 101*b1cdbd2cSJim Jagielski 102*b1cdbd2cSJim Jagielski <p>This method is only called from within an implementation of 103*b1cdbd2cSJim Jagielski <member>XInterface::queryInterface()</member> 104*b1cdbd2cSJim Jagielski or <member>XAggregation::queryAggregation()</member>. This method 105*b1cdbd2cSJim Jagielski is to be called by the delegator if it does not implement the 106*b1cdbd2cSJim Jagielski interface itself. An object which got aggregated cannot depend 107*b1cdbd2cSJim Jagielski on getting its own interface when it calls the method 108*b1cdbd2cSJim Jagielski <member>XInterface::queryInterface()</member>. 109*b1cdbd2cSJim Jagielski 110*b1cdbd2cSJim Jagielski @see XAggregation::setDelegator 111*b1cdbd2cSJim Jagielski */ 112*b1cdbd2cSJim Jagielski any queryAggregation( [in] type aType ); 113*b1cdbd2cSJim Jagielski 114*b1cdbd2cSJim Jagielski}; 115*b1cdbd2cSJim Jagielski 116*b1cdbd2cSJim Jagielski//============================================================================= 117*b1cdbd2cSJim Jagielski 118*b1cdbd2cSJim Jagielski}; }; }; }; 119*b1cdbd2cSJim Jagielski 120*b1cdbd2cSJim Jagielski#endif 121