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