/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* This file incorporates work covered by the following license notice:
*
* 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 .
*/
#ifndef __com_sun_star_ucb_Content_idl__
#define __com_sun_star_ucb_Content_idl__
#include 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 occur 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,
com::sun::star::lang::XComponent::dispose() must
be called at the content. The implementation of this method must call
com::sun::star::lang::XEventListener::disposing()
on the registered listeners and release the appropriate object
references. At the other hand, the implementation of
XEventListener::disposing must release its appropriate references.
This interface is required.
*/
interface com::sun::star::lang::XComponent;
/** enables the caller to let the content execute commands.
It is strongly recommended that any implementation supports the
improved XCommandProcessor2 interface. 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. 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
com::sun::star::beans::PropertyValue passed as
command argument, and so on. The exceptions will never be passed to
an com::sun::star::task::InteractionHandler. Every element in the returned sequence is an any containing: If the value to set is equal to the current value, no exception must
be added to the returned sequence The OpenCommandArgument2 members must be
filled as follows: The OpenCommandArgument2 members must be
filled as follows: The exceution must be aborted by the implementation of this command
(by throwing a CommandAbortedException), if an
unsupported mode is requested. 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.
Creation of a new persistent content:
This mechanism should work for all transfer operations, but generally
it's less efficient than the transfer command. Exceptions:
Note that InteractiveLockingLockExpiredException might
be raised by any command that requires a previously obtained lock.
PropertyCommandArgument::Property
contains information about the property to be added.
PropertyCommandArgument::DefaultValue
may contain the default value for the property. Its type must
match the one specified in com::sun::star::beans::Property::Type.
Note that the dynamic properties must be kept persistent. The
service Store (UCB persistence service) may be used to
implement this. Important: The implementation must at least support
adding properties of the following basic data types:
Raises a ::com::sun::star::beans::PropertyExistException
if a property with the same name already exists;
::com::sun::star::beans::IllegalTypeException
if the property has an unsupported type;
::com::sun::star::lang::IllegalArgumentException
if the Name of the property is empty. Raises a ::com::sun::star::beans::UnknownPropertyException
if the property does not exist;
::com::sun::star::beans::NotRemoveableException
if the property is not removable. This property is always read-only. The ContentType should not be confused with the MIME
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". If the property value can be a non-empty sequence, the
Content must also support command "createNewContent". The value is a string containing three tokens, separated by ";"
(A semicolon): Each token may contain the following values: Where many existing Content 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.
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 Store (UCB persistence service) may be used to
implement this.
Important: The implementation of
com::sun::star::beans::XPropertyContainer::addProperty()
must at least support adding properties of the following basic data
types:
Commands
Mandatory commands
Command Name
Return Type
Parameters
Description
getCommandInfo
XCommandInfo
void
This command obtains an interface which allows to query
information on commands supported by a content.
getPropertySetInfo
com::sun::star::beans::XPropertySetInfo
void
This command obtains an interface which allows to query
information on properties supported by a content.
getPropertyValues
com::sun::star::sdbc::XRow
sequence< com::sun::star::beans::Property > aProps
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.
setPropertyValues
sequence< any >
sequence< com::sun::star::beans::PropertyValue > aValues
This command sets property values of the content.
Optional commands
Command Name
Return Type
Parameters
Description
open
XDynamicResultSet
OpenCommandArgument2 aOpenCommandArg
For folder objects, this command will return an
implementation of service DynamicResultSet.
The exceution must be aborted by the implementation of this command
(by throwing a CommandAbortedException), if an
unsupported mode is requested.
open
void
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.
createNewContent
XContent
ContentInfo contentinfo
This command creates a new non-persistent content of a given type.
Note: This command is part of the replacement for the deprecated
interface XContentCreator.
insert
void
InsertCommandArgument aInsertCommandArg
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
ContentEvent - ContentAction::INSERTED.
update
void
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
XContentEventListener::contentEvent().
synchronize
void
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
XContent::contentEvent().
close
void
void
This command closes an object.
delete
void
boolean bDeletePhysically
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 ContentEvent
- ContentAction::DELETED. Additionally, the contents
parent must notify a ContentEvent
- ContentAction::REMOVED
undelete
void
void
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.
search
XDynamicResultSet
SearchCommandArgument aSearchCommandArg
This command searches for subcontents of a content matching the
given search criteria. The command will return an implemenation
of service DynamicResultSet.
transfer
void
TransferInfo aTransferInfo
Important note: A client that wants to transfer data should
not execute this command, but it should execute the command
"globalTransfer" at the UniversalContentBroker.
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
InteractiveBadTransferURLException 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:
targetContent = target.execute( "createNewContent", type )
props = sourceContent.execute( "getPropertyValues", ... )
dataStream = sourceContent.execute( "open", ... )
targetContent.execute( "setPropertyValues", props )
targetContent.execute( "insert", dataStream )
sourceContent.execute( "delete", ... )
lock
void
void
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).
Exceptions:
unlock
void
void
This command removes a lock obtained by executing the command "lock"
from the resource.
addProperty
void
PropertyCommandArgument aCmdArg
Adds a new properties to the content.
Note: This command is new since Apache OpenOffice 4.0, LibreOffice 4.2 and replaces the deprecated interface method
com::sun::star::beans::XPropertyContainer::addProperty.
removeProperty
void
string PropertyName
Removes the properties from the content.
Note: This command is new since Apache OpenOffice 4.0, LibreOffice 4.2 and replaces the deprecated interface method
com::sun::star::beans::XPropertyContainer::removeProperty.
Properties
Mandatory properties
Name
Type
Description
ContentType
string
contains a unique type string for the content
( i.e. "application/vnd.sun.star.hierarchy-link" ).
IsFolder
boolean
indicates, whether a content can contain other contents.
IsDocument
boolean
indicates, whether a content is a document. This means,
the content can dump itself into a data sink.
Title
string
contains the title of an object (e.g. the subject of a message).
Optional properties
*/
interface com::sun::star::ucb::XCommandProcessor;
/** is an enhanced version of XCommandProcessor that has an
additional method for releasing command identifiers obtained via
XCommandProcessor::createCommandIdentifier() to avoid
resource leaks. For a detailed description of the problem refer to
XCommandProcessor2::releaseCommandIdentifier().
Name
Type
Description
AutoUpdateInterval
long
contains the interval for automatic updates of an object.
It is specified in seconds.
ConnectionLimit
short
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.)
ConnectionMode
short
contains the current connection mode for the object.
(see ConnectionMode)
CreatableContentsInfo
sequence ContentInfo
contains the types of Contents a Content object can create via
command "createNewContent".
Note: This property is part of the replacement for the deprecated
interface XContentCreator.
DateCreated
com::sun::star::util::DateTime
contains the date and time the object was created.
DateModified
com::sun::star::util::DateTime
contains the date and time the object was last modified.
DocumentCount
long
contains the count of documents of a folder.
DocumentCountMarked
long
contains the count of marked documents within a folder.
DocumentHeader
sequence< DocumentHeaderField >
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".
DocumentStoreMode
DocumentStoreMode
contains information about the way a folder stores the
contents of (remote) documents.
FolderCount
long
contains the count of subfolders of a folder.
FreeSpace
hyper
contains the free space left on a storage device. It is
specified in bytes.
HasDocuments
boolean
indicates whether a content has subcontents, which are documents.
HasFolders
boolean
indicates whether a content has subcontents, which are folders.
IsMarked
boolean
indicates whether a content is "marked".
IsRead
boolean
indicates whether a content has been "read".
IsReadOnly
boolean
indicates whether a content is read-only.
IsSubscribed
boolean
indicates whether a content is subscribed.
IsTimeLimitedStore
boolean
indicates whether the feature to store contents
depending on their age is active.
UpdateOnOpen
boolean
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.
Keywords
string
contains the keywords of a document (e.g. the value
of the "keywords" header field of a news article).
MediaType
string
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 ).
MessageBCC
string
contains the BCC (blind carbon copy) receiver(s) of a message.
MessageCC
string
contains the CC (carbon copy) receiver(s) of a message.
MessageFrom
string
contains (the address of) the sender of a message.
MessageId
string
contains the ID of a message.
MessageInReplyTo
string
contains the "In-Reply-To" field of a message.
MessageReplyTo
string
contains the "Reply-To" field of a message.
MessageTo
string
contains the recipient(s) of a message.
NewsGroups
string
contains the name(s) of the newsgroup(s) into which a message was posted.
Password
string
contains a password (e.g. needed to access a POP3-Server).
Priority
Priority
contains a priority (i.e. of a message).
References
string
contains the "References" field of a news article.
Rules
RuleSet
contains the rules set for a content.
SeenCount
long
contains the count of seen/read subcontents of a folder content.
ServerBase
string
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)
ServerName
string
contains a server name (e.g. The name of the server to use for
a POP3-Account).
ServerPort
short
contains a numeric server port.
Size
hyper
contains the size (usually in bytes) of an object.
SizeLimit
hyper
contains a size limit for an object. (e.g. One may specify the
maximum size of the HTTP-Cache)
SubscribedCount
long
contains the count of subscribed contents of a folder.
SynchronizePolicy
SynchronizePolicy
contains the policy to use when synchronizing two objects.
TargetFrames
string
contains information about the target frame to use when displaying
an object.
TargetURL
string
for contents that are links to other contents, contains the URL of
the target content
TimeLimitStore
short
contains the value to use if the property "IsTimeLimitedStore" is set.
UserName
string
contains a user name. (e.g. the user name needed to access a
POP3-Account)
VerificationMode
VerificationMode
describes a verification policy.
If a property with an unsupported type shall be added a com::sun::star::beans::IllegalTypeException must be raised. @deprecated
This interface is deprecated, because a ContentProvider might need a XCommandEnvironment to perform the tasks of adding and removing properties. New implementations should implement the respective commands "addProperty" and "removeProperty" instead. */ 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 com::sun::star::beans::XPropertyContainer. ) */ [optional] 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. */ [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. @deprecated
This interface is deprecated. Use property "CreatableContentsInfo" and command "createNewContent" instead. */ [optional] interface com::sun::star::ucb::XContentCreator; /** provides access to the parent content of this content.
The object returned by the implementation of the method com::sun::star::container::XChild::getParent() must implement the service Content. 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. */ [optional] interface com::sun::star::container::XChild; }; }; }; }; }; #endif /* vim:set shiftwidth=4 softtabstop=4 expandtab: */