]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/tarstrm.tex
document LoadObject() (patch 1873045)
[wxWidgets.git] / docs / latex / wx / tarstrm.tex
1 %
2 % automatically generated by HelpGen $Revision$ from
3 % wx/tarstrm.h at 28/Oct/06 18:27:02
4 %
5
6 \section{\class{wxTarClassFactory}}\label{wxtarclassfactory}
7
8 Class factory for the tar archive format. See the base class
9 for details.
10
11 \wxheading{Derived from}
12
13 \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}\\
14 \helpref{wxObject}{wxobject}
15
16 \wxheading{Include files}
17
18 <wx/tarstrm.h>
19
20 \wxheading{Library}
21
22 \helpref{wxBase}{librarieslist}
23
24 \wxheading{See also}
25
26 \helpref{Archive formats such as zip}{wxarc}\\
27 \helpref{Generic archive programming}{wxarcgeneric}\\
28 \helpref{wxTarEntry}{wxtarentry}\\
29 \helpref{wxTarInputStream}{wxtarinputstream}\\
30 \helpref{wxTarOutputStream}{wxtaroutputstream}
31
32
33 %
34 % automatically generated by HelpGen $Revision$ from
35 % wx/tarstrm.h at 28/Oct/06 18:27:02
36 %
37
38 \section{\class{wxTarEntry}}\label{wxtarentry}
39
40 Holds the meta-data for an entry in a tar.
41
42 \wxheading{Derived from}
43
44 \helpref{wxArchiveEntry}{wxarchiveentry}\\
45 \helpref{wxObject}{wxobject}
46
47 \wxheading{Include files}
48
49 <wx/tarstrm.h>
50
51 \wxheading{Library}
52
53 \helpref{wxBase}{librarieslist}
54
55 \wxheading{Data structures}
56
57 Constants for \helpref{Get/SetTypeFlag}{wxtarentrytypeflag}:
58
59 \begin{verbatim}
60 // TypeFlag values
61 enum {
62 wxTAR_REGTYPE = '0', // regular file
63 wxTAR_LNKTYPE = '1', // hard link
64 wxTAR_SYMTYPE = '2', // symbolic link
65 wxTAR_CHRTYPE = '3', // character special
66 wxTAR_BLKTYPE = '4', // block special
67 wxTAR_DIRTYPE = '5', // directory
68 wxTAR_FIFOTYPE = '6', // named pipe
69 wxTAR_CONTTYPE = '7' // contiguous file
70 };
71
72 \end{verbatim}
73
74 \wxheading{See also}
75
76 \helpref{Archive formats such as zip}{wxarc}\\
77 \helpref{wxTarInputStream}{wxtarinputstream}\\
78 \helpref{wxTarOutputStream}{wxtaroutputstream}
79
80 \wxheading{Field availability}
81
82 The tar format stores all the meta-data for an entry ahead of its data,
83 therefore \helpref{GetNextEntry()}{wxtarinputstreamgetnextentry} always returns
84 a fully populated wxTarEntry object, both when reading from seekable and
85 non-seekable streams.
86
87
88 \latexignore{\rtfignore{\wxheading{Members}}}
89
90
91 \membersection{wxTarEntry::wxTarEntry}\label{wxtarentrywxtarentry}
92
93 \func{}{wxTarEntry}{\param{const wxString\& }{name = wxEmptyString}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}, \param{wxFileOffset }{size = wxInvalidOffset}}
94
95 Constructor. The tar archive format stores the entry's size ahead of the
96 entry's data. Therefore when creating an archive on a non-seekable stream it
97 is necessary to supply the correct size when each entry is created.
98
99 \func{}{wxTarEntry}{\param{const wxTarEntry\& }{entry}}
100
101 Copy constructor.
102
103
104 \membersection{wxTarEntry::Get/SetAccessTime}\label{wxtarentryaccesstime}
105
106 \constfunc{wxDateTime}{GetAccessTime}{\void}
107
108 \func{void}{SetAccessTime}{\param{const wxDateTime\& }{dt}}
109
110 The entry's access time stamp. See also
111 \helpref{wxArchiveEntry::Get/SetDateTime}{wxarchiveentrydatetime}.
112
113
114 \membersection{wxTarEntry::Get/SetCreateTime}\label{wxtarentrycreatetime}
115
116 \constfunc{wxDateTime}{GetCreateTime}{\void}
117
118 \func{void}{SetCreateTime}{\param{const wxDateTime\& }{dt}}
119
120 The entry's creation time stamp. See also
121 \helpref{wxArchiveEntry::Get/SetDateTime}{wxarchiveentrydatetime}.
122
123
124 \membersection{wxTarEntry::Get/SetDevMajor and Get/SetDevMinor}\label{wxtarentrydev}
125
126 \constfunc{int}{GetDevMajor}{\void}
127
128 \constfunc{int}{GetDevMinor}{\void}
129
130 \func{void}{SetDevMajor}{\param{int }{dev}}
131
132 \func{void}{SetDevMinor}{\param{int }{dev}}
133
134 OS specific IDs defining a device, these are only meaningful when
135 \helpref{TypeFlag}{wxtarentrytypeflag} is set to {\it wxTAR\_CHRTYPE}
136 or {\it wxTAR\_BLKTYPE}.
137
138
139 \membersection{wxTarEntry::Get/SetGroupId and Get/SetUserId}\label{wxtarentryuidgid}
140
141 \constfunc{int}{GetGroupId}{\void}
142
143 \constfunc{int}{GetUserId}{\void}
144
145 \func{void}{SetGroupId}{\param{int }{id}}
146
147 \func{void}{SetUserId}{\param{int }{id}}
148
149 The user ID and group ID that has \helpref{permissions}{wxtarentrymode} over
150 this entry. These values aren't usually useful unless the file will only be
151 restored to the same system it originated from. \helpref{Get/SetGroupName and
152 Get/SetUserName}{wxtarentryunamegname} can be used instead.
153
154
155 \membersection{wxTarEntry::Get/SetGroupName and Get/SetUserName}\label{wxtarentryunamegname}
156
157 \constfunc{wxString}{GetGroupName}{\void}
158
159 \constfunc{wxString}{GetUserName}{\void}
160
161 \func{void}{SetGroupName}{\param{const wxString\& }{group}}
162
163 \func{void}{SetUserName}{\param{const wxString\& }{user}}
164
165 The names of the user and group that has \helpref{permissions}{wxtarentrymode}
166 over this entry. These are not present in very old tars.
167
168
169 \membersection{wxTarEntry::GetInternalName}\label{wxtarentrygetinternalname}
170
171 \constfunc{wxString}{GetInternalName}{\void}
172
173 Returns the entry's filename in the internal format used within the
174 archive. The name can include directory components, i.e. it can be a
175 full path.
176
177 The names of directory entries are returned without any trailing path
178 separator. This gives a canonical name that can be used in comparisons.
179
180 \func{wxString}{GetInternalName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}, \param{bool* }{pIsDir = NULL}}
181
182 A static member that translates a filename into the internal format used
183 within the archive. If the third parameter is provided, the bool pointed
184 to is set to indicate whether the name looks like a directory name
185 (i.e. has a trailing path separator).
186
187
188 \membersection{wxTarEntry::Get/SetLinkName}\label{wxtarentrylinkname}
189
190 \constfunc{wxString}{GetLinkName}{\void}
191
192 \func{void}{SetLinkName}{\param{const wxString\& }{link}}
193
194 The filename of a previous entry in the tar that this entry is a link to.
195 Only meaningful when \helpref{TypeFlag}{wxtarentrytypeflag} is set
196 to {\it wxTAR\_LNKTYPE} or {\it wxTAR\_SYMTYPE}.
197
198
199 \membersection{wxTarEntry::Get/SetMode}\label{wxtarentrymode}
200
201 \constfunc{int}{GetMode}{\void}
202
203 \func{void}{SetMode}{\param{int }{mode}}
204
205 UNIX permission bits for this entry. Giving read, write and execute permissions
206 to the file's \helpref{User and Group}{wxtarentryunamegname} and to others.
207 Symbols are defined for them in <wx/file.h>.
208
209 \begin{verbatim}
210 #define wxS_IRUSR 00400
211 #define wxS_IWUSR 00200
212 #define wxS_IXUSR 00100
213
214 #define wxS_IRGRP 00040
215 #define wxS_IWGRP 00020
216 #define wxS_IXGRP 00010
217
218 #define wxS_IROTH 00004
219 #define wxS_IWOTH 00002
220 #define wxS_IXOTH 00001
221
222 \end{verbatim}
223
224
225 \membersection{wxTarEntry::Get/SetSize}\label{wxtarentrysize}
226
227 \func{void}{SetSize}{\param{wxFileOffset }{size}}
228
229 \constfunc{wxFileOffset}{GetSize}{\void}
230
231 The size of the entry's data in bytes.
232
233 The tar archive format stores the entry's size ahead of the entry's data.
234 Therefore when creating an archive on a non-seekable stream it is necessary to
235 supply the correct size when each entry is created. For seekable streams this
236 is not necessary as \helpref{wxTarOutputStream}{wxtaroutputstream} will attempt
237 to seek back and fix the entry's header when the entry is closed, though it is
238 still more efficient if the size is given beforehand.
239
240
241 \membersection{wxTarEntry::Get/SetTypeFlag}\label{wxtarentrytypeflag}
242
243 \constfunc{int}{GetTypeFlag}{\void}
244
245 \func{void}{SetTypeFlag}{\param{int }{type}}
246
247 Returns the type of the entry. It should be one of the following:
248
249 \begin{verbatim}
250 // TypeFlag values
251 enum {
252 wxTAR_REGTYPE = '0', // regular file
253 wxTAR_LNKTYPE = '1', // hard link
254 wxTAR_SYMTYPE = '2', // symbolic link
255 wxTAR_CHRTYPE = '3', // character special
256 wxTAR_BLKTYPE = '4', // block special
257 wxTAR_DIRTYPE = '5', // directory
258 wxTAR_FIFOTYPE = '6', // named pipe
259 wxTAR_CONTTYPE = '7' // contiguous file
260 };
261
262 \end{verbatim}
263
264 When creating archives use just these values. When reading archives
265 any other values should be treated as {\it wxTAR\_REGTYPE}.
266
267
268 \membersection{wxTarEntry::operator=}\label{wxtarentryoperatorassign}
269
270 \func{wxTarEntry\& operator}{operator=}{\param{const wxTarEntry\& }{entry}}
271
272 Assignment operator.
273
274
275 %
276 % automatically generated by HelpGen $Revision$ from
277 % wx/tarstrm.h at 28/Oct/06 18:27:02
278 %
279
280 \section{\class{wxTarInputStream}}\label{wxtarinputstream}
281
282 Input stream for reading tar files.
283
284 \helpref{GetNextEntry()}{wxtarinputstreamgetnextentry} returns an
285 \helpref{wxTarEntry}{wxtarentry} object containing the meta-data
286 for the next entry in the tar (and gives away ownership). Reading from
287 the wxTarInputStream then returns the entry's data. Eof() becomes true
288 after an attempt has been made to read past the end of the entry's data.
289 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
290
291 Tar entries are seekable if the parent stream is seekable. In practice this
292 usually means they are only seekable if the tar is stored as a local file and
293 is not compressed.
294
295 \wxheading{Derived from}
296
297 \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
298 \helpref{wxFilterInputStream}{wxfilterinputstream}\\
299 \helpref{wxInputStream}{wxinputstream}\\
300 \helpref{wxStreamBase}{wxstreambase}
301
302 \wxheading{Include files}
303
304 <wx/tarstrm.h>
305
306 \wxheading{Library}
307
308 \helpref{wxBase}{librarieslist}
309
310 \wxheading{Data structures}
311 \begin{verbatim}
312 typedef wxTarEntry entry_type
313 \end{verbatim}
314
315 \helpref{Archive formats such as zip}{wxarc}\\
316 \helpref{wxTarEntry}{wxtarentry}\\
317 \helpref{wxTarOutputStream}{wxtaroutputstream}
318
319 \latexignore{\rtfignore{\wxheading{Members}}}
320
321
322 \membersection{wxTarInputStream::wxTarInputStream}\label{wxtarinputstreamwxtarinputstream}
323
324 \func{}{wxTarInputStream}{\param{wxInputStream\& }{stream}, \param{wxMBConv\& }{conv = wxConvLocal}}
325
326 \func{}{wxTarInputStream}{\param{wxInputStream* }{stream}, \param{wxMBConv\& }{conv = wxConvLocal}}
327
328 Constructor. In a Unicode build the second parameter {\it conv} is
329 used to translate fields from the standard tar header into Unicode. It has
330 no effect on the stream's data. {\it conv} is only used for the standard
331 tar headers, any pax extended headers are always UTF-8 encoded.
332
333 If the parent stream is passed as a pointer then the new filter stream
334 takes ownership of it. If it is passed by reference then it does not.
335
336
337 \membersection{wxTarInputStream::CloseEntry}\label{wxtarinputstreamcloseentry}
338
339 \func{bool}{CloseEntry}{\void}
340
341 Closes the current entry. On a non-seekable stream reads to the end of
342 the current entry first.
343
344
345 \membersection{wxTarInputStream::GetNextEntry}\label{wxtarinputstreamgetnextentry}
346
347 \func{wxTarEntry*}{GetNextEntry}{\void}
348
349 Closes the current entry if one is open, then reads the meta-data for
350 the next entry and returns it in a \helpref{wxTarEntry}{wxtarentry}
351 object, giving away ownership. The stream is then open and can be read.
352
353
354 \membersection{wxTarInputStream::OpenEntry}\label{wxtarinputstreamopenentry}
355
356 \func{bool}{OpenEntry}{\param{wxTarEntry\& }{entry}}
357
358 Closes the current entry if one is open, then opens the entry specified
359 by the {\it entry} object.
360
361 {\it entry} should be from the same tar file, and the tar should
362 be on a seekable stream.
363
364 \wxheading{See also}
365
366 \helpref{Looking up an archive entry by name}{wxarcbyname}
367
368
369 %
370 % automatically generated by HelpGen $Revision$ from
371 % wx/tarstrm.h at 28/Oct/06 18:27:02
372 %
373
374 \section{\class{wxTarOutputStream}}\label{wxtaroutputstream}
375
376 Output stream for writing tar files.
377
378 \helpref{PutNextEntry()}{wxtaroutputstreamputnextentry} is used to create
379 a new entry in the output tar, then the entry's data is written to the
380 wxTarOutputStream. Another call to PutNextEntry() closes the current
381 entry and begins the next.
382
383 \wxheading{Derived from}
384
385 \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}\\
386 \helpref{wxFilterOutputStream}{wxfilteroutputstream}\\
387 \helpref{wxOutputStream}{wxoutputstream}\\
388 \helpref{wxStreamBase}{wxstreambase}
389
390 \wxheading{Include files}
391
392 <wx/tarstrm.h>
393
394 \wxheading{Library}
395
396 \helpref{wxBase}{librarieslist}
397
398 \wxheading{Data structures}
399
400 Constants for the {\it format} parameter of the
401 \helpref{constructor}{wxtaroutputstreamwxtaroutputstream}.
402
403 \begin{verbatim}
404 // Archive Formats (use wxTAR_PAX, it's backward compatible)
405 enum wxTarFormat
406 {
407 wxTAR_USTAR, // POSIX.1-1990 tar format
408 wxTAR_PAX // POSIX.1-2001 tar format
409 };
410
411 \end{verbatim}
412
413 \wxheading{See also}
414
415 \helpref{Archive formats such as zip}{wxarc}\\
416 \helpref{wxTarEntry}{wxtarentry}\\
417 \helpref{wxTarInputStream}{wxtarinputstream}
418
419
420 \latexignore{\rtfignore{\wxheading{Members}}}
421
422
423 \membersection{wxTarOutputStream::wxTarOutputStream}\label{wxtaroutputstreamwxtaroutputstream}
424
425 \func{}{wxTarOutputStream}{\param{wxOutputStream\& }{stream}, \param{wxTarFormat }{format = wxTAR\_PAX}, \param{wxMBConv\& }{conv = wxConvLocal}}
426
427 \func{}{wxTarOutputStream}{\param{wxOutputStream* }{stream}, \param{wxTarFormat }{format = wxTAR\_PAX}, \param{wxMBConv\& }{conv = wxConvLocal}}
428
429 If the parent stream is passed as a pointer then the new filter stream
430 takes ownership of it. If it is passed by reference then it does not.
431
432 In a Unicode build the third parameter {\it conv} is used to translate the
433 headers fields into an 8-bit encoding. It has no effect on the stream's data.
434
435 When the {\it format} is {\it wxTAR\_PAX}, pax extended headers are generated
436 when any header field will not fit the standard tar header block or if it
437 uses any non-ascii characters.
438
439 Extended headers are stored as extra 'files' within the tar, and will be
440 extracted as such by any other tar program that does not understand them.
441 The {\it conv} parameter only affect the standard tar headers, the extended
442 headers are always UTF-8 encoded.
443
444 When the {\it format} is {\it wxTAR\_USTAR}, no extended headers are
445 generated, and instead a warning message is logged if any header field
446 overflows.
447
448
449 \membersection{wxTarOutputStream::\destruct{wxTarOutputStream}}\label{wxtaroutputstreamdtor}
450
451 \func{}{\destruct{wxTarOutputStream}}{\void}
452
453 The destructor calls \helpref{Close()}{wxtaroutputstreamclose} to finish
454 writing the tar if it has not been called already.
455
456
457 \membersection{wxTarOutputStream::Close}\label{wxtaroutputstreamclose}
458
459 \func{bool}{Close}{\void}
460
461 Finishes writing the tar, returning true if successful.
462 Called by the destructor if not called explicitly.
463
464
465 \membersection{wxTarOutputStream::CloseEntry}\label{wxtaroutputstreamcloseentry}
466
467 \func{bool}{CloseEntry}{\void}
468
469 Close the current entry. It is called implicitly whenever another new
470 entry is created with \helpref{CopyEntry()}{wxtaroutputstreamcopyentry}
471 or \helpref{PutNextEntry()}{wxtaroutputstreamputnextentry}, or
472 when the tar is closed.
473
474
475 \membersection{wxTarOutputStream::CopyArchiveMetaData}\label{wxtaroutputstreamcopyarchivemetadata}
476
477 \func{bool}{CopyArchiveMetaData}{\param{wxTarInputStream\& }{s}}
478
479 See \helpref{wxArchiveOutputStream::CopyArchiveMetaData}{wxarchiveoutputstreamcopyarchivemetadata}.
480 For the tar format this function does nothing.
481
482
483 \membersection{wxTarOutputStream::CopyEntry}\label{wxtaroutputstreamcopyentry}
484
485 \func{bool}{CopyEntry}{\param{wxTarEntry* }{entry}, \param{wxTarInputStream\& }{inputStream}}
486
487 Takes ownership of {\it entry} and uses it to create a new entry
488 in the tar. {\it entry} is then opened in {\it inputStream} and its contents
489 copied to this stream.
490
491 For some other archive formats CopyEntry() is much more efficient than
492 transferring the data using Read() and Write() since it will copy them
493 without decompressing and recompressing them. For tar however it makes
494 no difference.
495
496 For tars on seekable streams, {\it entry} must be from the same tar file
497 as {\it stream}. For non-seekable streams, {\it entry} must also be the
498 last thing read from {\it inputStream}.
499
500
501 \membersection{wxTarOutputStream::Get/SetBlockingFactor}\label{wxtaroutputstreamblockingfactor}
502
503 \constfunc{int}{GetBlockingFactor}{\void}
504
505 \func{void}{SetBlockingFactor}{\param{int }{factor}}
506
507 The tar is zero padded to round its size up to {\it BlockingFactor * 512} bytes.
508
509 Defaults to 10 for {\it wxTAR\_PAX} and 20 for {\it wxTAR\_USTAR}
510 (see the \helpref{constructor}{wxtaroutputstreamwxtaroutputstream}), as
511 specified in the POSIX standards.
512
513
514 \membersection{wxTarOutputStream::PutNextDirEntry}\label{wxtaroutputstreamputnextdirentry}
515
516 \func{bool}{PutNextDirEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}}
517
518 Create a new directory entry
519 (see \helpref{wxArchiveEntry::IsDir()}{wxarchiveentryisdir})
520 with the given name and timestamp.
521
522 \helpref{PutNextEntry()}{wxtaroutputstreamputnextentry} can
523 also be used to create directory entries, by supplying a name with
524 a trailing path separator.
525
526
527 \membersection{wxTarOutputStream::PutNextEntry}\label{wxtaroutputstreamputnextentry}
528
529 \func{bool}{PutNextEntry}{\param{wxTarEntry* }{entry}}
530
531 Takes ownership of {\it entry} and uses it to create a new entry
532 in the tar.
533
534 \func{bool}{PutNextEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}, \param{wxFileOffset }{size = wxInvalidOffset}}
535
536 Create a new entry with the given name, timestamp and size.
537