include/unotools/tempfile.hxx

   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 #pragma once
  20
  21 #include <unotools/unotoolsdllapi.h>
  22 #include <com/sun/star/io/XInputStream.hpp>
  23 #include <com/sun/star/io/XOutputStream.hpp>
  24 #include <com/sun/star/io/XStream.hpp>
  25 #include <com/sun/star/io/XSeekable.hpp>
  26 #include <com/sun/star/io/XTruncate.hpp>
  27 #include <cppuhelper/implbase.hxx>
  28 #include <tools/stream.hxx>
  29 #include <memory>
  30 #include <mutex>
  31 #include <optional>
  32
  33 namespace utl
  34 {
  35
  36
  37 /**
  38   This is the "fast" temp file. Different OSes have different ideas how this should work, so this
  39   class presents an interface that is fast across Windows and Unix (which differ in how they want
  40   temp files to work).
  41   The key point is that such a temporary file is only a readable/writeable stream, and does not have
  42   a filename, or a location in the filesystem hierarchy.
  43   If you need a name or a URL, you should use TempFileNamed, which is slower, but creates an actual
  44   file in the filesystem.
  45 */
  46 class UNOTOOLS_DLLPUBLIC TempFileFast
  47 {
  48     std::unique_ptr<SvFileStream> mxStream;
  49
  50 public:
  51                     TempFileFast();
  52                     TempFileFast(TempFileFast && other) noexcept;
  53                     ~TempFileFast();
  54
  55                     /**
  56                     Returns a stream to the tempfiles data; the stream is owned by the tempfile object, so you have to keep this
  57                     alive as long as you want to use the stream.
  58                     */
  59     SvStream*       GetStream( StreamMode eMode );
  60
  61                     /**
  62                     Close and destroy the owned stream object if any.
  63                     */
  64     void            CloseStream();
  65
  66 };
  67
  68 /**
  69 Only create a "physical" file name for a temporary file that would be valid at that moment.
  70 Should only be used for 3rd party code with a file name interface that wants to create the file by itself.
  71 If you want to convert file name into a URL, always use class LocalFileHelper, but never use any
  72 conversion functions of osl.
  73 */
  74 UNOTOOLS_DLLPUBLIC OUString CreateTempName();
  75
  76 UNOTOOLS_DLLPUBLIC OUString CreateTempURL( const OUString* pParent=nullptr, bool bDirectory=false );
  77
  78 /**
  79 Same as above; additionally the name starts with some given characters followed by a counter ( example:
  80 rLeadingChars="abc" means "abc0","abc1" and so on, depending on existing files in the folder ).
  81 The extension string may be f.e. ".txt" or "", if no extension string is given, ".tmp" is used
  82     @param  _bStartWithZero If set to false names will be generated like "abc","abc0","abc1"
  83     @param  bCreateParentDirs If rLeadingChars contains a slash, this will create the required
  84             parent directories.
  85 */
  86 UNOTOOLS_DLLPUBLIC OUString CreateTempURL( std::u16string_view rLeadingChars, bool _bStartWithZero=true, std::u16string_view pExtension={},
  87                           const OUString* pParent=nullptr, bool bCreateParentDirs=false );
  88
  89 /**
  90 The TempNameBaseDirectory is a subfolder in the folder that is passed as a "physical" file name in the
  91 SetTempNameBaseDirectory method.
  92 This subfolder will be used if a TempFile or TempName is created without a parent name or a parent name
  93 that does not belong to the local file system.
  94 The caller of the SetTempNameBase is responsible for deleting this folder and all temporary files in it.
  95 The return value of both methods is the complete "physical" name of the tempname base folder.
  96 It is not a URL because all URLs must be "UCB compatible", so there may be no suitable URL at all.
  97 */
  98 UNOTOOLS_DLLPUBLIC OUString SetTempNameBaseDirectory( const OUString &rBaseName );
  99
 100 // Return the URL of the temp directory (the one set with SetTempNameBaseDirectory or the
 101 // default tempfile folder):
 102 UNOTOOLS_DLLPUBLIC OUString GetTempNameBaseDirectory();
 103
 104 /**
 105     The class TempFile gives access to temporary files in the local file system. Sometimes they are needed because a 3rd party
 106     code has a file name based interface, or some file access has to be done locally without transferring tons of bytes to or
 107     from a remote system.
 108     Creating a UCB content on a TempFile is only possible if a UCP for the local file system is present.
 109     TempFiles can always be accessed by SvFileStreams or Sot/SvStorages using the "physical" file name ( not the URL, because
 110     this may be a non-file URL, see below ), but if a UCB content can be created, it is also possible to take the URL and use
 111     the UCB helper classes for streams. For convenience use UcbStreamHelper.
 112     A Tempfile always has a "physical" file name ( a file name in the local computers host notation ) but it has a
 113     "UCB compatible" URL only if a UCP for the local file system exists. This URL may have its own URL scheme
 114     ( not necessarily "file://" ! ). The TempFile class methods take this into account, but other simple conversions like
 115     the osl functions do not.
 116     So it is a potential error to convert between the filename and the URL of a TempFile object using functions or methods
 117     outside this class.
 118 */
 119 class UNOTOOLS_DLLPUBLIC TempFileNamed
 120 {
 121 friend UNOTOOLS_DLLPUBLIC OUString SetTempNameBaseDirectory( const OUString & );
 122     OUString    aName;
 123     std::unique_ptr<SvStream>
 124                 pStream;
 125     bool        bIsDirectory;
 126     bool        bKillingFileEnabled;
 127
 128 public:
 129                     /**
 130                     Create a temporary file or directory, in the default tempfile folder or if possible in a given folder.
 131                     This given folder ( the "parent" parameter ( if not NULL ) ) must be a "UCB compatible" URL.
 132                     The temporary object is created in the local file system, even if there is no UCB that can access it.
 133                     If the given folder is part of the local file system, the TempFile is created in this folder.
 134                     */
 135                     TempFileNamed( const OUString* pParent=nullptr, bool bDirectory=false );
 136
 137                     /**
 138                     Same as above; additionally the name starts with some given characters followed by a counter ( example:
 139                     rLeadingChars="abc" means "abc0","abc1" and so on, depending on existing files in the folder ).
 140                     The extension string may be f.e. ".txt" or "", if no extension string is given, ".tmp" is used
 141                         @param  _bStartWithZero If set to false names will be generated like "abc","abc0","abc1"
 142                         @param  bCreateParentDirs If rLeadingChars contains a slash, this will create the required
 143                                 parent directories.
 144                     */
 145                     TempFileNamed( std::u16string_view rLeadingChars, bool _bStartWithZero=true, std::u16string_view pExtension={},
 146                               const OUString* pParent = nullptr, bool bCreateParentDirs=false );
 147
 148                     TempFileNamed(TempFileNamed && other) noexcept;
 149
 150                     /**
 151                     TempFile will be removed from disk in dtor if EnableKillingFile(true) was called before.
 152                     Temporary directories will be removed recursively in that case.
 153                     */
 154                     ~TempFileNamed();
 155
 156                     /**
 157                     Returns sal_True if it has a valid file name.
 158                     */
 159     bool            IsValid() const;
 160
 161                     /**
 162                     Returns the URL of the tempfile object.
 163                     If you want to have the system path file name, use the GetFileName() method of this object
 164                     */
 165     OUString const & GetURL() const;
 166
 167                     /**
 168                     Returns the system path name of the tempfile in host notation
 169                     If you want to have the URL, use the GetURL() method of this object.
 170                     */
 171     OUString        GetFileName() const;
 172
 173                     /**
 174                     Returns a stream to the tempfiles data; the stream is owned by the tempfile object, so you have to keep this
 175                     alive as long as you want to use the stream. If the TempFile object is destroyed, it also destroys the
 176                     stream object, the underlying file is only deleted if EnableKillingFile(true) has been called before!
 177                     */
 178     SvStream*       GetStream( StreamMode eMode );
 179
 180                     /**
 181                     Let the TempFile object close and destroy the owned stream object if any.
 182                     */
 183     void            CloseStream();
 184
 185                     /**
 186                     If enabled the file will be removed from disk when the dtor is called ( default is not enabled )
 187                     */
 188     void            EnableKillingFile( bool bEnable=true )
 189                     { bKillingFileEnabled = bEnable; }
 190
 191 };
 192
 193
 194 typedef ::cppu::WeakImplHelper<
 195      css::io::XStream
 196     , css::io::XSeekable
 197     , css::io::XInputStream
 198     , css::io::XOutputStream
 199     , css::io::XTruncate> TempFileFastService_Base;
 200 class UNOTOOLS_DLLPUBLIC TempFileFastService final : public TempFileFastService_Base
 201 {
 202     std::optional<utl::TempFileFast> mpTempFile;
 203     std::mutex maMutex;
 204     SvStream* mpStream;
 205     bool mbInClosed;
 206     bool mbOutClosed;
 207
 208     void checkError () const;
 209     void checkConnected ();
 210
 211 public:
 212     explicit TempFileFastService ();
 213     virtual ~TempFileFastService () override;
 214
 215     // XInputStream
 216     virtual ::sal_Int32 SAL_CALL readBytes( css::uno::Sequence< ::sal_Int8 >& aData, ::sal_Int32 nBytesToRead ) override;
 217     virtual ::sal_Int32 SAL_CALL readSomeBytes( css::uno::Sequence< ::sal_Int8 >& aData, ::sal_Int32 nMaxBytesToRead ) override;
 218     virtual void SAL_CALL skipBytes( ::sal_Int32 nBytesToSkip ) override;
 219     virtual ::sal_Int32 SAL_CALL available(  ) override;
 220     virtual void SAL_CALL closeInput(  ) override;
 221     // XOutputStream
 222     virtual void SAL_CALL writeBytes( const css::uno::Sequence< ::sal_Int8 >& aData ) override;
 223     virtual void SAL_CALL flush(  ) override;
 224     virtual void SAL_CALL closeOutput(  ) override;
 225     // XSeekable
 226     virtual void SAL_CALL seek( sal_Int64 location ) override;
 227     virtual sal_Int64 SAL_CALL getPosition(  ) override;
 228     virtual sal_Int64 SAL_CALL getLength(  ) override;
 229     // XStream
 230     virtual css::uno::Reference< css::io::XInputStream > SAL_CALL getInputStream(  ) override;
 231     virtual css::uno::Reference< css::io::XOutputStream > SAL_CALL getOutputStream(  ) override;
 232     // XTruncate
 233     virtual void SAL_CALL truncate() override;
 234
 235 };
 236
 237
 238 }
 239
 240 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */