offapi/com/sun/star/util/XAtomServer.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_util_XAtomServer_idl__
  20 #define __com_sun_star_util_XAtomServer_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/util/AtomDescription.idl>
  24 #include <com/sun/star/util/AtomClassRequest.idl>
  25
  26
  27 module com
  28 {
  29 module sun
  30 {
  31 module star
  32 {
  33 module util
  34 {
  35
  36 /** an interface to map between <i>string</i>s and <i>id</i>s
  37
  38    <p>a note on atoms:<br>
  39    Atoms are abbreviations for strings.
  40    When a string gets registered, it is assigned a numeric id
  41    so that said string can always be referred to by this id.
  42    This way strings have to be transported only once over remote connections.
  43    Valid ids are (in this implementation) non zero, signed 32 bit values.
  44    An atom of 0 means that the string in question is not registered</p>
  45
  46    <p>Additionally there is the abstraction of atom class:<br>
  47    Atoms are grouped into classes, so that an id can be assigned
  48    to multiple strings, depending on the class context. The main
  49    advantage of this is that atoms in one class may be kept
  50    to small numbers, so that bandwidth can be reduced by sending
  51    the atoms only as 16 bit values. Note that it is up to the user in this
  52    case to handle overflows.</p>
  53 */
  54
  55 published interface XAtomServer : com::sun::star::uno::XInterface
  56 {
  57     /** returns a whole atom class
  58
  59         @param atomClass
  60             which class to return
  61
  62         @returns
  63             the descriptions for all atoms of class <code>atomClass</code>
  64     */
  65     sequence< AtomDescription > getClass( [in] long atomClass );
  66     /** returns multiple atom classes
  67
  68         @param atomClasses
  69             which classes to return
  70
  71         @returns
  72             the descriptions for all atoms of the requested classes
  73     */
  74     sequence< sequence< AtomDescription > > getClasses( [in] sequence< long > atomClasses );
  75     /** returns the strings for an arbitrary amount of atoms of multiple classes
  76
  77         @param atoms
  78             describes which strings to return
  79
  80         @returns
  81             the strings for the requested atoms
  82     */
  83     sequence< string > getAtomDescriptions( [in] sequence< AtomClassRequest > atoms );
  84
  85     /** returns the atoms that have been registered to a class after an
  86         already known atom
  87
  88         <p>Hint to implementor: using ascending atoms is the easiest way
  89         to decide, which atoms are recent.</p>
  90
  91         @param atomClass
  92             the class in question
  93
  94         @param atom
  95             the last known atom
  96
  97         @returns
  98             all atom description that have been added to class
  99             <code>atomClass</code> after <code>atom</code>
 100     */
 101     sequence< AtomDescription > getRecentAtoms( [in] long atomClass, [in] long atom );
 102
 103     /** registers or searches for a string
 104
 105         @param atomClass
 106             the class of atoms in question
 107
 108         @param description
 109             the string in question
 110
 111         @param create
 112             if true a new atom will be created for an unknown string
 113             else the invalid atom (0) will be returned for an unknown string
 114
 115         @returns
 116             the atom for the string <code>description</code>
 117     */
 118     long getAtom( [in] long atomClass, [in] string description, [in] boolean create );
 119 };
 120
 121
 122 }; // module util
 123 }; // module star
 124 }; // module sun
 125 }; // module com
 126
 127
 128 #endif
 129
 130 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */