path: root/offapi/com/sun/star/ucb/Content.idl

/*************************************************************************
 *
 *  $RCSfile: Content.idl,v $
 *
 *  $Revision: 1.1 $
 *
 *  last change: $Author: mi $ $Date: 2000-11-06 09:22:31 $
 *
 *  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_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.

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

    //-------------------------------------------------------------------------
    /** must be implemented to make it possible to resolve cyclic object
        references. 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,
        <method>XComponent::dispose</method> must be called at the content.
        The implementation of this method must call
        <method>XEventListener::disposing</method> on the registered
        listeners and release the appropriate object references. At the other
        hand, the implementation of <method>XEventListener::disposing</method>
        must release its appropriate references.

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

    //-------------------------------------------------------------------------
    /** enables the caller to let the content execute commands.
        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.

        This interface is required.

        =======================================================================
        Commands:
        =======================================================================

        [return_type]
            [command_name]
                [param_type_and_name]

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

        // This command obtains an interface which allows to query
        // information on commands supported by a content.
        com::sun::star::ucb::XCommandInfo
            getCommandInfo
                void

        // This command obtains an interface which allows to query
        // information on properties supported by a content.
        com::sun::star::beans::XPropertySetInfo
            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.
        com::sun::star::sdbc::XRow
            getPropertyValues
                sequence< com::sun::star::beans::Property >

        // This command sets property values of the content.
        // Note: The execution will not be aborted, if there are properties
        //       contained, that are unknown to the content!
        void
            setPropertyValues
                sequence< com::sun::star::beans::PropertyValue >

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

        // For folder objects, this command will return an implementation
        // of service com::sun::star::ucb::DynamicContentResultSet.
        //
        // The OpenCommandArgument2 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 CommandAbortedException ), if an unsupported open
        // mode is requested.
        //
        com::sun::star::ucb::XDynamicResultSet
            <B>open</B>
                com::sun::star::ucb::OpenCommandArgument2 aOpenCommandArg

        // For non-folder objects, the OpenCommandArgument2 struct will be
        // prefilled with a data sink object, which will be filled
        // with the content data.
        //
        // The OpenCommandArgument2 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 CommandAbortedException ), if an unsupported open
        // mode is requested.
        //
        void
            <B>open</B>
                com::sun::star::ucb::OpenCommandArgument2 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
        // <method>com::sun::star::ucb::XContent::contentEvent</method>.
        void
            <B>update</B>
                com::sun::star::ucb::OpenCommandArgument2 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
        // <method>com::sun::star::ucb::XContent::contentEvent</method>.
        void
            <B>synchronize</B>
                com::sun::star::ucb::OpenCommandArgument2 aOpenCommandArg

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

        // This command deletes an object. If TRUE is passes as parameter,
        // the object will be destroyed physically. Otherwise it will will
        // be put into trash can, if such a service is available and the
        // object to delete supports the command "undelete".
        // On successful completion of this command, the deleted content
        // must propagate its deletion by notifying a <type>ContentEvent</type>
        // - <type>ContentAction::DELETED</type>. Additionally, the contents
        // parent must notify a <type>ContentEvent</type>
        // - <type>ContentAction::REMOVED</type>
        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
        // <method>com::sun::star::ucb::XContentCreator::createNewContent</method>
        // 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 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> - <type>ContentAction::INSERTED</type>.
        //
        // (2) Additionally this command can be called at any time to overwrite
        // the data of an existing content.
        void
            <B>insert</B>
                com::sun::star::ucb::InsertCommandArgument

        // This command searches for subcontents of a content matching the
        // given search criteria. The command will return an implemenation
        // of service com::sun::star::ucb::DynamicContentResultSet.
        com::sun::star::ucb::XDynamicResultSet
            <B>search</B>
                com::sun::star::ucb::SearchCommandArgument aSearchCommandArg

        // 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. Source and target folder may be the same
        // when doing a move operation.
        //
        // Transfers without the transfer command are 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. Therefore,
        // a client that wants to transfer data should first try to execute
        // a transfer command at the target folder. If the excution fails,
        // the client must transfer the content using the
        // createNew-transferProps-insert sequence described above.
        void
            <B>transfer</B>
                com::sun::star::ucb::TransferInfo 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 com::sun::star::ucb::ConnectionMode
        short ConnectionMode

        // contains the date and time the object was created.
        com::sun::star::util::DateTime DateCreated

        // contains the date and time the object was last modified.
        com::sun::star::util::DateTime 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< com::sun::star::ucb::DocumentHeaderField > DocumentHeader

        // contains information about the way a folder stores the
        // contents of (remote) documents.
        com::sun::star::ucb::DocumentStoreMode 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).
        com::sun::star::ucb::Priority Priority

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

        // contains the rules set for a content.
        com::sun::star::ucb::RuleSet 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.
        com::sun::star::ucb::SynchronizePolicy 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.
        com::sun::star::ucb::VerificationMode VerificationMode

     */
    interface com::sun::star::ucb::XCommandProcessor;

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

        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. Note that the dynamic
        properties must be kept persistent. The service UCB persistence
        service <type>Store</type> may be used to implement this.

        It is recommended to implement this interface.
     */
    interface com::sun::star::beans::XPropertyContainer;

    //-------------------------------------------------------------------------
    /** can be used to notify properties removed from or added to the
        content's property set.
        This interface must be implemented, if the implementation can
        dynamically change it's property set ( e.g. because it implements
        the interface <type>XPropertyContainer</type>. )

        It is recommended to implement this interface.
     */
    interface com::sun::star::beans::XPropertySetInfoChangeNotifier;

    //-------------------------------------------------------------------------
    /** can be used to notify commands removed from or added to the
        content's command set.
        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 ).

        This interface is 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). A content is "new", if it
        does not physically exist before creating it using this interface.

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

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

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

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

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

}; }; }; };

#endif