offapi/com/sun/star/ucb/XContentIdentifierMapping.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XContentIdentifierMapping.idl,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_ucb_XContentIdentifierMapping_idl__
  31 #define __com_sun_star_ucb_XContentIdentifierMapping_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 //=============================================================================
  38
  39 module com { module sun { module star { module ucb {
  40
  41  published interface XContent;
  42  published interface XContentIdentifier;
  43
  44 //=============================================================================
  45 /** A mapping from a (source) set of <type>XContentIdentifier</type>s to
  46     another (target) set of XContentIdentifiers.
  47
  48     <p>For convenience and performance, mapping between the string
  49     representations     of source/target XContentIdentifiers, as well as mapping
  50     between <type>XContent</type>s identified by source/target
  51     XContentIdentifiers is also supported.
  52
  53     <p>This interface can be useful in cases where the identifieres (and
  54     associated contents) returned by the various methods of an
  55     <type>XContentAccess</type> need to be mapped to some other space of
  56     identifiers (and associated contents).
  57
  58     @see XContent
  59     @see XContentAccess
  60     @see XContentIdentifier
  61 */
  62
  63 published interface XContentIdentifierMapping: com::sun::star::uno::XInterface
  64 {
  65     //-------------------------------------------------------------------------
  66     /** Map the string representation of an <type>XContentIdentifier</type>.
  67
  68         @param Source  The string representation of an XContentIdentifier
  69         from the source set.
  70
  71         @returns  The string representation of the target set's
  72         XContentIdentifier corresponding to the source identifier.  The
  73         returned string may be empty if either Source was empty already, or if
  74         there's no applicable target to map to.
  75     */
  76     string mapContentIdentifierString([in] string Source);
  77
  78     //-------------------------------------------------------------------------
  79     /** Map an <type>XContentIdentifier</type>.
  80
  81         @param Source  An XContentIdentifier from the source set.
  82
  83         @returns  The target set's XContentIdentifier corresponding to the
  84         source identifier.  The returned XContentIdentifier may be null if
  85         either Source was null already, or if there's no applicable target to
  86         map to.
  87     */
  88     XContentIdentifier mapContentIdentifier([in] XContentIdentifier Source);
  89
  90     //-------------------------------------------------------------------------
  91     /** Map the <type>XContent</type> identified by an
  92         <type>XContentIdentifier</type>.
  93
  94         @param Source  The XContent identified by an XContentIdentifier from
  95         the source set.
  96
  97         @returns  The XContent identified by the target set's
  98         XContentIdentifier corresponding to the source identifier.  The
  99         returned XContent may be null if either Source was null already, or if
 100         there's no applicable target to map to.
 101     */
 102     XContent mapContent([in] XContent Source);
 103
 104     //-------------------------------------------------------------------------
 105     /** Map the content identifiers (or related data) contained in the columns
 106         of a <type scope="com::sun::star::sdbc">XRow</type>.
 107
 108         @param Value  On input, a sequence of anys corresponding to the columns
 109         of the XRow (the first column goes into the     zeroth position of the
 110         sequence, and so on).  On output, the same sequence, but with the
 111         entries mapped as necessary.  This is an inout parameter rather than a
 112         comination of in parameter and return value for performance reasons
 113         (assuming that in most cases most elements in the input sequence will
 114         be returned unmodified).
 115
 116         @returns  <TRUE/> if any of the columns contain data that (potentially)
 117         needs mapping (though maybe no mapping occured for the concrete input
 118         data of this call).  This information can be useful to decide whether,
 119         for another row, a call to this function is at all necessary.
 120     */
 121     boolean mapRow([inout] sequence< any > Value);
 122 };
 123
 124 //=============================================================================
 125
 126 }; }; }; };
 127
 128 #endif