xref: /aoo42x/main/offapi/com/sun/star/packages/Package.idl (revision d1766043)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#ifndef __com_sun_star_packages_Package_idl__
#define __com_sun_star_packages_Package_idl__

#ifndef __com_sun_star_lang_XInitialization_idl__
#include <com/sun/star/lang/XInitialization.idl>
#endif

#ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__
#include <com/sun/star/container/XHierarchicalNameAccess.idl>
#endif

#ifndef __com_sun_star_lang_XSingleServiceFactory_idl__
#include <com/sun/star/lang/XSingleServiceFactory.idl>
#endif

#ifndef __com_sun_star_util_XChangesBatch_idl__
#include <com/sun/star/util/XChangesBatch.idl>
#endif


//=============================================================================

module com {  module sun {  module star {  module packages {

//=============================================================================
/**	The <type>Package</type> is a service that provides access to a set of
	files and folders contained within a Package. One instance of the
	Package service exists for each Package file to be manipulated.

	Each instance is created with an argument which specifies the URL of
	the Package file to which the user requires access. If the instance is
	created without arguments, it must be initialised with the
	<type scope="com::sun::star::lang">XInitialization</type> service methods
	before it is a valid instance of the service.
*/
published service Package
{
	/**
	A Package can be initialised with one of the following:

	1. A file URL referring to a package.
	2. An XInputStream referring to a package (it must also
	   support an XSeekable interface).
	3. An XStream referring to a package. The XInputStream must support
	   an XSeekable interface, and the XOutputStream must support an
	   XTruncate interface.

	It will throw a css::uno::Exception if initialised with bad data or
	if the package has an invalid format (for example, a corrupt central d
	irectory record if the file is a ZIP file).
	*/
	interface com::sun::star::lang::XInitialization;
	/**
	This interface is used to get access to any entry within the package
	For example:
		getByHierarchicalName ("folder/subfolder/file1.txt");
	This will return a PackageStream which refers to the specified stream.
	This is also used to get access to a particular folder within the
	Package. For example:
		getByHierarchicalName ("folder/subfolder/");
	This will return a PackageFolder which describes the contents of the specified
	folder.

	Calls to methods of XHierarchicalNameAccess must NOT have a leading slash.
	*/
	interface com::sun::star::container::XHierarchicalNameAccess;
	/**
	This interface is used to create new PackageStream or PackageFolder
	implementation objects for addition to the Package.

	createInstance - creates a new stream implementation object (when first
	created, the new object is not part of the Package). It must be added
	to the PackageFolder in which it will reside using the methods in the
	PackageFolder service.

	createInstanceWithArguments - This accepts one boolean value as an
	argument. If it set to true, a PackageFolder implementation is created,
	if it is set to false, a PackageStream implementation is created.

	Creating and inserting a new stream would be done as follows:

		1. xNewStream = package->createInstanceWithArguments( false );
		2. xDataStream = new MyStreamImpl(). (wherever the data comes from)
		3. xNewStream->setInputStream( xDataStream );
		4. parentFolder->insertByName( "image.png", xNewStream );

	Replacing an existing stream would be very similar, except that the
	call ->insertByName would be replaced by ->replaceByName.
	*/
	interface com::sun::star::lang::XSingleServiceFactory;
	/**
	This interface is used to commit any changes to the Package. A new
	Package file will be written with any new or changed streams/folders and
	omitting any PackageStream or PackageFolder that has been removed.
	*/
	interface com::sun::star::util::XChangesBatch;
};
}; }; }; };

#endif