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_XInterface_idl__ 24*b1cdbd2cSJim Jagielski#define __com_sun_star_uno_XInterface_idl__ 25*b1cdbd2cSJim Jagielski 26*b1cdbd2cSJim Jagielski//============================================================================= 27*b1cdbd2cSJim Jagielski 28*b1cdbd2cSJim Jagielski module com { module sun { module star { module uno { 29*b1cdbd2cSJim Jagielski 30*b1cdbd2cSJim Jagielski//============================================================================= 31*b1cdbd2cSJim Jagielski 32*b1cdbd2cSJim Jagielski// DocMerge from xml: interface com::sun::star::uno::XInterface 33*b1cdbd2cSJim Jagielski/** base interface of all UNO interfaces 34*b1cdbd2cSJim Jagielski 35*b1cdbd2cSJim Jagielski <p> It provides lifetime control by reference counting and the 36*b1cdbd2cSJim Jagielski possibility of querying for other 37*b1cdbd2cSJim Jagielski interfaces of the same logical object. 38*b1cdbd2cSJim Jagielski 39*b1cdbd2cSJim Jagielski 40*b1cdbd2cSJim Jagielski <p> 41*b1cdbd2cSJim Jagielski "Logical Object" in this case means that the 42*b1cdbd2cSJim Jagielski interfaces actually can be supported by internal (e.g. aggregated) physical objects.</p> 43*b1cdbd2cSJim Jagielski 44*b1cdbd2cSJim Jagielski <p> Deriving from this interface is mandatory for all UNO interfaces. 45*b1cdbd2cSJim Jagielski <p> Each language binding (Java, C++, StarBasic, Python, ... ) may 46*b1cdbd2cSJim Jagielski provide a different mapping of this interface, please look into the language 47*b1cdbd2cSJim Jagielski dependent documention. 48*b1cdbd2cSJim Jagielski 49*b1cdbd2cSJim Jagielski <p> The UNO object does not export the state of the reference count (acquire() and 50*b1cdbd2cSJim Jagielski release() do not have return values). In general, also the UNO object itself 51*b1cdbd2cSJim Jagielski should not make any assumption on the concrete value of the reference count 52*b1cdbd2cSJim Jagielski (except on the transition from one to zero ). 53*b1cdbd2cSJim Jagielski 54*b1cdbd2cSJim Jagielski */ 55*b1cdbd2cSJim Jagielskipublished interface XInterface 56*b1cdbd2cSJim Jagielski{ 57*b1cdbd2cSJim Jagielski /** queries for a new interface to an existing UNO object. 58*b1cdbd2cSJim Jagielski <p> 59*b1cdbd2cSJim Jagielski The queryInterface() method is the entry point to obtain other interfaces which 60*b1cdbd2cSJim Jagielski are exported by the object. The caller asks the implementation of the object, 61*b1cdbd2cSJim Jagielski if it supports the interface specified by the type argument. The call may either 62*b1cdbd2cSJim Jagielski return with a interface reference of the requested type or with a void any. 63*b1cdbd2cSJim Jagielski 64*b1cdbd2cSJim Jagielski <p> 65*b1cdbd2cSJim Jagielski There are certain specifications, a queryInterface() implementation must not violate. 66*b1cdbd2cSJim Jagielski <p> 67*b1cdbd2cSJim Jagielski 1) If queryInterface on a specific object has once returned a valid interface reference 68*b1cdbd2cSJim Jagielski for a given type, it must return a valid reference for any successive queryInterface 69*b1cdbd2cSJim Jagielski calls on this object for the same type. 70*b1cdbd2cSJim Jagielski <p> 71*b1cdbd2cSJim Jagielski 2) If queryInterface on a specific object has once returned a null reference 72*b1cdbd2cSJim Jagielski for a given type, it must always return a null reference for the same type. 73*b1cdbd2cSJim Jagielski <p> 74*b1cdbd2cSJim Jagielski 3) If queryInterface on a reference A returns reference B, queryInterface on 75*b1cdbd2cSJim Jagielski B for Type A must return interface reference A or calls made on the returned 76*b1cdbd2cSJim Jagielski reference must be equivalent to calls made on reference A. 77*b1cdbd2cSJim Jagielski <p> 78*b1cdbd2cSJim Jagielski 4) If queryInterface on a reference A returns reference B, queryInterface on 79*b1cdbd2cSJim Jagielski A and B for XInterface must return the same interface reference (object identity). 80*b1cdbd2cSJim Jagielski 81*b1cdbd2cSJim Jagielski <p> The reason for the strong specification is, that a Uno Runtime Environment (URE) 82*b1cdbd2cSJim Jagielski may choose to cache queryInterface() calls. 83*b1cdbd2cSJim Jagielski <p> As mentioned above, certain language bindings may map this function differently also 84*b1cdbd2cSJim Jagielski with different specifications, please visit the language dependent specification for it. 85*b1cdbd2cSJim Jagielski The current C++ binding sticks to the specification state 86*b1cdbd2cSJim Jagielski <p> 87*b1cdbd2cSJim Jagielski The rules mentioned above are basically identical to the rules of QueryInterface in MS COM. 88*b1cdbd2cSJim Jagielski 89*b1cdbd2cSJim Jagielski @param aType a UNO interface type, for which an object reference shall be obtained. 90*b1cdbd2cSJim Jagielski @return an interface reference in case the requested interface is supported by the object, 91*b1cdbd2cSJim Jagielski a void any otherwise. 92*b1cdbd2cSJim Jagielski */ 93*b1cdbd2cSJim Jagielski any queryInterface( [in] type aType ); 94*b1cdbd2cSJim Jagielski 95*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 96*b1cdbd2cSJim Jagielski /** increases the reference counter by one. 97*b1cdbd2cSJim Jagielski 98*b1cdbd2cSJim Jagielski <p>When you have called acquire() on the 99*b1cdbd2cSJim Jagielski UNO object, it is often said, that you have a reference or a hard reference 100*b1cdbd2cSJim Jagielski to the object. 101*b1cdbd2cSJim Jagielski 102*b1cdbd2cSJim Jagielski <p> 103*b1cdbd2cSJim Jagielski It is only allowed to invoke a method on an UNO object, when you keep 104*b1cdbd2cSJim Jagielski a hard reference to it. 105*b1cdbd2cSJim Jagielski 106*b1cdbd2cSJim Jagielski <p> Every call to acquire must be followed by a corresponding call to release 107*b1cdbd2cSJim Jagielski some time later, which may eventually lead to the destruction of the object. 108*b1cdbd2cSJim Jagielski */ 109*b1cdbd2cSJim Jagielski [oneway] void acquire(); 110*b1cdbd2cSJim Jagielski 111*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 112*b1cdbd2cSJim Jagielski 113*b1cdbd2cSJim Jagielski // DocMerge from xml: method com::sun::star::uno::XInterface::release 114*b1cdbd2cSJim Jagielski /** decreases the reference counter by one. 115*b1cdbd2cSJim Jagielski <p>When the reference counter reaches 0, the object gets deleted.</p> 116*b1cdbd2cSJim Jagielski <p>Calling release() on the object is often called releasing 117*b1cdbd2cSJim Jagielski or clearing the reference to an object. 118*b1cdbd2cSJim Jagielski */ 119*b1cdbd2cSJim Jagielski [oneway] void release(); 120*b1cdbd2cSJim Jagielski 121*b1cdbd2cSJim Jagielski}; 122*b1cdbd2cSJim Jagielski 123*b1cdbd2cSJim Jagielski//============================================================================= 124*b1cdbd2cSJim Jagielski 125*b1cdbd2cSJim Jagielski}; }; }; }; 126*b1cdbd2cSJim Jagielski 127*b1cdbd2cSJim Jagielski/*============================================================================= 128*b1cdbd2cSJim Jagielski 129*b1cdbd2cSJim Jagielski=============================================================================*/ 130*b1cdbd2cSJim Jagielski#endif 131