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 #include "unotools/unotoolsdllapi.h"
  20
  21 #ifndef _UNOTOOLS_TEMPFILE_HXX
  22 #define _UNOTOOLS_TEMPFILE_HXX
  23
  24 #include <tools/string.hxx>
  25 #include <tools/stream.hxx>
  26
  27 namespace utl
  28 {
  29
  30 struct TempFile_Impl;
  31
  32 /**
  33     The class TempFile gives access to temporary files in the local file system. Sometimes they are needed because a 3rd party
  34     code has a file name based interface, or some file access has to be done locally without transferring tons of bytes to or
  35     from a remote system.
  36     Creating a UCB content on a TempFile is only possible if a UCP for the local file system is present.
  37     TempFiles can always be accessed by SvFileStreams or Sot/SvStorages using the "physical" file name ( not the URL, because
  38     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
  39     the UCB helper classes for streams. For convenience use UcbStreamHelper.
  40     A Tempfile always has a "physical" file name ( a file name in the local computers host notation ) but it has a
  41     "UCB compatible" URL only if a UCP for the local file system exists. This URL may have its own URL scheme
  42     ( not necessarily "file://" ! ). The TempFile class methods take this into account, but other simple conversions like
  43     the osl functions do not.
  44     So it is a potential error to convert between the filename and the URL of a TempFile object using functions or methods
  45     outside this class.
  46 */
  47
  48 class UNOTOOLS_DLLPUBLIC TempFile
  49 {
  50     TempFile_Impl*  pImp;
  51     sal_Bool        bKillingFileEnabled;
  52
  53 protected:
  54
  55 public:
  56                     /**
  57                     Create a temporary file or directory, in the default tempfile folder or if possible in a given folder.
  58                     This given folder ( the "parent" parameter ( if not NULL ) ) must be a "UCB compatible" URL.
  59                     The temporary object is created in the local file system, even if there is no UCB that can access it.
  60                     If the given folder is part of the local file system, the TempFile is created in this folder.
  61                     */
  62                     TempFile( const String* pParent=NULL, sal_Bool bDirectory=sal_False );
  63
  64                     /**
  65                     Same as above; additionally the name starts with some given characters followed by a counter ( example:
  66                     rLeadingChars="abc" means "abc0","abc1" and so on, depending on existing files in the folder ).
  67                     The extension string may be f.e. ".txt" or "", if no extension string is given, ".tmp" is used
  68                     */
  69                     TempFile( const String& rLeadingChars, const String* pExtension=NULL, const String* pParent=NULL,
  70                                 sal_Bool bDirectory=sal_False);
  71
  72                     /**
  73                     Same as above; additionally the name starts with some given characters followed by a counter ( example:
  74                     rLeadingChars="abc" means "abc0","abc1" and so on, depending on existing files in the folder ).
  75                     The extension string may be f.e. ".txt" or "", if no extension string is given, ".tmp" is used
  76                         @param  _bStartWithZero If set to false names will be generated like "abc","abc0","abc1"
  77                     */
  78                     TempFile( const String& rLeadingChars,sal_Bool _bStartWithZero, const String* pExtension=NULL, const String* pParent=NULL,sal_Bool bDirectory=sal_False);
  79
  80                     /**
  81                     TempFile will be removed from disk in dtor if EnableKillingTempFile was called before.
  82                     Temporary directories will be removed recursively in that case.
  83                     */
  84                     ~TempFile();
  85
  86                     /**
  87                     Returns sal_True if it has a valid file name.
  88                     */
  89     sal_Bool        IsValid() const;
  90
  91                     /**
  92                     Returns the "UCB compatible" URL of the tempfile object.
  93                     If you want to have the "physical" file name, use the GetFileName() method of this object, because these
  94                     method uses the UCB for the conversion, but never use any external conversion functions for URLs into
  95                     "physical" names.
  96                     If no UCP is available for the local file system, an empty URL is returned. In this case you can't access
  97                     the file as a UCB content !
  98                     */
  99     String          GetURL() const;
 100
 101                     /**
 102                     Returns the "physical" name of the tempfile in host notation ( should only be used for 3rd party code
 103                     with file name interfaces ).
 104                     If you want to have the URL, use the GetURL() method of this object, but never use any external
 105                     conversion functions for "physical" names into URLs.
 106                     */
 107     String          GetFileName() const;
 108
 109                     /**
 110                     Returns a stream to the tempfiles data; the stream is owned by the tempfile object, so you have to keep this
 111                     alive as long as you want to use the stream. If the TempFile object is destroyed, it also destroys the
 112                     stream object, the underlying file is only deleted if EnableKillingFile( sal_True ) has been called before!
 113                     */
 114     SvStream*       GetStream( StreamMode eMode );
 115
 116                     /**
 117                     Let the TempFile object close and destroy the owned stream object if any.
 118                     */
 119     void            CloseStream();
 120
 121                     /**
 122                     If enabled the file will be removed from disk when the dtor is called ( default is not enabled )
 123                     */
 124     void            EnableKillingFile( sal_Bool bEnable=sal_True )
 125                     { bKillingFileEnabled = bEnable; }
 126
 127     sal_Bool        IsKillingFileEnabled() const
 128                     { return bKillingFileEnabled; }
 129
 130                     /**
 131                     Only create a "physical" file name for a temporary file that would be valid at that moment.
 132                     Should only be used for 3rd party code with a file name interface that wants to create the file by itself.
 133                     If you want to convert file name into a URL, always use class LocalFileHelper, but never use any
 134                     conversion functions of osl.
 135                     */
 136     static String   CreateTempName( const String* pParent=NULL );
 137
 138                     /**
 139                     The TempNameBaseDirectory is a subfolder in the folder that is passed as a "physical" file name in the
 140                     SetTempNameBaseDirectory method.
 141                     This subfolder will be used if a TempFile or TempName is created without a parent name or a parent name
 142                     that does not belong to the local file system.
 143                     The caller of the SetTempNameBase is responsible for deleting this folder and all temporary files in it.
 144                     The return value of both methods is the complete "physical" name of the tempname base folder.
 145                     It is not a URL because alle URLs must be "UCB compatible", so there may be no suitable URL at all.
 146                     */
 147     static String   SetTempNameBaseDirectory( const String &rBaseName );
 148 };
 149
 150 }
 151
 152 #endif
 153
 154 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */