offapi/com/sun/star/packages/Package.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_packages_Package_idl__
  28 #define __com_sun_star_packages_Package_idl__
  29
  30 #ifndef __com_sun_star_lang_XInitialization_idl__
  31 #include <com/sun/star/lang/XInitialization.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__
  35 #include <com/sun/star/container/XHierarchicalNameAccess.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_lang_XSingleServiceFactory_idl__
  39 #include <com/sun/star/lang/XSingleServiceFactory.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_util_XChangesBatch_idl__
  43 #include <com/sun/star/util/XChangesBatch.idl>
  44 #endif
  45
  46
  47 //=============================================================================
  48
  49 module com {  module sun {  module star {  module packages {
  50
  51 //=============================================================================
  52 /** The <type>Package</type> is a service that provides access to a set of
  53     files and folders contained within a Package. One instance of the
  54     Package service exists for each Package file to be manipulated.
  55
  56     Each instance is created with an argument which specifies the URL of
  57     the Package file to which the user requires access. If the instance is
  58     created without arguments, it must be initialised with the
  59     <type scope="com::sun::star::lang">XInitialization</type> service methods
  60     before it is a valid instance of the service.
  61 */
  62 published service Package
  63 {
  64     /**
  65     A Package can be initialised with one of the following:
  66
  67     1. A file URL referring to a package.
  68     2. An XInputStream referring to a package (it must also
  69        support an XSeekable interface).
  70     3. An XStream referring to a package. The XInputStream must support
  71        an XSeekable interface, and the XOutputStream must support an
  72        XTruncate interface.
  73
  74     It will throw a css::uno::Exception if initialised with bad data or
  75     if the package has an invalid format (for example, a corrupt central d
  76     irectory record if the file is a ZIP file).
  77     */
  78     interface com::sun::star::lang::XInitialization;
  79     /**
  80     This interface is used to get access to any entry within the package
  81     For example:
  82         getByHierarchicalName ("folder/subfolder/file1.txt");
  83     This will return a PackageStream which refers to the specified stream.
  84     This is also used to get access to a particular folder within the
  85     Package. For example:
  86         getByHierarchicalName ("folder/subfolder/");
  87     This will return a PackageFolder which describes the contents of the specified
  88     folder.
  89
  90     Calls to methods of XHierarchicalNameAccess must NOT have a leading slash.
  91     */
  92     interface com::sun::star::container::XHierarchicalNameAccess;
  93     /**
  94     This interface is used to create new PackageStream or PackageFolder
  95     implementation objects for addition to the Package.
  96
  97     createInstance - creates a new stream implementation object (when first
  98     created, the new object is not part of the Package). It must be added
  99     to the PackageFolder in which it will reside using the methods in the
 100     PackageFolder service.
 101
 102     createInstanceWithArguments - This accepts one boolean value as an
 103     argument. If it set to true, a PackageFolder implementation is created,
 104     if it is set to false, a PackageStream implementation is created.
 105
 106     Creating and inserting a new stream would be done as follows:
 107
 108         1. xNewStream = package->createInstanceWithArguments( false );
 109         2. xDataStream = new MyStreamImpl(). (wherever the data comes from)
 110         3. xNewStream->setInputStream( xDataStream );
 111         4. parentFolder->insertByName( "image.png", xNewStream );
 112
 113     Replacing an existing stream would be very similar, except that the
 114     call ->insertByName would be replaced by ->replaceByName.
 115     */
 116     interface com::sun::star::lang::XSingleServiceFactory;
 117     /**
 118     This interface is used to commit any changes to the Package. A new
 119     Package file will be written with any new or changed streams/folders and
 120     omitting any PackageStream or PackageFolder that has been removed.
 121     */
 122     interface com::sun::star::util::XChangesBatch;
 123 };
 124 }; }; }; };
 125
 126 #endif