diff options
Diffstat (limited to 'offapi/com/sun/star/ucb/Content.idl')
| -rw-r--r-- | offapi/com/sun/star/ucb/Content.idl | 756 |
1 files changed, 756 insertions, 0 deletions
diff --git a/offapi/com/sun/star/ucb/Content.idl b/offapi/com/sun/star/ucb/Content.idl new file mode 100644 index 000000000000..85923c65fe15 --- /dev/null +++ b/offapi/com/sun/star/ucb/Content.idl @@ -0,0 +1,756 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org 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 version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#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>. +*/ +published 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] + + ----------------------------------------------------------------------- + Mandatory 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< <type scope="com::sun::star::beans">Property</type> > 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< any > + setPropertyValues + sequence< <type scope="com::sun::star::beans">PropertyValue</type> > 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 executing the command "createNewContent" + // and initializing it via setting properties, afterwards. + // 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.execute( "createNewContent", type ) + // 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 + + // This command obtains an exlusive write lock for the resource. The + // lock is active until command "unlock" is executed or the OOo + // session that obtained the lock ends or until the lock is released by + // a third party (e.g. a system administrator). + void + <B>lock</B> + void + Exceptions: <type>InteractiveLockingLockedException</type> + <type>InteractiveLockingLockExpiredException</type> + + // This command removes a lock obtained by executing the command "lock" + // from the resource. + void + <B>unlock</B> + void + Exceptions: <type>InteractiveLockingNotLockedException</type> + <type>InteractiveLockingLockExpiredException</type> + + // Note that <type>InteractiveLockingLockExpiredException</type> might + // be raised by any command that requires a previously obtained lock. + + // This command creates a new non-persistent content of a given type. + // + // <p>Creation of a new (persistent) content: + // <ol> + // <li>creatabletypes = obtain "CreatableContentsInfo" property<br> + // from creator + // <li>choose a suitable type from creatabletypes + // <li>newObject = execute command "createNewContent(type)" at<br> + // creator + // <li>initialize the new object (i.e. newObject.Property1 = ...) + // <li>execute command "insert" at new content. This command + // commits the data and makes the new content persistent. + // </ol> + // + // This command must be supported by every Content that supports the + // property "CreatableContentsInfo" if the returned property value + // contains a non-empty sequence of creatable types. + // + // Note: This command is part of the replacement for the deprecated + // interface <type>XContentCreator</type>. + <type>XContent</type> > + <B>createNewContent</B> + <type>ContentInfo<type> contentinfo + + ======================================================================= + Properties: + ======================================================================= + + ----------------------------------------------------------------------- + Mandatory 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 property + // "CreatableContentsInfo". + 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 "MessageTo". + sequence< <type>DocumentHeaderField</type> > 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 "marked". + 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 "keywords" 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 "In-Reply-To" field of a message. + string MessageInReplyTo + + // contains the "Reply-To" 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 "References" 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 "/pub/incoming" + // 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 ";" + (A semicolon):<br/> + <dl> + <dt>1st token + </dt><dd>Behavior on "select" ( single click ) + </dd><dt>2nd token + </dt><dd>Behavior on "open" ( double click ) + </dd><dt>3rd token + </dt><dd>Behavior on "open in new task" ( double click + CTRL key ) + </dd></dl> + </p> + <p> Each token may contain the following values:<br/> + <dl> + <dt>"_beamer" + </dt><dd>Show in "Beamer" + </dd><dt>"_top" + </dt><dd>Show in current frame (replaces old) + </dd><dt>"_blank" + </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 + + // contains the types of Contents a Content object can create via + // command "createNewContent". + // + // If the property value can be a non-empty sequence, the Content must + // also support command "createNewContent". + // + // Note: This property is part of the replacement for the deprecated + // interface <type>XContentCreator</type>. + sequence <type>ContentInfo</type> CreatableContentsInfo + + </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. + + @deprecated + + <p>This interface is <b>deprecated</b>. Use property + "CreatableContentsInfo" and command "createNewContent" instead. + */ + [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 |