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