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:
=======================================================================
[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.
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 > 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
// ::com::sun::star::beans::PropertyValue 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.
// - ::com::sun::star::beans::UnknownPropertyException
// indicates, that the property is not known to the content
// implementation.
// - ::com::sun::star::beans::IllegalTypeException
// indicates, that the data type of the property value is not
// acceptable.
// - ::com::sun::star::lang::IllegalAccessException
// indicates, that the property is constant
// (::com::sun::star::beans::PropertyAttribute::READONLY
// is set).
// - ::com::sun::star::lang::IllegalArgumentException
// indicates, that the property value is not acceptable. For instance,
// setting an empty title may be illegal.
// - Any other execption derived from ::com::sun::star::uno::Exception
// indicates, that the value was not set successfully. For example,
// this can be a InteractiveAugmentedIOException
// transporting the error code IOErrorCode::ACCESS_DENIED.
//
// If the value to set is equal to the current value, no exception must
// be added to the returned sequence
sequence< any >
setPropertyValues
sequence< ::com::sun::star::beans::PropertyValue > aValues
-----------------------------------------------------------------------
Optional commands:
-----------------------------------------------------------------------
// For folder objects, this command will return an implementation
// of service DynamicResultSet.
//
// 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 mode is requested.
XDynamicResultSet
open
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 mode is requested.
void
open
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.
void
update
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.
void
synchronize
OpenCommandArgument2 aOpenCommandArg
// This command closes an object.
void
close
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 ContentEvent
// - ContentAction::DELETED. Additionally, the contents
// parent must notify a ContentEvent
// - ContentAction::REMOVED
void
delete
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
undelete
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
// ContentEvent - ContentAction::INSERTED.
//
// (2) Additionally this command can be called at any time to overwrite
// the data of an existing content.
void
insert
InsertCommandArgument aInsertCommandArg
// This command searches for subcontents of a content matching the
// given search criteria. The command will return an implemenation
// of service DynamicResultSet.
XDynamicResultSet
search
SearchCommandArgument aSearchCommandArg
// 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:
//
// 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
transfer
TransferInfo 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
lock
void
Exceptions: InteractiveLockingLockedException
InteractiveLockingLockExpiredException
// This command removes a lock obtained by executing the command "lock"
// from the resource.
void
unlock
void
Exceptions: InteractiveLockingNotLockedException
InteractiveLockingLockExpiredException
// Note that InteractiveLockingLockExpiredException might
// be raised by any command that requires a previously obtained lock.
// This command creates a new non-persistent content of a given type.
//
// Creation of a new (persistent) content:
//
// - creatabletypes = obtain "CreatableContentsInfo" property
// from creator
// - choose a suitable type from creatabletypes
//
- newObject = execute command "createNewContent(type)" at
// creator
// - initialize the new object (i.e. newObject.Property1 = ...)
//
- execute command "insert" at new content. This command
// commits the data and makes the new content persistent.
//
//
// 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.
XContent >
createNewContent
=======================================================================
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 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 "MessageTo".
sequence< DocumentHeaderField > DocumentHeader
// contains information about the way a folder stores the
// contents of (remote) documents.
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 "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).
Priority Priority
// contains the "References" field of a news article.
string References
// contains the rules set for a content.
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 "/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.
SynchronizePolicy SynchronizePolicy
// 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
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.
VerificationMode 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 XContentCreator.
sequence ContentInfo CreatableContentsInfo