Interface XStorage

Devguide

Index

Methods' Summary

Attributes' Summary

Methods' Details

Attributes' Details

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

Copyright © 2013, The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache, the Apache feather logo, Apache OpenOffice and OpenOffice.org are trademarks of The Apache Software Foundation. Other names may be trademarks of their respective owners.

API

SDK

Tips ‘n’ Tricks

Miscellaneous