Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.4 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: embed ::

interface XStorage
Base Interfaces
XStorage
┣ ::com::sun::star::container::XNameAccess
┃ ┗ ::com::sun::star::container::XElementAccess
┗ ::com::sun::star::lang::XComponent

::com::sun::star::container::XNameAccess
Description
allows to get list of child elements and to check if an element with a specified name exists in a storage.

It is also possible to use this interface to get read access to a child element by XNameAccess::getByName call. But the recommended way is to use XStorage interface for this purpose.

::com::sun::star::lang::XComponent
Description
allows to controll and track lifetime of the storage.

In case a storage is disposed any call to it's methods should result in ::com::sun::star::lang::DisposedException.

Description
This interface represents main storage functionality.

Methods' Summary
copyToStorage allows to copy current storage to another one  
openStreamElement allows to get access to a child stream of the storage.  
openEncryptedStreamElement allows to get access to a child encrypted stream with password.  
openStorageElement allows to get access to a child storage.  
cloneStreamElement allows to get readonly copy of a child stream of the storage.  
cloneEncryptedStreamElement allows to get readonly copy of a child encrypted stream with password.  
copyLastCommitTo allows to get copy of this storage at the state of it's last commit.  
copyStorageElementLastCommitTo allows to get copy of a child storage at the state of it's last commit.  
isStreamElement allows to check if an element is a child stream with specified name.  
isStorageElement allows to check if an element is a child storage with specified name.  
removeElement removes an element from a storage.  
renameElement renames an element in a storage.  
copyElementTo allows to copy an entry from one storage to another.  
moveElementTo allows to move an entry from one storage to another.  
Methods' Details
copyToStorage
void
copyToStorage( [in] XStorage  xDest )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to copy current storage to another one

The destination storage contents are overwritten. After the successful copying the target storage is automatically commited if it implements transacted access.

Parameter xDest
a destination storage this storage must be copied to.
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException an illegal argument is provided
Throws
::com::sun::star::io::IOException in case of io errors during copying
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exception acquired during copying
openStreamElement
::com::sun::star::io::XStream
openStreamElement( [in] string  sStreamName,
[in] long  nOpenMode )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::packages::WrongPasswordException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get access to a child stream of the storage.

In case the stream is open in readonly mode the XStream::getOutputStream method will return an empty reference.

Parameter sStreamName
the name of the substream that should be open
Parameter nOpenMode
a mode the stream should be open in, can be a combination of ElementModes values
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::packages::WrongPasswordException the provided password is wrong
Throws
::com::sun::star::io::IOException in case of io errors during stream opening
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
openEncryptedStreamElement
::com::sun::star::io::XStream
openEncryptedStreamElement( [in] string  sStreamName,
[in] long  nOpenMode,
[in] string  sPassword )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::packages::NoEncryptionException,
::com::sun::star::packages::WrongPasswordException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get access to a child encrypted stream with password.

If storage does not allow any encryption this method will always throw ::com::sun::star::packages::NoEncryptionException.

In case the stream is open in readonly mode the XStream::getOutputStream method will return an empty reference.

Parameter sStreamName
the name of the substream that should be open
Parameter nOpenMode
a mode the stream should be open in, can be a combination of ElementModes values
Parameter sPassword
this parameter allowes to specify a reading password for the stream, the password must be a correct one, otherwise an exception will be thrown
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::packages::NoEncryptionException the stream is not encrypted
Throws
::com::sun::star::packages::WrongPasswordException the provided password is wrong
Throws
::com::sun::star::io::IOException in case of io errors during stream opening
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
openStorageElement
XStorage
openStorageElement( [in] string  sStorName,
[in] long  nOpenMode )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get access to a child storage.

The opened substorage must support specified in 'nOpenMode' access modes. It can support 'read' mode in addition. But any child element can support one of those modes only in case this mode is supported by parent storage.

Parameter sStorName
the name of the storage that should be open
Parameter nOpenMode
a mode the storage should be open in
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::io::IOException in case of io errors during stream opening
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
cloneStreamElement
::com::sun::star::io::XStream
cloneStreamElement( [in] string  sStreamName )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::packages::WrongPasswordException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get readonly copy of a child stream of the storage.

The stream is open in readonly mode so the XStream::getOutputStream method will return an empty reference.

Parameter sStreamName
the name of the substream that should be copied
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::packages::WrongPasswordException the provided password is wrong
Throws
::com::sun::star::io::IOException in case of io errors during stream opening
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
cloneEncryptedStreamElement
::com::sun::star::io::XStream
cloneEncryptedStreamElement( [in] string  sStreamName,
[in] string  sPassword )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::packages::NoEncryptionException,
::com::sun::star::packages::WrongPasswordException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get readonly copy of a child encrypted stream with password.

If storage does not allow any encryption this method will always throw ::com::sun::star::packages::NoEncryptionException.

The stream is open in readonly mode so the XStream::getOutputStream method will return an empty reference.

This method allows to specify reading password for the child stream explicitly.

Parameter sStreamName
the name of the substream that should be copied
Parameter sPassword
this parameter allowes to specify a reading password for the stream, the password must be a correct one, otherwise an exception will be thrown
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::packages::NoEncryptionException the stream is not encrypted
Throws
::com::sun::star::packages::WrongPasswordException the provided password is wrong
Throws
::com::sun::star::io::IOException in case of io errors during stream opening
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
copyLastCommitTo
void
copyLastCommitTo( [in] XStorage  xTargetStorage )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get copy of this storage at the state of it's last commit.

This method makes sence only for services implementations that allow transaction in the storage.

Parameter xStorage
the target storage that will be filled in with copy.
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::io::IOException in case of io errors during copying
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
copyStorageElementLastCommitTo
void
copyStorageElementLastCommitTo( [in] string  sStorName,
[in] XStorage  xTargetStorage )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to get copy of a child storage at the state of it's last commit.

This method makes sence only for services implementations that allow transaction in the storage.

Parameter sStorName
the name of the storage that should be copied
Parameter xStorage
the target storage that will be filled in with copy
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
Throws
::com::sun::star::lang::IllegalArgumentException one of provided arguments is illegal
Throws
::com::sun::star::io::IOException in case of io errors during copying
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
isStreamElement
boolean
isStreamElement( [in] string  sElementName )
raises( ::com::sun::star::container::NoSuchElementException,
::com::sun::star::lang::IllegalArgumentException,
InvalidStorageException );

Description
allows to check if an element is a child stream with specified name.

In case there is no child element with such name an exception will be thrown.

Parameter sElementName
the name of the element to check
Returns
true in case the element is a stream false - the element is a storage
Throws
::com::sun::star::container::NoSuchElementException there is no element with such name
Throws
::com::sun::star::lang::IllegalArgumentException an illegal argument is provided
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
isStorageElement
boolean
isStorageElement( [in] string  sElementName )
raises( ::com::sun::star::container::NoSuchElementException,
::com::sun::star::lang::IllegalArgumentException,
InvalidStorageException );

Description
allows to check if an element is a child storage with specified name.

In case there is no child element with such name an exception will be thrown.

Parameter sElementName
the name of the element to check
Returns
true in case the element is a storage false - the element is a stream
Throws
::com::sun::star::container::NoSuchElementException there is no element with such name
Throws
::com::sun::star::lang::IllegalArgumentException an illegal argument is provided
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for any reason
removeElement
void
removeElement( [in] string  sElementName )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::container::NoSuchElementException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
removes an element from a storage.
Parameter sElementName
the name of the element to remove
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for eny reason
Throws
::com::sun::star::lang::IllegalArgumentException an illegal argument is provided
Throws
::com::sun::star::container::NoSuchElementException there is no element with such name
Throws
::com::sun::star::io::IOException in case of io errors during removing
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
renameElement
void
renameElement( [in] string  sElementName,
[in] string  sNewName )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::container::NoSuchElementException,
::com::sun::star::container::ElementExistException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
renames an element in a storage.
Parameter sElementName
the old name of the element to rename
Parameter sNewName
the new name of the element to rename
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for eny reason
Throws
::com::sun::star::lang::IllegalArgumentException an illegal argument is provided
Throws
::com::sun::star::container::NoSuchElementException there is no element with old name in this storage
Throws
::com::sun::star::container::ElementExistException an element with new name already exists in this storage
Throws
::com::sun::star::io::IOException in case of io errors during renaming
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
copyElementTo
void
copyElementTo( [in] string  sElementName,
[in] XStorage  xDest,
[in] string  sNewName )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::container::NoSuchElementException,
::com::sun::star::container::ElementExistException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to copy an entry from one storage to another.

If target element supports transacted mode it must be commited by this method after successful copying.

Parameter sElementName
the name of the element in this storage
Parameter xDest
a destination storage
Parameter sNewName
the name of the result element in destination storage
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for eny reason
Throws
::com::sun::star::container::NoSuchElementException there is no specified source element in this storage
Throws
::com::sun::star::container::ElementExistException an element with specified destination name already exists in destination storage
Throws
::com::sun::star::io::IOException in case of io errors during copying
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
moveElementTo
void
moveElementTo( [in] string  sElementName,
[in] XStorage  xDest,
[in] string  sNewName )
raises( InvalidStorageException,
::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::container::NoSuchElementException,
::com::sun::star::container::ElementExistException,
::com::sun::star::io::IOException,
StorageWrappedTargetException );

Description
allows to move an entry from one storage to another.

If target element supports transacted mode it must be commited by this method after successful moving.

Parameter sElementName
the name of the element in this storage
Parameter xDest
a destination storage
Parameter sNewName
the name of the result element in destination storage
Throws
::com::sun::star::embed::InvalidStorageException this storage is in invalid state for eny reason
Throws
::com::sun::star::container::NoSuchElementException there is no specified source element in this storage
Throws
::com::sun::star::container::ElementExistException an element with specified destination name already exists in destination storage
Throws
::com::sun::star::io::IOException in case of io errors during moving
Throws
::com::sun::star::embed::StorageWrappedTargetException wraps other exceptions
Top of Page

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.