Branch data Line data Source code
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 neccessarily "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 : 6096 : void EnableKillingFile( sal_Bool bEnable=sal_True )
125 : 6096 : { 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: */
|