/*************************************************************************
 *
 *  $RCSfile: Content.idl,v $
 *
 *  $Revision: 1.16.8.2 $
 *
 *  last change: $Author: mi $ $Date: 2003/01/21 17:51:33 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (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.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2000 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/

#ifndef __com_sun_star_ucb_Content_idl__
#define __com_sun_star_ucb_Content_idl__

#ifndef __com_sun_star_ucb_XContent_idl__
#include <com/sun/star/ucb/XContent.idl>
#endif

#ifndef __com_sun_star_ucb_XContent_idl__
#include <com/sun/star/ucb/XContent.idl>
#endif

#ifndef __com_sun_star_lang_XComponent_idl__
#include <com/sun/star/lang/XComponent.idl>
#endif

#ifndef __com_sun_star_ucb_XCommandProcessor_idl__
#include <com/sun/star/ucb/XCommandProcessor.idl>
#endif

#ifndef __com_sun_star_ucb_XCommandProcessor2_idl__
#include <com/sun/star/ucb/XCommandProcessor2.idl>
#endif

#ifndef __com_sun_star_ucb_XCommandInfoChangeNotifier_idl__
#include <com/sun/star/ucb/XCommandInfoChangeNotifier.idl>
#endif

#ifndef __com_sun_star_beans_XPropertyContainer_idl__
#include <com/sun/star/beans/XPropertyContainer.idl>
#endif

#ifndef __com_sun_star_beans_XPropertySetInfoChangeNotifier_idl__
#include <com/sun/star/beans/XPropertySetInfoChangeNotifier.idl>
#endif

#ifndef __com_sun_star_beans_XPropertiesChangeNotifier_idl__
#include <com/sun/star/beans/XPropertiesChangeNotifier.idl>
#endif

#ifndef __com_sun_star_ucb_XContentCreator_idl__
#include <com/sun/star/ucb/XContentCreator.idl>
#endif

#ifndef __com_sun_star_container_XChild_idl__
#include <com/sun/star/container/XChild.idl>
#endif

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

module com { module sun { module star { module ucb {

//=============================================================================
/** A <type>Content</type> is a service that provides access to data of a
	content provided by an implementation of the service
	<type>ContentProvider</type>.
*/
service Content
{
	//-------------------------------------------------------------------------
	/** provides access to the identitity and the type of the content and
		allows the registration of listeners for <type>ContentEvent</type>s.

		<p>This interface is required.
	 */
	interface com::sun::star::ucb::XContent;

	//-------------------------------------------------------------------------
	/** must be implemented to make it possible to resolve cyclic object
	    references.

		<p>Those references i.e. may occure if there are listeners
		registered at the content ( the content holds the listeners ) and
		the implementation of the listener interface holds a reference on
		the content. If the content shall be released,
		<member scope="com::sun::star::lang">XComponent::dispose</member> must
		be called at the content. The implementation of this method must call
		<member scope="com::sun::star::lang">XEventListener::disposing</member>
		on the registered listeners and release the appropriate object
		references. At the other hand, the implementation of
		XEventListener::disposing must release its appropriate references.

		<p>This interface is required.
	 */
	interface com::sun::star::lang::XComponent;

	//-------------------------------------------------------------------------
	/**	enables the caller to let the content execute commands.

        <p>It is strongly recommended that any implementation supports the
        improved <type>XCommandProcessor2</type> interface.</p>

		<p>Typical commands are "open", "delete", "getPropertyValues" and
		"setPropertyValues". Each content must support a set of standard
		commands and properties. Also there is a set of predefined optionally
		commands and properties. A content may define additional commands and
		properties. </p>

		<p>This interface is required. </p>

		<pre>
		=======================================================================
		Commands:
		=======================================================================

		[return type]
			[command name]
				[parameter type and name]

		-----------------------------------------------------------------------
		Requiered commands:
		-----------------------------------------------------------------------

		// This command obtains an interface which allows to query
		// information on commands supported by a content.
		<type>XCommandInfo</type>
			getCommandInfo
				void

		// This command obtains an interface which allows to query
		// information on properties supported by a content.
		<type scope="com::sun::star::beans">XPropertySetInfo</type>
			getPropertySetInfo
				void

		// This command obtains property values from the content.
		// Note: The execution will not be aborted, if there are properties
		//       requested, that are unknown to the content! The returned
		//       row object must contain a NULL value in the corresponding
		//       column instead.
		<type scope="com::sun::star::sdbc">XRow</type>
			getPropertyValues
				sequence&lt; <type scope="com::sun::star::beans">Property</type> &gt; aProps

		// This command sets property values of the content.
        // Note that setPropertyValues does not throw an exception in the case
        // that one or more of the requested property values cannot be set! The
        // implementation should set as much property values as possible. This
        // command returns a sequence< any > which has exactly the same number
        // of elements like the number of properties to set. Every sequence
        // element contains the status for a property. The first sequence
        // elements corresponds to the first element in the sequence of
        // <type scope="com::sun::star::beans">PropertyValue</type> passed as
        // command argument and so on. The exceptions will never be passed to
        // an Interaction Handler.
        //
        // An any containing:
        //
        // - No value indicates, that the property value was set successfully.
        // - <type scope="com::sun::star::beans">UnknownPropertyException</type>
        //   indicates, that the property is not known to the content
        //   implementation.
        // - <type scope="com::sun::star::beans">IllegalTypeException</type>
        //   indicates, that the data type of the property value is not
        //   acceptable.
        // - <type scope="com::sun::star::lang">IllegalAccessException</type>
        //   indicates, that the property is constant
        //   (<member scope="com::sun::star::beans">PropertyAttribute::READONLY</member>
        //   is set).
        // - <type scope="com::sun::star::lang">IllegalArgumentException</type>
        //   indicates, that the property value is not acceptable. For instance,
        //   setting an empty title may be illegal.
        // - Any other execption derived from <type scope="com::sun::star::uno">Exception</type>
        //   indicates, that the value was not set successfully. For example,
        //   this can be a <type>InteractiveAugmentedIOException</type>
        //   transporting the error code <member>IOErrorCode::ACCESS_DENIED</member>.
        //
        // If the value to set is equal to the current value, no exception must
        // be added to the returned sequence
        sequence&lt; any &gt;
			setPropertyValues
				sequence&lt; <type scope="com::sun::star::beans">PropertyValue</type> &gt; aValues

		-----------------------------------------------------------------------
		Optional commands:
		-----------------------------------------------------------------------

		// For folder objects, this command will return an implementation
		// of service <type>DynamicResultSet</type>.
		//
		// The <type>OpenCommandArgument2</type> members must be filled as follows:
		//
		// Mode         : ALL or FOLDERS or DOCUMENTS. The implementation
		//                of the open command MUST support all these modes!
		// Priority     : can be set, but implementation may ignore the value
		// Sink		   	: empty( ignored )
		// Properties   : The properties for that the result set shall
		//                contain the property values. The order of the
		//                sequence is the same as the order of result set
		//                columns. First element of sequence will be row
		//                number one, second will be row number two, ...
		// SortingInfo 	: contains sort criteria, if result set shall
		//                be sorted, otherwise it can be left empty.
		//
		// The exceution must be aborted by the implementation of this command
		// (by throwing a <type>CommandAbortedException</type>), if an
		// unsupported mode is requested.
		<type>XDynamicResultSet</type>
			<B>open</B>
				<type>OpenCommandArgument2</type> aOpenCommandArg

		// For non-folder objects, the <type>OpenCommandArgument2</type> struct
		// will be prefilled with a data sink object, which will be filled
		// with the content data.
		//
		// The <type>OpenCommandArgument2</type> members must be filled as follows:
		//
		// Mode         : DOCUMENT or DOCUMENT_SHARE_DENY_NONE or
		//                DOCUMENT_SHARE_DENY_WRITE. Support for DOCUMENT
 		//                is mandatory, all others are optional.
		// Priority     : can be set, but implementation may ignore the value
		// Sink		   	: a sink, where the implementation can put the
		//                document data into.
		// Properties   : empty ( ignored )
		// SortingInfo 	: empty ( ignored )
		//
		// The exceution must be aborted by the implementation of this command
		// (by throwing a <type>CommandAbortedException</type>), if an
		// unsupported mode is requested.
		void
			<B>open</B>
				<type>OpenCommandArgument2</type> aOpenCommandArg

		// This command triggers an update operation on a content. For example,
		// when "updating" a POP3-Inbox, the content for that box will get
		// and store all new objects on the appropriate server. The inserted
		// contents will be notified by calling
        // <member>XContentEventListener::contentEvent</member>.
		void
			<B>update</B>
				<type>OpenCommandArgument2</type> aOpenCommandArg

		// This command triggers a synchronization operation between locally
		// cached data and remote server's data. For example, when
		// "synchronizing" a POP3-Inbox the content for that box will get and
		// store all new objects and destroy all cached data for objects no
		// longer existing on the server. The inserted/deleted contents will
		// be notified by calling
		// <member>XContent::contentEvent</member>.
		void
			<B>synchronize</B>
				<type>OpenCommandArgument2</type> aOpenCommandArg

		// This command closes an object.
		void
			<B>close</B>
				void

		// This command deletes an object. If <TRUE/> is passed as parameter,
		// the object will be destroyed physically. Otherwise it will be put
		// into trash can, if such a service is available and the object to
		// be deleted supports the command "undelete".
		// On successful completion of this command, the deleted content
		// must propagate its deletion by notifying a <type>ContentEvent</type>
		// - <member>ContentAction::DELETED</member>. Additionally, the contents
		// parent must notify a <type>ContentEvent</type>
		// - <member>ContentAction::REMOVED</member>
		void
			<B>delete</B>
				boolean bDeletePhysically

		// This command restores an object previously deleted into trash. It
		// must be supported by objects which claim to be undeletable, but
		// should never be called directly.
		void
			<B>undelete</B>
				void

		// (1) This command inserts a new content. It commits the process of
		// creating a new content via calling another content's method
		// <member>XContentCreator::createNewContent</member>
		// The command is not called on the content which created the new
		// content, because the new object already knows where it is to be
		// inserted (i.e. Calling createNewContent with the content type for a
		// message on a News Group creates a content which internally belongs
		// to the Outbox. Calling "insert" on that message will result in
		// posting the article to the appropriate News Group). Not calling
		// "insert" for the new content, i.e. because the user cancels writing
		// a new message, simply discards the new object. No extra call to
		// "delete" is necessary.
		// On successful completion of this command, the parent of the inserted
		// content must propagate the change by notifying a
		// <type>ContentEvent</type> - <member>ContentAction::INSERTED</member>.
		//
		// (2) Additionally this command can be called at any time to overwrite
		// the data of an existing content.
		void
			<B>insert</B>
				<type>InsertCommandArgument</type> aInsertCommandArg

		// This command searches for subcontents of a content matching the
		// given search criteria. The command will return an implemenation
		// of service <type>DynamicResultSet</type>.
		<type>XDynamicResultSet</type>
			<B>search</B>
				<type>SearchCommandArgument</type> aSearchCommandArg

		// <b>Important note:</b> A client that wants to transfer data should
		// not execute this command, but it should execute the command
		// "globalTransfer" at the <type>UniversalContentBroker</type>.
		// This command is able to transfer all kind of content
		// supported by that UCB.
		//
		// This command transfers (copies/moves) an object from one location
		// to another. It must be executed at the folder content representing
		// the destination of the transfer operation. Note that the
		// implementation need not(!) be able to handle any type of contents.
		// Generally, there are good chances that a transfer of a content will
		// succeed, if source and target folder have the same URL scheme.
		// But there is no guaranty for that. For instance, moving a message
		// from a folder on IMAP server A to a folder on IMAP server B may
		// fail, because the transfer command can't be implemented efficiently
		// for this scenario, because it is not directly supported by the IMAP
		// protocol. On the other hand, moving a message from one folder to
		// another folder on the same IMAP server should work, because it can
		// be implemeted efficiently. If an implementation is not able to
		// handle a given source URL, it should indicate this by issuing a
		// <type>InteractiveBadTransferURLException</type> interaction request.
		// Source and target folder may be the same when doing a move operation.
		//
		// Transfers without the transfer command can be done as follows:
		//
		// 1) Create a new content at the target folder
		//    --> targetContent = target.XContentCreator::createNewContent(...)
		// 2) Transfer data from source to target content
		//    --> props = sourceContent.execute( "getPropertyValues", ... )
		//    --> dataStream = sourceContent.execute( "open", ... )
		//    --> targetContent.execute( "setPropertyValues", props )
		// 3) Insert ( commit ) the new content
		//    --> targetContent.execute( "insert", dataStream )
		// 4) For move operations only: destroy the source content
		//    sourceContent.execute( "delete", ... )
		//
		// This mechanism should work for all transfer operations, but generally
		// it's less efficient than the transfer command.
		void
			<B>transfer</B>
				<type>TransferInfo</type> aTransferInfo

		=======================================================================
		Properties:
		=======================================================================

		-----------------------------------------------------------------------
		Requiered properties:
		-----------------------------------------------------------------------

		// contains a unique(!) type string for the content ( i.e.
		// "application/vnd.sun.star.hierarchy-link" ). This property is always
		// read-only. It does not contain the media type ( MIME types ) of the
		// content. Media types may be provided through the optional property
		// "MediaType".
		// The value of this property should match the information on creatable
		// contents given by UCB contents that implement the interface
		// <type>XContentCreator</type>.
		string ContentType

		// indicates, whether a content can contain other contents.
		boolean	IsFolder

		// indicates, whether a content is a document. This means, the
		// content can dump itself into a data sink.
		boolean	IsDocument

		// contains the title of an object (e.g. the subject of a message).
		string Title;

		-----------------------------------------------------------------------
		Optional properties:
		-----------------------------------------------------------------------

		// contains the interval for automatic updates of an object.
		// It is specified in seconds.
		long AutoUpdateInterval

		// contains the maximum number of network connections
		// allowed for one (internet) protocol at a time. (e.g. The HTTP
		// cache can be configured to use a maximum for the number of
		// connections used for browsing.)
		short ConnectionLimit

		// contains the current connection mode for the object.
		// (see <type>ConnectionMode</type>)
		short ConnectionMode

		// contains the date and time the object was created.
		<type scope"com::sun::star::util">DateTime</type> DateCreated

		// contains the date and time the object was last modified.
		<type scope"com::sun::star::util">DateTime</type> DateModified

		// contains the count of documents of a folder.
		long DocumentCount;

		// contains the count of marked documents within a folder.
		long DocumentCountMarked

		// contains a sequence of documemt header fields (i.e. header
		// fields of a MIME-message, or the document info of an
		// office document ). For some standard header fields there
		// are predefined separate properties, like &quot;MessageTo&quot;.
		sequence&lt; <type>DocumentHeaderField</type> &gt; DocumentHeader

		// contains information about the way a folder stores the
		// contents of (remote) documents.
		<type>DocumentStoreMode</type> DocumentStoreMode

		// contains the count of subfolders of a folder.
		long FolderCount

		// contains the free space left on a storage device. It is
			specified in bytes.
		hyper FreeSpace

		// indicates whether a content has subcontents, which are documents.
		boolean HasDocuments

		// indicates whether a content has subcontents, which are folders.
		boolean HasFolders

		// indicates whether a content is &quot;marked&quot;.
		boolean IsMarked

		// indicates whether a content has been "read".
		boolean IsRead;

		// indicates whether a content is read-only.
		boolean IsReadOnly

		// indicates whether a content is subscribed.
		boolean IsSubscribed

		// indicates whether the feature to store contents depending on
		// their age is active.
		boolean IsTimeLimitedStore;

		// indicates whether (sub)contents shall be automatically updated
		// everytime a (folder) content is opened. This property may be
		// used to control whether a folder content should read data only
		// from local cache when it is opened, or whether it should connect
		// to a server to obtain latest data.
		boolean UpdateOnOpen

		// contains the keywords of a document (e.g. the value
		// of the &quot;keywords&quot; header field of a news article).
		string Keywords

		// contains the media type ( MIME type ) of a content. It is highly
		// recommended to support this property if the content's implementation
		// can obtain the media type natively from its data source ( i.e.
		// HTTP servers provide media types for all their documents ).
		string MediaType

		// contains the BCC (blind carbon copy) receiver(s) of a message.
		string MessageBCC

		// contains the CC (carbon copy) receiver(s) of a message.
		string MessageCC

		// contains (the address of) the sender of a message.
		string MessageFrom

		// contains the ID of a message.
		string MessageId

		// contains the &quot;In-Reply-To&quot; field of a message.
		string MessageInReplyTo

		// contains the &quot;Reply-To&quot; field of a message.
		string MessageReplyTo

		// contains the recipient(s) of a message.
		string MessageTo

		// contains the name(s) of the newsgroup(s) into which a message
		// was posted.
		string NewsGroups

		// contains a password (e.g. needed to access a POP3-Server).
		string Password

		// contains a priority (i.e. of a message).
		<type>Priority</type> Priority

		// contains the &quot;References&quot; field of a news article.
		string References

		// contains the rules set for a content.
		<type>RuleSet</type> Rules

		// contains the count of seen/read subcontents of a folder content.
		long SeenCount

		// contains the base directory to use on a server. (e.g. Setting
		// the server base of an FTP-Account to &quot;/pub/incoming&quot;
		// will result in showing contents from that directory and not from
		// server's root directory)
		string ServerBase

		// contains a server name (e.g. The name of the server to use for
		// a POP3-Account).
		string ServerName

		// contains a numeric server port.
		short ServerPort

		// contains the size (usually in bytes) of an object.
		hyper Size

		// contains a size limit for an object. (e.g. One may specify the
		// maximum size of the HTTP-Cache)
		hyper SizeLimit

		// contains the count of subscribed contents of a folder.
		long SubscribedCount

		// contains the policy to use when synchronizing two objects.
		<type>SynchronizePolicy</type> SynchronizePolicy

		// contains information about the target frame to use when displaying
		// an object.

		<p>The value is a string containing three tokens, separated by &quot;;&quot;
		(A semicolon):<br/>
		<dl>
		<dt>1st token
		</dt><dd>Behavior on &quot;select&quot; ( single click )
		</dd><dt>2nd token
		</dt><dd>Behavior on &quot;open&quot;   ( double click )
		</dd><dt>3rd token
		</dt><dd>Behavior on &quot;open in new task&quot; ( double click + CTRL key )
		</dd></dl>
		</p>
		<p>  Each token may contain the following values:<br/>
		<dl>
		<dt>&quot;_beamer&quot;
		</dt><dd>Show in &quot;Beamer&quot;
		</dd><dt>&quot;_top&quot;
		</dt><dd>Show in current frame (replaces old)
		</dd><dt>&quot;_blank&quot;
		</dt><dd>Show in new task
		</dd></dl>
		</p>

		string TargetFrames

		// for contents that are links to other contents, contains the URL of
		// the target content
		string TargetURL

		// contains the value to use if the property "IsTimeLimitedStore" is set.
		short TimeLimitStore;

		// contains a user name. (e.g. the user name needed to access a
		// POP3-Account)
		string UserName

		// describes a verification policy.
		<type>VerificationMode</type> VerificationMode
		</pre>
	 */
	interface com::sun::star::ucb::XCommandProcessor;

    //-------------------------------------------------------------------------
    /** is an enhanced version of <type>XCommandProcessor</type> that has an
        additional method for releasing command identifiers obtained via
        <member>XCommandProcessor::createCommandIdentifier</member> to avoid
        resource leaks. For a detailed description of the problem refer to
        <member>XCommandProcessor2::releaseCommandIdentifier</member>.

        <p>Where many existing <type>Content</type> implementations do not
        (yet), every new implementation should support this interface.
     */
    [optional] interface com::sun::star::ucb::XCommandProcessor2;

	//-------------------------------------------------------------------------
	/**	notifies changes of property values to listeners registered	for
	    those properties.

		<p>This interface is required.
	 */
	interface com::sun::star::beans::XPropertiesChangeNotifier;

	//-------------------------------------------------------------------------
	/**	can be used to add new properties to the content and to remove
		properties from the content dynamically.

	    <p>Note that the dynamic properties must be kept persistent. The
	    service <type>Store</type> (UCB persistence	service) may be used to
	    implement this.

		<p><b>Important:</b> The implementation of
		<method scope="com::sun::star::beans">XPropertyContainer::addProperty</method>
		must at least support adding properties of the following basic data
		types:

		<p>
		<ul>
		<li>boolean
		<li>char
		<li>byte
		<li>string
		<li>short
		<li>long
		<li>hyper
		<li>float
		<li>double
		</ul>

		<p>If a property with an unsupported type shall be added a
		<type scope="com::sun::star::beans">IllegalTypeException</type> must
		be raised.
	 */
	interface com::sun::star::beans::XPropertyContainer;

	//-------------------------------------------------------------------------
	/** can be used to notify properties removed from or added to the
	    content's property set.

		<p>This interface must be implemented, if the implementation can
		dynamically change it's property set ( e.g. because it implements
		the interface
		<type scope="com::sun::star::beans">XPropertyContainer</type>. )
	 */
    [optional] interface com::sun::star::beans::XPropertySetInfoChangeNotifier;

	//-------------------------------------------------------------------------
	/** can be used to notify commands removed from or added to the
	    content's command set.

		<p>This interface must be implemented, if the implementation can
		dynamically change it's command set ( e.g. because the set of
		available commands depends on the value of a property of the
		content ).

		<p>This interface is optional.
	 */
	[optional] interface com::sun::star::ucb::XCommandInfoChangeNotifier;

	//-------------------------------------------------------------------------
	/**	creates new contents (i.e. creates a new folder in another folder
		somewhere in the local file system).

	    <p>A content is "new", if it does not physically exist before creating
	    it using this interface.

		<p>This interface is optional. It should be implemented by contents
		which shall be able to create new objects.
	 */
	[optional] interface com::sun::star::ucb::XContentCreator;

	//-------------------------------------------------------------------------
	/**	provides access to the parent content of this content.

		<p>The object returned by the implementation of the method
		<member scope="com::sun::star::container">XChild::getParent()</member>
		must implement the service <type>Content</type>. If the content is a
		root object, an empty interface may be returned.

		<p>This interface must be implemented by a content which is a (logical)
		child of a content.
	 */
    [optional] interface com::sun::star::container::XChild;
};

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

}; }; }; };

#endif
