1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23#ifndef __com_sun_star_packages_Package_idl__ 24#define __com_sun_star_packages_Package_idl__ 25 26#ifndef __com_sun_star_lang_XInitialization_idl__ 27#include <com/sun/star/lang/XInitialization.idl> 28#endif 29 30#ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__ 31#include <com/sun/star/container/XHierarchicalNameAccess.idl> 32#endif 33 34#ifndef __com_sun_star_lang_XSingleServiceFactory_idl__ 35#include <com/sun/star/lang/XSingleServiceFactory.idl> 36#endif 37 38#ifndef __com_sun_star_util_XChangesBatch_idl__ 39#include <com/sun/star/util/XChangesBatch.idl> 40#endif 41 42 43//============================================================================= 44 45module com { module sun { module star { module packages { 46 47//============================================================================= 48/** The <type>Package</type> is a service that provides access to a set of 49 files and folders contained within a Package. One instance of the 50 Package service exists for each Package file to be manipulated. 51 52 Each instance is created with an argument which specifies the URL of 53 the Package file to which the user requires access. If the instance is 54 created without arguments, it must be initialised with the 55 <type scope="com::sun::star::lang">XInitialization</type> service methods 56 before it is a valid instance of the service. 57*/ 58published service Package 59{ 60 /** 61 A Package can be initialised with one of the following: 62 63 1. A file URL referring to a package. 64 2. An XInputStream referring to a package (it must also 65 support an XSeekable interface). 66 3. An XStream referring to a package. The XInputStream must support 67 an XSeekable interface, and the XOutputStream must support an 68 XTruncate interface. 69 70 It will throw a css::uno::Exception if initialised with bad data or 71 if the package has an invalid format (for example, a corrupt central d 72 irectory record if the file is a ZIP file). 73 */ 74 interface com::sun::star::lang::XInitialization; 75 /** 76 This interface is used to get access to any entry within the package 77 For example: 78 getByHierarchicalName ("folder/subfolder/file1.txt"); 79 This will return a PackageStream which refers to the specified stream. 80 This is also used to get access to a particular folder within the 81 Package. For example: 82 getByHierarchicalName ("folder/subfolder/"); 83 This will return a PackageFolder which describes the contents of the specified 84 folder. 85 86 Calls to methods of XHierarchicalNameAccess must NOT have a leading slash. 87 */ 88 interface com::sun::star::container::XHierarchicalNameAccess; 89 /** 90 This interface is used to create new PackageStream or PackageFolder 91 implementation objects for addition to the Package. 92 93 createInstance - creates a new stream implementation object (when first 94 created, the new object is not part of the Package). It must be added 95 to the PackageFolder in which it will reside using the methods in the 96 PackageFolder service. 97 98 createInstanceWithArguments - This accepts one boolean value as an 99 argument. If it set to true, a PackageFolder implementation is created, 100 if it is set to false, a PackageStream implementation is created. 101 102 Creating and inserting a new stream would be done as follows: 103 104 1. xNewStream = package->createInstanceWithArguments( false ); 105 2. xDataStream = new MyStreamImpl(). (wherever the data comes from) 106 3. xNewStream->setInputStream( xDataStream ); 107 4. parentFolder->insertByName( "image.png", xNewStream ); 108 109 Replacing an existing stream would be very similar, except that the 110 call ->insertByName would be replaced by ->replaceByName. 111 */ 112 interface com::sun::star::lang::XSingleServiceFactory; 113 /** 114 This interface is used to commit any changes to the Package. A new 115 Package file will be written with any new or changed streams/folders and 116 omitting any PackageStream or PackageFolder that has been removed. 117 */ 118 interface com::sun::star::util::XChangesBatch; 119}; 120}; }; }; }; 121 122#endif 123
