physfs_internal.h
changeset 15 418eacc97ac8
parent 12 a4041c91d715
child 19 a0279b57398c
equal deleted inserted replaced
14:7d822f0d5f57 15:418eacc97ac8
    12 
    12 
    13 #ifndef __PHYSICSFS_INTERNAL__
    13 #ifndef __PHYSICSFS_INTERNAL__
    14 #error Do not include this header from your applications.
    14 #error Do not include this header from your applications.
    15 #endif
    15 #endif
    16 
    16 
    17 struct __PHYSFS_DIRREADER__;
    17 struct __PHYSFS_DIRHANDLE__;
    18 struct __PHYSFS_FILEFUNCTIONS__;
    18 struct __PHYSFS_FILEFUNCTIONS__;
    19 
    19 
    20 typedef struct __PHYSFS_FILEHANDLE__
    20 typedef struct __PHYSFS_FILEHANDLE__
    21 {
    21 {
    22         /*
    22         /*
    25     void *opaque;
    25     void *opaque;
    26 
    26 
    27         /*
    27         /*
    28          * This should be the DirHandle that created this FileHandle.
    28          * This should be the DirHandle that created this FileHandle.
    29          */
    29          */
    30     const struct __PHYSFS_DIRREADER__ *dirReader;
    30     const struct __PHYSFS_DIRHANDLE__ *dirHandle;
    31 
    31 
    32         /*
    32         /*
    33          * Pointer to the file i/o functions for this filehandle.
    33          * Pointer to the file i/o functions for this filehandle.
    34          */
    34          */
    35     const struct __PHYSFS_FILEFUNCTIONS__ *funcs;
    35     const struct __PHYSFS_FILEFUNCTIONS__ *funcs;
    38 
    38 
    39 typedef struct __PHYSFS_FILEFUNCTIONS__
    39 typedef struct __PHYSFS_FILEFUNCTIONS__
    40 {
    40 {
    41         /*
    41         /*
    42          * Read more from the file.
    42          * Read more from the file.
       
    43          * Returns number of objects of (objSize) bytes read from file, -1
       
    44          *  if complete failure.
       
    45          * On failure, call __PHYSFS_setError().
    43          */
    46          */
    44     int (*read)(FileHandle *handle, void *buffer,
    47     int (*read)(FileHandle *handle, void *buffer,
    45                 unsigned int objSize, unsigned int objCount);
    48                 unsigned int objSize, unsigned int objCount);
    46 
    49 
    47         /*
    50         /*
    48          * Write more to the file. Archives don't have to implement this.
    51          * Write more to the file. Archives don't have to implement this.
    49          *  (Set it to NULL if not implemented).
    52          *  (Set it to NULL if not implemented).
       
    53          * Returns number of objects of (objSize) bytes written to file, -1
       
    54          *  if complete failure.
       
    55          * On failure, call __PHYSFS_setError().
    50          */
    56          */
    51     int (*write)(FileHandle *handle, void *buffer,
    57     int (*write)(FileHandle *handle, void *buffer,
    52                  unsigned int objSize, unsigned int objCount);
    58                  unsigned int objSize, unsigned int objCount);
    53 
    59 
    54         /*
    60         /*
    62     int (*tell)(FileHandle *handle);
    68     int (*tell)(FileHandle *handle);
    63 
    69 
    64         /*
    70         /*
    65          * Move read/write pointer to byte offset from start of file.
    71          * Move read/write pointer to byte offset from start of file.
    66          *  Returns non-zero on success, zero on error.
    72          *  Returns non-zero on success, zero on error.
       
    73          * On failure, call __PHYSFS_setError().
    67          */
    74          */
    68     int (*seek)(FileHandle *handle, int offset);
    75     int (*seek)(FileHandle *handle, int offset);
    69 
    76 
    70         /*
    77         /*
    71          * Close the file, and free the FileHandle structure (including "opaque").
    78          * Close the file, and free the FileHandle structure (including "opaque").
       
    79          *  returns non-zero on success, zero if can't close file.
       
    80          * On failure, call __PHYSFS_setError().
    72          */
    81          */
    73     int (*close)(FileHandle *handle);
    82     int (*close)(FileHandle *handle);
    74 } FileFunctions;
    83 } FileFunctions;
    75 
    84 
    76 
    85 
    77 typedef struct __PHYSFS_DIRREADER__
    86 typedef struct __PHYSFS_DIRHANDLE__
    78 {
    87 {
    79         /*
    88         /*
    80          * This is reserved for the driver to store information.
    89          * This is reserved for the driver to store information.
    81          */
    90          */
    82     void *opaque;
    91     void *opaque;
    83 
    92 
    84         /*
    93         /*
    85          * Pointer to the directory i/o functions for this reader.
    94          * Pointer to the directory i/o functions for this handle.
    86          */
    95          */
    87     const struct __PHYSFS_DIRFUNCTIONS__ *funcs;
    96     const struct __PHYSFS_DIRFUNCTIONS__ *funcs;
    88 } DirHandle;
    97 } DirHandle;
    89 
    98 
    90 
    99 
   102 typedef struct __PHYSFS_DIRFUNCTIONS__
   111 typedef struct __PHYSFS_DIRFUNCTIONS__
   103 {
   112 {
   104         /*
   113         /*
   105          * Returns non-zero if (filename) is a valid archive that this
   114          * Returns non-zero if (filename) is a valid archive that this
   106          *  driver can handle. This filename is in platform-dependent
   115          *  driver can handle. This filename is in platform-dependent
   107          *  notation.
   116          *  notation. forWriting is non-zero if this is to be used for
   108          */
   117          *  the write directory, and zero if this is to be used for an
   109     int (*isArchive)(const char *filename);
   118          *  element of the search path.
       
   119          */
       
   120     int (*isArchive)(const char *filename, int forWriting);
   110 
   121 
   111         /*
   122         /*
   112          * Return a DirHandle for dir/archive (name).
   123          * Return a DirHandle for dir/archive (name).
   113          *  This filename is in platform-dependent notation.
   124          *  This filename is in platform-dependent notation.
   114          *  return (NULL) on error.
   125          *  forWriting is non-zero if this is to be used for
   115          */
   126          *  the write directory, and zero if this is to be used for an
   116     DirHandle *(*openArchive)(const char *name);
   127          *  element of the search path.
       
   128          * Returns NULL on failure, and calls __PHYSFS_setError().
       
   129          */
       
   130     DirHandle *(*openArchive)(const char *name, int forWriting);
   117 
   131 
   118         /*
   132         /*
   119          * Returns a list of all files in dirname. Each element of this list
   133          * Returns a list of all files in dirname. Each element of this list
   120          *  (and its "str" field) will be deallocated with the system's free()
   134          *  (and its "str" field) will be deallocated with the system's free()
   121          *  function by the caller, so be sure to explicitly malloc() each
   135          *  function by the caller, so be sure to explicitly malloc() each
   122          *  chunk.
   136          *  chunk.
   123          * If you have a memory failure, return as much as you can.
   137          * If you have a memory failure, return as much as you can.
   124          *  This dirname is in platform-independent notation.
   138          *  This dirname is in platform-independent notation.
   125          */
   139          */
   126     LinkedStringList **(*enumerateFiles)(DirHandle *r, const char *dirname);
   140     LinkedStringList *(*enumerateFiles)(DirHandle *r, const char *dirname);
       
   141 
       
   142         /*
       
   143          * Returns non-zero if filename can be opened for reading.
       
   144          *  This filename is in platform-independent notation.
       
   145          */
       
   146     int (*exists)(DirHandle *r, const char *name);
   127 
   147 
   128         /*
   148         /*
   129          * Returns non-zero if filename is really a directory.
   149          * Returns non-zero if filename is really a directory.
   130          *  This filename is in platform-independent notation.
   150          *  This filename is in platform-independent notation.
   131          */
   151          */
   136          *  This filename is in platform-independent notation.
   156          *  This filename is in platform-independent notation.
   137          */
   157          */
   138     int (*isSymLink)(DirHandle *r, const char *name);
   158     int (*isSymLink)(DirHandle *r, const char *name);
   139 
   159 
   140         /*
   160         /*
   141          * Returns non-zero if filename can be opened for reading.
       
   142          *  This filename is in platform-independent notation.
       
   143          */
       
   144     int (*isOpenable)(DirHandle *r, const char *name);
       
   145 
       
   146         /*
       
   147          * Open file for reading, and return a FileHandle.
   161          * Open file for reading, and return a FileHandle.
   148          *  This filename is in platform-independent notation.
   162          *  This filename is in platform-independent notation.
       
   163          * If you can't handle multiple opens of the same file,
       
   164          *  you can opt to fail for the second call.
       
   165          * Returns NULL on failure, and calls __PHYSFS_setError().
   149          */
   166          */
   150     FileHandle *(*openRead)(DirHandle *r, const char *filename);
   167     FileHandle *(*openRead)(DirHandle *r, const char *filename);
   151 
   168 
   152         /*
   169         /*
   153          * Open file for writing, and return a FileHandle.
   170          * Open file for writing, and return a FileHandle.
   154          *  This filename is in platform-independent notation.
   171          *  This filename is in platform-independent notation.
   155          *  This method may be NULL.
   172          *  This method may be NULL.
       
   173          * If you can't handle multiple opens of the same file,
       
   174          *  you can opt to fail for the second call.
       
   175          * Returns NULL on failure, and calls __PHYSFS_setError().
   156          */
   176          */
   157     FileHandle *(*openWrite)(DirHandle *r, const char *filename);
   177     FileHandle *(*openWrite)(DirHandle *r, const char *filename);
   158 
   178 
   159         /*
   179         /*
   160          * Open file for appending, and return a FileHandle.
   180          * Open file for appending, and return a FileHandle.
   161          *  This filename is in platform-independent notation.
   181          *  This filename is in platform-independent notation.
   162          *  This method may be NULL.
   182          *  This method may be NULL.
       
   183          * If you can't handle multiple opens of the same file,
       
   184          *  you can opt to fail for the second call.
       
   185          * Returns NULL on failure, and calls __PHYSFS_setError().
   163          */
   186          */
   164     FileHandle *(*openAppend)(DirHandle *r, const char *filename);
   187     FileHandle *(*openAppend)(DirHandle *r, const char *filename);
       
   188 
       
   189         /*
       
   190          * Delete a file in the archive/directory.
       
   191          *  Return non-zero on success, zero on failure.
       
   192          *  This filename is in platform-independent notation.
       
   193          *  This method may be NULL.
       
   194          * On failure, call __PHYSFS_setError().
       
   195          */
       
   196     int (*remove)(DirHandle *r, const char *filename);
       
   197 
       
   198         /*
       
   199          * Create a directory in the archive/directory.
       
   200          *  If the application is trying to make multiple dirs, PhysicsFS
       
   201          *  will split them up into multiple calls before passing them to
       
   202          *  your driver.
       
   203          *  Return non-zero on success, zero on failure.
       
   204          *  This filename is in platform-independent notation.
       
   205          *  This method may be NULL.
       
   206          * On failure, call __PHYSFS_setError().
       
   207          */
       
   208     int (*mkdir)(DirHandle *r, const char *filename);
   165 
   209 
   166         /*
   210         /*
   167          * Close directories/archives, and free the handle, including
   211          * Close directories/archives, and free the handle, including
   168          *  the "opaque" entry. This should assume that it won't be called if
   212          *  the "opaque" entry. This should assume that it won't be called if
   169          *  there are still files open from this DirHandle.
   213          *  there are still files open from this DirHandle.
   174 
   218 
   175 /* error messages... */
   219 /* error messages... */
   176 #define ERR_IS_INITIALIZED       "Already initialized"
   220 #define ERR_IS_INITIALIZED       "Already initialized"
   177 #define ERR_NOT_INITIALIZED      "Not initialized"
   221 #define ERR_NOT_INITIALIZED      "Not initialized"
   178 #define ERR_INVALID_ARGUMENT     "Invalid argument"
   222 #define ERR_INVALID_ARGUMENT     "Invalid argument"
   179 #define ERR_FILES_OPEN_READ      "Files still open for reading"
   223 #define ERR_FILES_STILL_OPEN     "Files still open"
   180 #define ERR_FILES_OPEN_WRITE     "Files still open for writing"
       
   181 #define ERR_NO_DIR_CREATE        "Failed to create directories"
   224 #define ERR_NO_DIR_CREATE        "Failed to create directories"
   182 #define ERR_OUT_OF_MEMORY        "Out of memory"
   225 #define ERR_OUT_OF_MEMORY        "Out of memory"
   183 #define ERR_NOT_IN_SEARCH_PATH   "No such entry in search path"
   226 #define ERR_NOT_IN_SEARCH_PATH   "No such entry in search path"
   184 #define ERR_NOT_SUPPORTED        "Operation not supported"
   227 #define ERR_NOT_SUPPORTED        "Operation not supported"
   185 #define ERR_UNSUPPORTED_ARCHIVE  "Archive type unsupported"
   228 #define ERR_UNSUPPORTED_ARCHIVE  "Archive type unsupported"
       
   229 #define ERR_NOT_A_HANDLE         "Not a file handle"
       
   230 #define ERR_INSECURE_FNAME       "Insecure filename"
       
   231 #define ERR_SYMLINK_DISALLOWED   "Symbolic links are disabled"
       
   232 #define ERR_NO_WRITE_DIR         "Write directory is not set"
   186 
   233 
   187 
   234 
   188 /*
   235 /*
   189  * Call this to set the message returned by PHYSFS_getLastError().
   236  * Call this to set the message returned by PHYSFS_getLastError().
   190  *  Please only use the ERR_* constants above, or add new constants to the
   237  *  Please only use the ERR_* constants above, or add new constants to the
   191  *  above group, but I want these all in one place.
   238  *  above group, but I want these all in one place.
       
   239  *
       
   240  * Calling this with a NULL argument is a safe no-op.
   192  */
   241  */
   193 void __PHYSFS_setError(const char *err);
   242 void __PHYSFS_setError(const char *err);
   194 
   243 
   195 
   244 
       
   245 /*
       
   246  * Convert (dirName) to platform-dependent notation, then prepend (prepend)
       
   247  *  and append (append) to the converted string.
       
   248  *
       
   249  *  So, on Win32, calling:
       
   250  *     __PHYSFS_convertToDependentNotation("C:\", "my/files", NULL);
       
   251  *  ...will return the string "C:\my\files".
       
   252  *
       
   253  * This is a convenience function; you might want to hack something out that
       
   254  *  is less generic (and therefore more efficient).
       
   255  *
       
   256  * Be sure to free() the return value when done with it.
       
   257  */
       
   258 char *__PHYSFS_convertToDependentNotation(const char *prepend,
       
   259                                           const char *dirName,
       
   260                                           const char *append);
       
   261 
       
   262 /*
       
   263  * Verify that (fname) (in platform-independent notation), in relation
       
   264  *  to (h) is secure. That means that each element of fname is checked
       
   265  *  for symlinks (if they aren't permitted). Also, elements such as
       
   266  *  ".", "..", or ":" are flagged.
       
   267  *
       
   268  * Returns non-zero if string is safe, zero if there's a security issue.
       
   269  *  PHYSFS_getLastError() will specify what was wrong.
       
   270  */
       
   271 int __PHYSFS_verifySecurity(DirHandle *h, const char *fname);
       
   272 
       
   273 
   196 /* This gets used all over for lessening code clutter. */
   274 /* This gets used all over for lessening code clutter. */
   197 #define BAIL_IF_MACRO(c, e, r) if (c) { __PHYSFS_setError(e); return(r); }
   275 #define BAIL_IF_MACRO(c, e, r) if (c) { __PHYSFS_setError(e); return r; }
   198 
   276 
   199 
   277 
   200 
   278 
   201 
   279 
   202 /*--------------------------------------------------------------------------*/
   280 /*--------------------------------------------------------------------------*/
   212 
   290 
   213 /*
   291 /*
   214  * The dir separator; "/" on unix, "\\" on win32, ":" on MacOS, etc...
   292  * The dir separator; "/" on unix, "\\" on win32, ":" on MacOS, etc...
   215  *  Obviously, this isn't a function, but it IS a null-terminated string.
   293  *  Obviously, this isn't a function, but it IS a null-terminated string.
   216  */
   294  */
   217 extern const char *__PHYSFS_PlatformDirSeparator;
   295 extern const char *__PHYSFS_platformDirSeparator;
   218 
   296 
   219 /*
   297 /*
   220  * Platform implementation of PHYSFS_getCdRomDirs()...
   298  * Platform implementation of PHYSFS_getCdRomDirs()...
   221  *  See physfs.h. The retval should be freeable via PHYSFS_freeList().
   299  *  See physfs.h. The retval should be freeable via PHYSFS_freeList().
   222  */
   300  */
   260 /*
   338 /*
   261  * Return non-zero if filename (in platform-dependent notation) is a symlink.
   339  * Return non-zero if filename (in platform-dependent notation) is a symlink.
   262  */
   340  */
   263 int __PHYSFS_platformIsSymlink(const char *fname);
   341 int __PHYSFS_platformIsSymlink(const char *fname);
   264 
   342 
       
   343 /*
       
   344  * Return non-zero if filename (in platform-dependent notation) is a symlink.
       
   345  */
       
   346 int __PHYSFS_platformIsDirectory(const char *fname);
       
   347 
   265 
   348 
   266 #ifdef __cplusplus
   349 #ifdef __cplusplus
   267 extern "C" {
   350 extern "C" {
   268 #endif
   351 #endif
   269 
   352