offapi/com/sun/star/embed/XHierarchicalStorageAccess.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21
  22  module com {  module sun {  module star {  module embed {
  23
  24 /** This interface allows hierarchical access to storage tree.
  25
  26     <p>
  27     Currently only streams can be opened using this interface.
  28     </p>
  29
  30     <p>
  31     The hierarchical access can not be mixed with a normal access. Thus when
  32     in a storage a stream with a path "a/b/c" is accessed using hierarchical
  33     access, another stream "a/b/d" can also be opened with hierarchical
  34     access ( if it is still not opened ), but the substorage "a" can not be
  35     opened ( it is locked by hierarchical access ).
  36     </p>
  37  */
  38 published interface XHierarchicalStorageAccess
  39 {
  40     // METHODS
  41     /** allows to get access to a child stream of the storage, using
  42         hierarchical path.
  43
  44         <p>
  45         In case the stream is open in readonly mode the
  46         com::sun::star::io::XStream::getOutputStream()
  47         method will return an empty reference.
  48         </p>
  49
  50         @param sStreamPath
  51             the path to the substream that should be open
  52
  53         @param nOpenMode
  54             a mode the stream should be open in,
  55             can be a combination of ElementModes values
  56
  57         @throws ::com::sun::star::embed::InvalidStorageException
  58             this storage is in invalid state for any reason
  59
  60         @throws ::com::sun::star::lang::IllegalArgumentException
  61             one of provided arguments is illegal
  62
  63         @throws ::com::sun::star::packages::WrongPasswordException
  64             the provided password is wrong
  65
  66         @throws ::com::sun::star::io::IOException
  67             in case of io errors during stream opening
  68
  69         @throws ::com::sun::star::embed::StorageWrappedTargetException
  70             wraps other exceptions
  71      */
  72     XExtendedStorageStream  openStreamElementByHierarchicalName(
  73             [in] string sStreamPath,
  74             [in] long nOpenMode )
  75         raises( ::com::sun::star::embed::InvalidStorageException,
  76                 ::com::sun::star::lang::IllegalArgumentException,
  77                 ::com::sun::star::packages::WrongPasswordException,
  78                 ::com::sun::star::io::IOException,
  79                 ::com::sun::star::embed::StorageWrappedTargetException );
  80
  81     /** allows to get access to a child encrypted stream with password using
  82         hierarchical path.
  83
  84         <p>
  85         If storage does not allow any encryption this method will always throw
  86         com::sun::star::packages::NoEncryptionException.
  87         </p>
  88
  89         <p>
  90         In case the stream is open in readonly mode the
  91         com::sun::star::io::XStream::getOutputStream()
  92         method will return an empty reference.
  93         </p>
  94
  95         @param sStreamName
  96             the path to the substream that should be open
  97
  98         @param nOpenMode
  99             a mode the stream should be open in,
 100             can be a combination of ElementModes values
 101
 102         @param sPassword
 103             this parameter allows to specify a reading password for the
 104             stream, the password must be a correct one, otherwise an
 105             exception will be thrown
 106
 107         @throws ::com::sun::star::embed::InvalidStorageException
 108             this storage is in invalid state for any reason
 109
 110         @throws ::com::sun::star::lang::IllegalArgumentException
 111             one of provided arguments is illegal
 112
 113         @throws ::com::sun::star::packages::NoEncryptionException
 114             the stream is not encrypted
 115
 116         @throws ::com::sun::star::packages::WrongPasswordException
 117             the provided password is wrong
 118
 119         @throws ::com::sun::star::io::IOException
 120             in case of io errors during stream opening
 121
 122         @throws ::com::sun::star::embed::StorageWrappedTargetException
 123             wraps other exceptions
 124      */
 125     XExtendedStorageStream  openEncryptedStreamElementByHierarchicalName(
 126             [in] string sStreamName,
 127             [in] long nOpenMode,
 128             [in] string sPassword )
 129         raises( ::com::sun::star::embed::InvalidStorageException,
 130                 ::com::sun::star::lang::IllegalArgumentException,
 131                 ::com::sun::star::packages::NoEncryptionException,
 132                 ::com::sun::star::packages::WrongPasswordException,
 133                 ::com::sun::star::io::IOException,
 134                 ::com::sun::star::embed::StorageWrappedTargetException );
 135
 136     /** removes a stream specified by hierarchical name from a storage.
 137
 138         @param sElementPath
 139             the path to the element to remove
 140
 141         @throws ::com::sun::star::embed::InvalidStorageException
 142             this storage is in invalid state for any reason
 143
 144         @throws ::com::sun::star::lang::IllegalArgumentException
 145             an illegal argument is provided
 146
 147         @throws ::com::sun::star::container::NoSuchElementException
 148             there is no element with such name
 149
 150         @throws ::com::sun::star::io::IOException
 151             in case of io errors during removing
 152
 153         @throws ::com::sun::star::embed::StorageWrappedTargetException
 154             wraps other exceptions
 155
 156      */
 157     void removeStreamElementByHierarchicalName( [in] string sElementPath )
 158         raises( ::com::sun::star::embed::InvalidStorageException,
 159                 ::com::sun::star::lang::IllegalArgumentException,
 160                 ::com::sun::star::container::NoSuchElementException,
 161                 ::com::sun::star::io::IOException,
 162                 ::com::sun::star::embed::StorageWrappedTargetException );
 163
 164 };
 165
 166
 167 }; }; }; };
 168
 169 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */