offapi/com/sun/star/ucb/TransientDocumentsContentProvider.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: TransientDocumentsContentProvider.idl,v $
  10  * $Revision: 1.5 $
  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_TransientDocumentsContentProvider_idl__
  31 #define __com_sun_star_ucb_TransientDocumentsContentProvider_idl__
  32
  33 #ifndef __com_sun_star_ucb_XContentProvider_idl__
  34 #include <com/sun/star/ucb/XContentProvider.idl>
  35 #endif
  36
  37 //=============================================================================
  38
  39 module com { module sun { module star { module ucb {
  40
  41 //=============================================================================
  42 /** The Transient Documents Content Provider (TDCP) implements a
  43     <type>ContentProvider</type> for the <type>UniversalContentBroker</type>
  44     (UCB).
  45
  46     <p>It provides access to the hierachical structure of the documents that
  47     are active in a running OpenOffice.org process. As long as a document was
  48     not closed, the TDCP can access it. All documents that have been loaded -
  49     regardless of their persistent document format (sxw, doc, sxc, xls, ...)
  50     or that have been created  but not yet saved to any storage medium, are
  51     supported. The TDCP is not able to load any documents itself. This is
  52     exclusively done by the OpenOffice.org document handling framework. The
  53     document contents provided by the TDCP represent live data, which may
  54     differ from any persistent representation of the document, for instance,
  55     because the user modified the document after loading, but did not yet save
  56     it.
  57
  58     @see TransientDocumentsRootContent
  59     @see TransientDocumentsDocumentContent
  60     @see TransientDocumentsFolderContent
  61     @see TransientDocumentsStreamContent
  62
  63     @since OOo 2.0.0
  64 */
  65 service TransientDocumentsContentProvider
  66 {
  67     //-------------------------------------------------------------------------
  68     /** provides four different types of contents: Stream, Folder, Document and
  69         Root.
  70
  71         <p>
  72
  73         <b>TDCP Contents</b>
  74         <ol>
  75         <li>
  76         A TDCP Stream (<type>TransientDocumentsStreamContent</type>) is a
  77         content which represents a data stream of an Office document. It is
  78         contained in a TDCP Folder or TDCP Document. A TDCP Stream has no
  79         children.
  80         </li>
  81         <li>
  82         A TDCP Folder (<type>TransientDocumentsFolderContent</type>) is a
  83         container for other TDCP Folders and TDCP Streams. It may be contained
  84         in another TDCP Folder or in a TDCP Document.
  85         </li>
  86         <li>
  87         A TDCP Document (<type>TransientDocumentsDocumentContent</type>)
  88         represents the root folder of a transient document. It is a container
  89         for other TDCP Folders and TDCP Streams. It is always a child of the
  90         TDCP Root.
  91         </li>
  92         <li>
  93         There is at most one instance of a TDCP Root
  94         (<type>TransientDocumentsRootContent</type>) at a time. All other TDCP
  95         contents are children of this folder. The TDCP Root Folder can contain
  96         only TDCP Documents. It has the fixed URL "vnd.sun.star.tdoc:/".
  97         </li>
  98         </ol>
  99
 100         <p><b>URL Scheme for TDCP Contents</b>
 101
 102         <p>Each TDCP content has an identifier corresponding to the following
 103         scheme:
 104
 105         <ul>
 106         <li>
 107         tdcp-URL   = "vnd.sun.star.tdoc:" abs-path
 108         </li>
 109         <li>
 110         abs-path   = +( "/" segment )
 111         </li>
 112         <li>
 113         segment    = *( pchar )
 114         </li>
 115         <li>
 116         pchar      = unreserved | escaped | ":" | "@" | "&" | "=" | "+" | "$" | ","
 117         </li>
 118         <li>
 119         unreserved = alphanum | mark
 120         </li>
 121         <li>
 122         mark       = "-" | "_" | "." | "!" | "~" | "*" | "'" | "("  | ")"
 123         </li>
 124         <li>
 125         escaped    = "%" hex hex
 126         </li>
 127         </ul>
 128
 129         <p>Examples:
 130
 131         <ul>
 132         <li>
 133         vnd.sun.star.tdoc:/
 134         ( The TDCP Root  )
 135         </li>
 136         <li>
 137         vnd.sun.star.tdoc:/22
 138         ( The document with the id 22 )
 139         </li>
 140         <li>
 141         vnd.sun.star.tdoc:/22/
 142         ( The document with the id 22 )
 143         </li>
 144         <li>
 145         vnd.sun.star.tdoc:/42/folder/subfolder
 146         ( The folder/stream named subfolder contained in folder named folder,
 147         which is contained in the document with the id 42 )
 148         </li>
 149         </ul>
 150
 151         </p>
 152      */
 153     interface com::sun::star::ucb::XContentProvider;
 154
 155 };
 156
 157 //=============================================================================
 158
 159 }; }; }; };
 160
 161 #endif