LibreOffice
LibreOffice 24.2 SDK API Reference
Exported Interfaces | List of all members
Content Service Referencepublished

A Content is a service that provides access to data of a content provided by an implementation of the service ContentProvider. More...

import"Content.idl";

Inheritance diagram for Content:
XChild XContentCreator XCommandInfoChangeNotifier XPropertySetInfoChangeNotifier XPropertyContainer XPropertiesChangeNotifier XCommandProcessor2 XCommandProcessor XComponent XContent DefinitionContent DocumentContainer DocumentDefinition Forms Reports

Exported Interfaces

interface com::sun::star::ucb::XContent
 provides access to the identity and the type of the content and allows the registration of listeners for ContentEvents. More...
 
interface com::sun::star::lang::XComponent
 must be implemented to make it possible to resolve cyclic object references. More...
 
interface com::sun::star::ucb::XCommandProcessor
 enables the caller to let the content execute commands. More...
 
interface com::sun::star::ucb::XCommandProcessor2
 is an enhanced version of XCommandProcessor that has an additional method for releasing command identifiers obtained via XCommandProcessor::createCommandIdentifier() to avoid resource leaks. More...
 
interface com::sun::star::beans::XPropertiesChangeNotifier
 notifies changes of property values to listeners registered for those properties. More...
 
interface com::sun::star::beans::XPropertyContainer
 can be used to add new properties to the content and to remove properties from the content dynamically. More...
 
interface com::sun::star::beans::XPropertySetInfoChangeNotifier
 can be used to notify properties removed from or added to the content's property set. More...
 
interface com::sun::star::ucb::XCommandInfoChangeNotifier
 can be used to notify commands removed from or added to the content's command set. More...
 
interface com::sun::star::ucb::XContentCreator
 creates new contents (i.e. More...
 
interface com::sun::star::container::XChild
 provides access to the parent content of this content. More...
 

Additional Inherited Members

- Public Member Functions inherited from XContent
com::sun::star::ucb::XContentIdentifier getIdentifier ()
 returns the identifier of the content. More...
 
string getContentType ()
 returns a type string, which is unique for that type of content (e.g. More...
 
void addContentEventListener ([in] com::sun::star::ucb::XContentEventListener Listener)
 adds a listener for content events. More...
 
void removeContentEventListener ([in] com::sun::star::ucb::XContentEventListener Listener)
 removes a listener for content events. More...
 
- Public Member Functions inherited from XInterface
any queryInterface ([in] type aType)
 queries for a new interface to an existing UNO object. More...
 
void acquire ()
 increases the reference counter by one. More...
 
void release ()
 decreases the reference counter by one. More...
 
- Public Member Functions inherited from XComponent
void dispose ()
 The owner of an object calls this method to explicitly free all resources kept by this object and thus break cyclic references. More...
 
void addEventListener ([in] XEventListener xListener)
 adds an event listener to the object. More...
 
void removeEventListener ([in] XEventListener aListener)
 removes an event listener from the listener list. More...
 
- Public Member Functions inherited from XCommandProcessor
long createCommandIdentifier ()
 creates a unique identifier for a command. More...
 
any execute ([in] Command aCommand, [in] long CommandId, [in] XCommandEnvironment Environment) raises ( com::sun::star::uno::Exception, CommandAbortedException )
 executes a command. More...
 
void abort ([in] long CommandId)
 ends the command associated with the given id. More...
 
- Public Member Functions inherited from XPropertiesChangeNotifier
void addPropertiesChangeListener ([in] sequence< string > PropertyNames, [in] com::sun::star::beans::XPropertiesChangeListener Listener)
 adds an XPropertiesChangeListener to the specified properties with the specified names. More...
 
void removePropertiesChangeListener ([in] sequence< string > PropertyNames, [in] com::sun::star::beans::XPropertiesChangeListener Listener)
 removes an XPropertiesChangeListener from the listener list. More...
 
- Public Member Functions inherited from XPropertyContainer
void addProperty ([in] string Name, [in] short Attributes, [in] any DefaultValue) raises ( com::sun::star::beans::PropertyExistException, com::sun::star::beans::IllegalTypeException, com::sun::star::lang::IllegalArgumentException )
 adds a property to the object. More...
 
void removeProperty ([in] string Name) raises ( com::sun::star::beans::UnknownPropertyException, com::sun::star::beans::NotRemoveableException )
 removes a property from the object. More...
 
- Protected Member Functions inherited from XCommandProcessor2
void releaseCommandIdentifier ([in] long CommandId)
 releases a command identifier obtained through XCommandProcessor::createCommandIdentifier() when it is no longer used. More...
 
- Protected Member Functions inherited from XPropertiesChangeNotifier
void addPropertiesChangeListener ([in] sequence< string > PropertyNames, [in] com::sun::star::beans::XPropertiesChangeListener Listener)
 adds an XPropertiesChangeListener to the specified properties with the specified names. More...
 
void removePropertiesChangeListener ([in] sequence< string > PropertyNames, [in] com::sun::star::beans::XPropertiesChangeListener Listener)
 removes an XPropertiesChangeListener from the listener list. More...
 
- Protected Member Functions inherited from XPropertyContainer
void addProperty ([in] string Name, [in] short Attributes, [in] any DefaultValue) raises ( com::sun::star::beans::PropertyExistException, com::sun::star::beans::IllegalTypeException, com::sun::star::lang::IllegalArgumentException )
 adds a property to the object. More...
 
void removeProperty ([in] string Name) raises ( com::sun::star::beans::UnknownPropertyException, com::sun::star::beans::NotRemoveableException )
 removes a property from the object. More...
 
- Protected Member Functions inherited from XPropertySetInfoChangeNotifier
void addPropertySetInfoChangeListener ([in] XPropertySetInfoChangeListener Listener)
 registers a listener for PropertySetInfoChangeEvents. More...
 
void removePropertySetInfoChangeListener ([in] XPropertySetInfoChangeListener Listener)
 removes a listener for PropertySetInfoChangeEvents. More...
 
- Protected Member Functions inherited from XCommandInfoChangeNotifier
void addCommandInfoChangeListener ([in] XCommandInfoChangeListener Listener)
 registers a listener for CommandInfoChangeEvents. More...
 
void removeCommandInfoChangeListener ([in] XCommandInfoChangeListener Listener)
 removes a listener for CommandInfoChangeEvents. More...
 
- Protected Member Functions inherited from XContentCreator
sequence< com::sun::star::ucb::ContentInfoqueryCreatableContentsInfo ()
 returns a list with information about the creatable contents. More...
 
com::sun::star::ucb::XContent createNewContent ([in] com::sun::star::ucb::ContentInfo Info)
 creates a new content of given type. More...
 
- Protected Member Functions inherited from XChild
com::sun::star::uno::XInterface getParent ()
 grants access to the object containing this content. More...
 
void setParent ([in] com::sun::star::uno::XInterface Parent) raises ( com::sun::star::lang::NoSupportException )
 sets the parent to this object. More...
 

Detailed Description

A Content is a service that provides access to data of a content provided by an implementation of the service ContentProvider.

Developers Guide
Universal Content Broker - Services and Interfaces

Exported Interfaces

◆ com::sun::star::beans::XPropertiesChangeNotifier

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

This interface is required.

◆ com::sun::star::beans::XPropertyContainer

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:

  • boolean
  • char
  • byte
  • string
  • short
  • long
  • hyper
  • float
  • double

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.

◆ com::sun::star::beans::XPropertySetInfoChangeNotifier

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. )

◆ com::sun::star::container::XChild

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.

◆ com::sun::star::lang::XComponent

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.

◆ com::sun::star::ucb::XCommandInfoChangeNotifier

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.

◆ com::sun::star::ucb::XCommandProcessor

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.

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.

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 a 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

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 OpenCommandArgument2 members must be filled as follows:

The execution 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.

The OpenCommandArgument2 members must be filled as follows:

The execution must be aborted by the implementation of this command (by throwing a CommandAbortedException), if an unsupported mode is requested.

createNewContent XContent ContentInfo contentinfo

This command creates a new non-persistent content of a given type.

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 XContentCreator.

Creation of a new persistent content:

  1. creatabletypes = obtain "CreatableContentsInfo" property from creator
  2. choose a suitable type from creatabletypes
  3. newObject = execute command "createNewContent(type)" at creator
  4. initialize the new object (i.e. newObject.Property1 = ...)
  5. execute command "insert" at new content. This command commits the data and makes the new content persistent.
insert void InsertCommandArgument aInsertCommandArg
  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 ContentEvent - ContentAction::INSERTED.
  2. Additionally this command can be called at any time to overwrite the data of an existing content.
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
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 implementation 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 implemented 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:

  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.

lock void void This command obtains an exclusive 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.

Exceptions:

Note that InteractiveLockingLockExpiredException might be raised by any command that requires a previously obtained lock.

addProperty void PropertyCommandArgument aCmdArg

Adds a new properties to the content.

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:

  • boolean
  • char
  • byte
  • string
  • short
  • long
  • hyper
  • float
  • double

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.

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.

Raises a com::sun::star::beans::UnknownPropertyException if the property does not exist; com::sun::star::beans::NotRemoveableException if the property is not removable.

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" ).

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".

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

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".

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 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 document 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 every time 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.

The value is a string containing three tokens, separated by ";" (A semicolon):

1st token
Behavior on "select" ( single click )
2nd token
Behavior on "open" ( double click )
3rd token
Behavior on "open in new task" ( double click + CTRL key )

Each token may contain the following values:

"_beamer"
Show in "Beamer"
"_top"
Show in current frame (replaces old)
"_blank"
Show in new task

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.

◆ com::sun::star::ucb::XCommandProcessor2

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().

Where many existing Content implementations do not (yet), every new implementation should support this interface.

◆ com::sun::star::ucb::XContent

provides access to the identity and the type of the content and allows the registration of listeners for ContentEvents.

This interface is required.

◆ com::sun::star::ucb::XContentCreator

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.


The documentation for this service was generated from the following file: