VirtualBox

Changeset 50194 in vbox for trunk/include


Ignore:
Timestamp:
Jan 23, 2014 5:52:28 PM (11 years ago)
Author:
vboxsync
Message:

tar.cpp: Stripped it futher down and documented what RTTarOpenCurrentFile actually need to do, simplifying the weird stuff that it used to do. You can only open the current file once now.

Location:
trunk/include/iprt
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/mangling.h

    r50154 r50194  
    14971497# define RTSystemShutdown                               RT_MANGLER(RTSystemShutdown)
    14981498# define RTTarClose                                     RT_MANGLER(RTTarClose)
    1499 # define RTTarCreate                                    RT_MANGLER(RTTarCreate)
    15001499# define RTTarCurrentFile                               RT_MANGLER(RTTarCurrentFile)
    15011500# define RTTarFileClose                                 RT_MANGLER(RTTarFileClose)
    … …  
    15031502# define RTTarFileOpen                                  RT_MANGLER(RTTarFileOpen)
    15041503# define RTTarFileOpenCurrentFile                       RT_MANGLER(RTTarFileOpenCurrentFile)
    1505 # define RTTarFileRead                                  RT_MANGLER(RTTarFileRead)
    15061504# define RTTarFileReadAt                                RT_MANGLER(RTTarFileReadAt)
    1507 # define RTTarFileSeek                                  RT_MANGLER(RTTarFileSeek)
    1508 # define RTTarFileSetMode                               RT_MANGLER(RTTarFileSetMode)
    1509 # define RTTarFileSetOwner                              RT_MANGLER(RTTarFileSetOwner)
    15101505# define RTTarFileSetSize                               RT_MANGLER(RTTarFileSetSize)
    1511 # define RTTarFileSetTime                               RT_MANGLER(RTTarFileSetTime)
    1512 # define RTTarFileTell                                  RT_MANGLER(RTTarFileTell)
    1513 # define RTTarFileWrite                                 RT_MANGLER(RTTarFileWrite)
    15141506# define RTTarFileWriteAt                               RT_MANGLER(RTTarFileWriteAt)
    1515 # define RTTarList                                      RT_MANGLER(RTTarList)
    15161507# define RTTarOpen                                      RT_MANGLER(RTTarOpen)
    15171508# define RTTarSeekNextFile                              RT_MANGLER(RTTarSeekNextFile)

  • trunk/include/iprt/tar.h

    r50154 r50194  
    44
    55/*
    6  * Copyright (C) 2009-2010 Oracle Corporation
     6 * Copyright (C) 2009-2014 Oracle Corporation
    77 *
    88 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    3535/** @defgroup grp_rt_tar    RTTar - Tar archive I/O
    3636 * @ingroup grp_rt
     37 *
     38 * @deprecated  Only used for legacy code and writing.  Migrate new code to the
     39 *              VFS interface, add the write part when needed.
     40 *
    3741 * @{
    3842 */
    … …  
    7781RTR3DECL(int) RTTarOpen(PRTTAR phTar, const char *pszTarname, uint32_t fMode, bool fStream);
    7882
    79 #if 0
    80 /**
    81  * Opens a Tar archive by handle.
    82  *
    83  * Use the mask to specify the access type. In create mode the target file
    84  * have not to exists.
    85  *
    86  * @returns IPRT status code.
    87  *
    88  * @param   phTar          Where to store the RTTAR handle.
    89  * @param   hFile          The file handle of the tar file.  This is expected
    90  *                         to be a regular file at the moment.
    91  * @param   fStream        Open the file in stream mode. Within this mode no
    92  *                         seeking is allowed.  Use this together with
    93  *                         RTTarFileCurrent, RTTarFileOpenCurrent,
    94  *                         RTTarFileSeekNextFile and the read method to
    95  *                         sequential read a tar file.  Currently ignored with
    96  *                         RTFILE_O_WRITE.
    97  */
    98 RTR3DECL(int) RTTarOpenByHandle(PRTTAR phTar, RTFILE hFile, uint32_t fMode, bool fStream);
    99 #endif
    100 
    10183/**
    10284 * Close the Tar archive.
    … …  
    10789 */
    10890RTR3DECL(int) RTTarClose(RTTAR hTar);
     91
     92/**
     93 * Jumps to the next file from the current RTTar position.
     94 *
     95 * @returns IPRT status code.
     96 *
     97 * @param   hTar           Handle to the RTTAR interface.
     98 */
     99RTR3DECL(int) RTTarSeekNextFile(RTTAR hTar);
     100
     101/**
     102 * Return the filename where RTTar currently stays at.
     103 *
     104 * @returns IPRT status code.
     105 *
     106 * @param   hTar           Handle to the RTTAR interface.
     107 * @param   ppszFilename   On success the filename.
     108 */
     109RTR3DECL(int) RTTarCurrentFile(RTTAR hTar, char **ppszFilename);
     110
     111/**
     112 * Opens the file where RTTar currently stays at.
     113 *
     114 * The current file can only be opened once.  The next call will open the next
     115 * file, implicitly calling RTTarSeekNextFile().
     116 *
     117 * @returns IPRT status code.
     118 *
     119 * @param   hTar           Handle to the RTTAR interface.
     120 * @param   phFile         Where to store the handle to the opened file.
     121 * @param   ppszFilename   On success the filename.
     122 * @param   fOpen          Open flags, i.e a combination of the RTFILE_O_* defines.
     123 *                         The ACCESS, ACTION flags are mandatory! Currently
     124 *                         only RTFILE_O_OPEN | RTFILE_O_READ is supported.
     125 */
     126RTR3DECL(int) RTTarFileOpenCurrentFile(RTTAR hTar, PRTTARFILE phFile, char **ppszFilename, uint32_t fOpen);
    109127
    110128/**
    … …  
    139157
    140158/**
    141  * Changes the read & write position in a file.
    142  *
    143  * @returns IPRT status code.
    144  *
    145  * @param   hFile          Handle to the file.
    146  * @param   offSeek        Offset to seek.
    147  * @param   uMethod        Seek method, i.e. one of the RTFILE_SEEK_* defines.
    148  * @param   poffActual     Where to store the new file position.
    149  *                         NULL is allowed.
    150  */
    151 RTR3DECL(int) RTTarFileSeek(RTTARFILE hFile, uint64_t offSeek, unsigned uMethod, uint64_t *poffActual);
    152 
    153 /**
    154  * Gets the current file position.
    155  *
    156  * @returns File offset.
    157  * @returns UINT64_MAX on failure.
    158  *
    159  * @param   hFile          Handle to the file.
    160  */
    161 RTR3DECL(uint64_t) RTTarFileTell(RTTARFILE hFile);
    162 
    163 /**
    164  * Read bytes from a file.
    165  *
    166  * @returns IPRT status code.
    167  *
    168  * @param   hFile          Handle to the file.
    169  * @param   pvBuf          Where to put the bytes we read.
    170  * @param   cbToRead       How much to read.
    171  * @param   *pcbRead       How much we actually read .
    172  *                         If NULL an error will be returned for a partial read.
    173  */
    174 RTR3DECL(int) RTTarFileRead(RTTARFILE hFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
    175 
    176 /**
    177159 * Read bytes from a file at a given offset.
    178160 * This function may modify the file position.
    … …  
    184166 * @param   pvBuf          Where to put the bytes we read.
    185167 * @param   cbToRead       How much to read.
    186  * @param   *pcbRead       How much we actually read .
    187  *                         If NULL an error will be returned for a partial read.
     168 * @param   pcbRead        Where to return how much we actually read.  If NULL
     169 *                         an error will be returned for a partial read.
    188170 */
    189171RTR3DECL(int) RTTarFileReadAt(RTTARFILE hFile, uint64_t off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
    190 
    191 /**
    192  * Write bytes to a file.
    193  *
    194  * @returns IPRT status code.
    195  *
    196  * @param   hFile          Handle to the file.
    197  * @param   pvBuf          What to write.
    198  * @param   cbToWrite      How much to write.
    199  * @param   *pcbWritten    How much we actually wrote.
    200  *                         If NULL an error will be returned for a partial write.
    201  */
    202 RTR3DECL(int) RTTarFileWrite(RTTARFILE hFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
    203172
    204173/**
    … …  
    212181 * @param   pvBuf          What to write.
    213182 * @param   cbToWrite      How much to write.
    214  * @param   *pcbWritten    How much we actually wrote.
    215  *                         If NULL an error will be returned for a partial write.
     183 * @param   pcbWritten     Where to return how much we actually wrote.  If NULL
     184 *                         an error will be returned for a partial write.
    216185 */
    217186RTR3DECL(int) RTTarFileWriteAt(RTTARFILE hFile, uint64_t off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
    … …  
    237206RTR3DECL(int) RTTarFileSetSize(RTTARFILE hFile, uint64_t cbSize);
    238207
    239 /**
    240  * Changes the mode flags of an open file.
    241  *
    242  * @returns IPRT status code.
    243  *
    244  * @param   hFile          Handle to the file.
    245  * @param   fMode          The new file mode, see @ref grp_rt_fs for details.
    246  */
    247 RTR3DECL(int) RTTarFileSetMode(RTTARFILE hFile, uint32_t fMode);
    248 
    249 /**
    250  * Sets the modification timestamp of the file.
    251  *
    252  * @returns IPRT status code.
    253  *
    254  * @param   pFile           Handle to the file.
    255  * @param   pTime           The time to store.
    256  */
    257 RTR3DECL(int) RTTarFileSetTime(RTTARFILE hFile, PRTTIMESPEC pTime);
    258 
    259 /**
    260  * Changes the owner and/or group of an open file.
    261  *
    262  * @returns IPRT status code.
    263  *
    264  * @param   hFile           Handle to the file.
    265  * @param   uid             The new file owner user id. Use -1 (or ~0) to leave this unchanged.
    266  * @param   gid             The new group id. Use -1 (or ~0) to leave this unchanged.
    267  */
    268 RTR3DECL(int) RTTarFileSetOwner(RTTARFILE hFile, uint32_t uid, uint32_t gid);
    269 
    270 /******************************************************************************
    271  *   Convenience Functions                                                    *
    272  ******************************************************************************/
    273 
    274 /**
    275  * Create a file list from a Tar archive.
    276  *
    277  * @note    Currently only regular files are supported.
    278  *
    279  * @returns IPRT status code.
    280  *
    281  * @param   pszTarFile      Tar file to list files from.
    282  * @param   ppapszFiles     On success an array with array with the filenames is
    283  *                          returned. The names must be freed with RTStrFree and
    284  *                          the array with RTMemFree.
    285  * @param   pcFiles         On success the number of entries in ppapszFiles.
    286  */
    287 RTR3DECL(int) RTTarList(const char *pszTarFile, char ***ppapszFiles, size_t *pcFiles);
    288 
    289 /**
    290  * Create a Tar archive out of the given files.
    291  *
    292  * @note Currently only regular files are supported.
    293  *
    294  * @returns IPRT status code.
    295  *
    296  * @param   pszTarFile           Where to create the Tar archive.
    297  * @param   papszFiles           Which files should be included.
    298  * @param   cFiles               The number of files in papszFiles.
    299  * @param   pfnProgressCallback  Progress callback function. Optional.
    300  * @param   pvUser               User defined data for the progress
    301  *                               callback. Optional.
    302  */
    303 RTR3DECL(int) RTTarCreate(const char *pszTarFile, const char * const *papszFiles, size_t cFiles, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
    304 
    305 /******************************************************************************
    306  *   Streaming Functions                                                      *
    307  ******************************************************************************/
    308 
    309 /**
    310  * Return the filename where RTTar currently stays at.
    311  *
    312  * @returns IPRT status code.
    313  *
    314  * @param   hTar           Handle to the RTTAR interface.
    315  * @param   ppszFilename   On success the filename.
    316  */
    317 RTR3DECL(int) RTTarCurrentFile(RTTAR hTar, char **ppszFilename);
    318 
    319 /**
    320  * Jumps to the next file from the current RTTar position.
    321  *
    322  * @returns IPRT status code.
    323  *
    324  * @param   hTar           Handle to the RTTAR interface.
    325  */
    326 RTR3DECL(int) RTTarSeekNextFile(RTTAR hTar);
    327 
    328 /**
    329  * Opens the file where RTTar currently stays at.
    330  *
    331  * @returns IPRT status code.
    332  *
    333  * @param   hTar           Handle to the RTTAR interface.
    334  * @param   phFile         Where to store the handle to the opened file.
    335  * @param   ppszFilename   On success the filename.
    336  * @param   fOpen          Open flags, i.e a combination of the RTFILE_O_* defines.
    337  *                         The ACCESS, ACTION flags are mandatory! Currently
    338  *                         only RTFILE_O_OPEN | RTFILE_O_READ is supported.
    339  */
    340 RTR3DECL(int) RTTarFileOpenCurrentFile(RTTAR hTar, PRTTARFILE phFile, char **ppszFilename, uint32_t fOpen);
    341 
    342 
    343208/** @} */
    344209
    345210RT_C_DECLS_END
    346211
    347 #endif /* ___iprt_tar_h */
    348 
     212#endif
     213
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette