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

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