xref: /trunk/main/offapi/com/sun/star/packages/Package.idl (revision d1766043)
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