]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/tarstrm.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / tarstrm.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: tarstrm.h
3 // Purpose: interface of wxTar* classes
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8
9 /** wxTarEntry::GetTypeFlag() values */
10 enum wxTarType
11 {
12 wxTAR_REGTYPE = '0', //!< regular file
13 wxTAR_LNKTYPE = '1', //!< hard link
14 wxTAR_SYMTYPE = '2', //!< symbolic link
15 wxTAR_CHRTYPE = '3', //!< character special
16 wxTAR_BLKTYPE = '4', //!< block special
17 wxTAR_DIRTYPE = '5', //!< directory
18 wxTAR_FIFOTYPE = '6', //!< named pipe
19 wxTAR_CONTTYPE = '7' //!< contiguous file
20 };
21
22 /** Archive Formats (use wxTAR_PAX, it's backward compatible) used by wxTarEntry */
23 enum wxTarFormat
24 {
25 wxTAR_USTAR, //!< POSIX.1-1990 tar format
26 wxTAR_PAX //!< POSIX.1-2001 tar format
27 };
28
29
30 /**
31 @class wxTarInputStream
32
33 Input stream for reading tar files.
34
35 wxTarInputStream::GetNextEntry() returns a wxTarEntry object containing the
36 meta-data for the next entry in the tar (and gives away ownership).
37 Reading from the wxTarInputStream then returns the entry's data.
38 wxTarInputStream::Eof() becomes @true after an attempt has been made to read
39 past the end of the entry's data.
40
41 When there are no more entries, wxTarInputStream::GetNextEntry() returns @NULL
42 and sets wxTarInputStream::Eof().
43
44 Tar entries are seekable if the parent stream is seekable. In practice this
45 usually means they are only seekable if the tar is stored as a local file and
46 is not compressed.
47
48 @library{wxbase}
49 @category{archive,streams}
50
51 @see @ref overview_archive_byname
52 */
53 class wxTarInputStream : public wxArchiveInputStream
54 {
55 public:
56 //@{
57 /**
58 Constructor. In a Unicode build the second parameter @a conv is
59 used to translate fields from the standard tar header into Unicode.
60
61 It has no effect on the stream's data. @a conv is only used for the standard
62 tar headers, any pax extended headers are always UTF-8 encoded.
63
64 If the parent stream is passed as a pointer then the new filter stream
65 takes ownership of it. If it is passed by reference then it does not.
66 */
67 wxTarInputStream(wxInputStream& stream,
68 wxMBConv& conv = wxConvLocal);
69 wxTarInputStream(wxInputStream* stream,
70 wxMBConv& conv = wxConvLocal);
71 //@}
72
73 /**
74 Closes the current entry.
75 On a non-seekable stream reads to the end of the current entry first.
76 */
77 bool CloseEntry();
78
79 /**
80 Closes the current entry if one is open, then reads the meta-data for
81 the next entry and returns it in a wxTarEntry object, giving away ownership.
82 The stream is then open and can be read.
83 */
84 wxTarEntry* GetNextEntry();
85
86 /**
87 Closes the current entry if one is open, then opens the entry specified
88 by the @a entry object.
89
90 @a entry should be from the same tar file, and the tar should be on a
91 seekable stream.
92 */
93 bool OpenEntry(wxTarEntry& entry);
94 };
95
96
97
98 /**
99 @class wxTarClassFactory
100
101 Class factory for the tar archive format.
102 See the base class for details.
103
104 @library{wxbase}
105 @category{archive,streams}
106
107 @see @ref overview_archive, @ref overview_archive_generic,
108 wxTarEntry, wxTarInputStream, wxTarOutputStream
109 */
110 class wxTarClassFactory : public wxArchiveClassFactory
111 {
112 public:
113
114 };
115
116
117
118 /**
119 @class wxTarOutputStream
120
121 Output stream for writing tar files.
122
123 wxTarOutputStream::PutNextEntry() is used to create a new entry in the output tar,
124 then the entry's data is written to the wxTarOutputStream.
125 Another call to wxTarOutputStream::PutNextEntry() closes the current entry
126 and begins the next.
127
128 @library{wxbase}
129 @category{streams}
130
131 @see @ref overview_archive, wxTarEntry, wxTarInputStream
132 */
133 class wxTarOutputStream : public wxArchiveOutputStream
134 {
135 public:
136 //@{
137 /**
138 If the parent stream is passed as a pointer then the new filter stream
139 takes ownership of it. If it is passed by reference then it does not.
140
141 In a Unicode build the third parameter @a conv is used to translate the
142 headers fields into an 8-bit encoding. It has no effect on the stream's data.
143
144 When the @a format is @e wxTAR_PAX, pax extended headers are generated
145 when any header field will not fit the standard tar header block or if it
146 uses any non-ascii characters.
147
148 Extended headers are stored as extra 'files' within the tar, and will be
149 extracted as such by any other tar program that does not understand them.
150 The @a conv parameter only affect the standard tar headers, the extended
151 headers are always UTF-8 encoded.
152
153 When the @a format is @e wxTAR_USTAR, no extended headers are generated,
154 and instead a warning message is logged if any header field overflows.
155 */
156 wxTarOutputStream(wxOutputStream& stream,
157 wxTarFormat format = wxTAR_PAX,
158 wxMBConv& conv = wxConvLocal);
159 wxTarOutputStream(wxOutputStream* stream,
160 wxTarFormat format = wxTAR_PAX,
161 wxMBConv& conv = wxConvLocal);
162 //@}
163
164 /**
165 The destructor calls Close() to finish writing the tar if it has
166 not been called already.
167 */
168 virtual ~wxTarOutputStream();
169
170 /**
171 Finishes writing the tar, returning @true if successful.
172 Called by the destructor if not called explicitly.
173 */
174 bool Close();
175
176 /**
177 Close the current entry.
178
179 It is called implicitly whenever another new entry is created with
180 CopyEntry() or PutNextEntry(), or when the tar is closed.
181 */
182 bool CloseEntry();
183
184 /**
185 See wxArchiveOutputStream::CopyArchiveMetaData().
186 For the tar format this function does nothing.
187 */
188 bool CopyArchiveMetaData(wxTarInputStream& s);
189
190 /**
191 Takes ownership of @a entry and uses it to create a new entry in the tar.
192 @a entry is then opened in @a inputStream and its contents copied to this stream.
193
194 For some other archive formats CopyEntry() is much more efficient than
195 transferring the data using Read() and Write() since it will copy them
196 without decompressing and recompressing them.
197 For tar however it makes no difference.
198
199 For tars on seekable streams, @a entry must be from the same tar file
200 as @a inputStream. For non-seekable streams, @a entry must also be the
201 last thing read from @a inputStream.
202 */
203 bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream);
204
205 //@{
206 /**
207 The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes.
208
209 The blocking factor defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
210 (see wxTarOutputStream()), as specified in the POSIX standards.
211 */
212 int GetBlockingFactor() const;
213 void SetBlockingFactor(int factor);
214 //@}
215
216 /**
217 Create a new directory entry (see wxArchiveEntry::IsDir()) with the given
218 name and timestamp.
219
220 PutNextEntry() can also be used to create directory entries, by supplying
221 a name with a trailing path separator.
222 */
223 bool PutNextDirEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now());
224
225 /**
226 Takes ownership of entry and uses it to create a new entry in the tar.
227 */
228 bool PutNextEntry(wxTarEntry* entry);
229
230 /**
231 Create a new entry with the given name, timestamp and size.
232 */
233 bool PutNextEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now(),
234 wxFileOffset size = wxInvalidOffset);
235 };
236
237
238
239 /**
240 @class wxTarEntry
241
242 Holds the meta-data for an entry in a tar.
243
244 @section tarentry_fields Field availability
245
246 The tar format stores all the meta-data for an entry ahead of its data,
247 therefore GetNextEntry() always returns a fully populated wxTarEntry object,
248 both when reading from seekable and non-seekable streams.
249
250 @library{wxbase}
251 @category{archive,streams}
252
253 @see @ref overview_archive, wxTarInputStream, wxTarOutputStream
254 */
255 class wxTarEntry : public wxArchiveEntry
256 {
257 public:
258 /**
259 Constructor.
260
261 The tar archive format stores the entry's size ahead of the entry's data.
262 Therefore when creating an archive on a non-seekable stream it is necessary
263 to supply the correct size when each entry is created.
264 */
265 wxTarEntry(const wxString& name = wxEmptyString,
266 const wxDateTime& dt = wxDateTime::Now(),
267 wxFileOffset size = wxInvalidOffset);
268
269 /**
270 Copy constructor.
271 */
272 wxTarEntry(const wxTarEntry& entry);
273
274 //@{
275 /**
276 Gets/sets the entry's access time stamp.
277 See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
278 */
279 wxDateTime GetAccessTime() const;
280 void SetAccessTime(const wxDateTime& dt);
281 //@}
282
283 //@{
284 /**
285 The entry's creation time stamp.
286 See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
287 */
288 wxDateTime GetCreateTime() const;
289 void SetCreateTime(const wxDateTime& dt);
290 //@}
291
292 //@{
293 /**
294 OS specific IDs defining a device; these are only meaningful when
295 wxTarEntry::GetTypeFlag() is @e wxTAR_CHRTYPE or @e wxTAR_BLKTYPE.
296 */
297 int GetDevMajor() const;
298 int GetDevMinor() const;
299 void SetDevMajor(int dev);
300 void SetDevMinor(int dev);
301 //@}
302
303 //@{
304 /**
305 The user ID and group ID that has permissions (see wxTarEntry::GetMode())
306 over this entry.
307
308 These values aren't usually useful unless the file will only be
309 restored to the same system it originated from.
310 wxTarEntry::GetGroupName() and wxTarEntry::GetUserName() can be used instead.
311 */
312 int GetGroupId() const;
313 int GetUserId() const;
314 void SetGroupId(int id);
315 void SetUserId(int id);
316 //@}
317
318 //@{
319 /**
320 The names of the user and group that has permissions (see wxTarEntry::GetMode())
321 over this entry. These are not present in very old tars.
322 */
323 wxString GetGroupName() const;
324 wxString GetUserName() const;
325 void SetGroupName(const wxString& group);
326 void SetUserName(const wxString& user);
327 //@}
328
329 //@{
330 /**
331 The filename of a previous entry in the tar that this entry is a link to.
332 Only meaningful when wxTarEntry::GetTypeFlag() is set to @e wxTAR_LNKTYPE
333 or @e wxTAR_SYMTYPE.
334 */
335 wxString GetLinkName() const;
336 void SetLinkName(const wxString& link);
337 //@}
338
339 //@{
340 /**
341 UNIX permission bits for this entry.
342 Giving read, write and execute permissions to the file's user and group
343 (see GetGroupName() and GetUserName()) and to others.
344
345 The integer is one or more ::wxPosixPermissions flags OR-combined.
346 */
347 int GetMode() const;
348 void SetMode(int mode);
349 //@}
350
351 //@{
352 /**
353 The size of the entry's data in bytes.
354
355 The tar archive format stores the entry's size ahead of the entry's data.
356 Therefore when creating an archive on a non-seekable stream it is necessary to
357 supply the correct size when each entry is created.
358
359 For seekable streams this is not necessary as wxTarOutputStream will attempt
360 to seek back and fix the entry's header when the entry is closed, though it is
361 still more efficient if the size is given beforehand.
362 */
363 void SetSize(wxFileOffset size);
364 wxFileOffset GetSize() const;
365 //@}
366
367 //@{
368 /**
369 Returns/Sets the type of the entry as a ::wxTarType value.
370
371 When creating archives use only one of ::wxTarType values.
372 When reading archives, GetTypeFlag() may return a value which does not
373 match any value of ::wxTarType; in this case the returned value should be
374 treated as @e wxTAR_REGTYPE.
375 */
376 int GetTypeFlag() const;
377 void SetTypeFlag(int type);
378 //@}
379
380 /**
381 Returns the entry's filename in the internal format used within the archive.
382
383 The name can include directory components, i.e. it can be a full path.
384 The names of directory entries are returned without any trailing path separator.
385 This gives a canonical name that can be used in comparisons.
386 */
387 wxString GetInternalName() const;
388
389 /**
390 A static member that translates a filename into the internal format used
391 within the archive.
392
393 If the third parameter is provided, the bool pointed to is set to indicate
394 whether the name looks like a directory name (i.e. has a trailing path separator).
395 */
396 static wxString GetInternalName(const wxString& name,
397 wxPathFormat format = wxPATH_NATIVE,
398 bool* pIsDir = NULL);
399
400 /**
401 Assignment operator.
402 */
403 wxTarEntry& operator operator=(const wxTarEntry& entry);
404 };
405