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