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