physfs_internal.h
changeset 20 efdde0d21521
parent 19 a0279b57398c
child 21 b1ea58d70a56
equal deleted inserted replaced
19:a0279b57398c 20:efdde0d21521
    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_DIRHANDLE__;
    17 struct __PHYSFS_DIRHANDLE__;
    18 struct __PHYSFS_FILEFUNCTIONS__;
    18 struct __PHYSFS_FILEFUNCTIONS__;
    19 
       
    20 typedef struct __PHYSFS_FILEHANDLE__
       
    21 {
       
    22         /*
       
    23          * This is reserved for the driver to store information.
       
    24          */
       
    25     void *opaque;
       
    26 
       
    27         /*
       
    28          * This should be the DirHandle that created this FileHandle.
       
    29          */
       
    30     const struct __PHYSFS_DIRHANDLE__ *dirHandle;
       
    31 
       
    32         /*
       
    33          * Pointer to the file i/o functions for this filehandle.
       
    34          */
       
    35     const struct __PHYSFS_FILEFUNCTIONS__ *funcs;
       
    36 } FileHandle;
       
    37 
       
    38 
       
    39 typedef struct __PHYSFS_FILEFUNCTIONS__
       
    40 {
       
    41         /*
       
    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().
       
    46          */
       
    47     int (*read)(FileHandle *handle, void *buffer,
       
    48                 unsigned int objSize, unsigned int objCount);
       
    49 
       
    50         /*
       
    51          * Write more to the file. Archives don't have to implement this.
       
    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().
       
    56          */
       
    57     int (*write)(FileHandle *handle, void *buffer,
       
    58                  unsigned int objSize, unsigned int objCount);
       
    59 
       
    60         /*
       
    61          * Returns non-zero if at end of file.
       
    62          */
       
    63     int (*eof)(FileHandle *handle);
       
    64 
       
    65         /*
       
    66          * Returns byte offset from start of file.
       
    67          */
       
    68     int (*tell)(FileHandle *handle);
       
    69 
       
    70         /*
       
    71          * Move read/write pointer to byte offset from start of file.
       
    72          *  Returns non-zero on success, zero on error.
       
    73          * On failure, call __PHYSFS_setError().
       
    74          */
       
    75     int (*seek)(FileHandle *handle, int offset);
       
    76 
       
    77         /*
       
    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().
       
    81          */
       
    82     int (*close)(FileHandle *handle);
       
    83 } FileFunctions;
       
    84 
       
    85 
       
    86 typedef struct __PHYSFS_DIRHANDLE__
       
    87 {
       
    88         /*
       
    89          * This is reserved for the driver to store information.
       
    90          */
       
    91     void *opaque;
       
    92 
       
    93         /*
       
    94          * Pointer to the directory i/o functions for this handle.
       
    95          */
       
    96     const struct __PHYSFS_DIRFUNCTIONS__ *funcs;
       
    97 } DirHandle;
       
    98 
    19 
    99 
    20 
   100 typedef struct __PHYSFS_LINKEDSTRINGLIST__
    21 typedef struct __PHYSFS_LINKEDSTRINGLIST__
   101 {
    22 {
   102     char *str;
    23     char *str;
   103     struct __PHYSFS_LINKEDSTRINGLIST__ *next;
    24     struct __PHYSFS_LINKEDSTRINGLIST__ *next;
   104 } LinkedStringList;
    25 } LinkedStringList;
       
    26 
       
    27 
       
    28 typedef struct __PHYSFS_FILEHANDLE__
       
    29 {
       
    30         /*
       
    31          * This is reserved for the driver to store information.
       
    32          */
       
    33     void *opaque;
       
    34 
       
    35         /*
       
    36          * This should be the DirHandle that created this FileHandle.
       
    37          */
       
    38     const struct __PHYSFS_DIRHANDLE__ *dirHandle;
       
    39 
       
    40         /*
       
    41          * Pointer to the file i/o functions for this filehandle.
       
    42          */
       
    43     const struct __PHYSFS_FILEFUNCTIONS__ *funcs;
       
    44 } FileHandle;
       
    45 
       
    46 
       
    47 typedef struct __PHYSFS_FILEFUNCTIONS__
       
    48 {
       
    49         /*
       
    50          * Read more from the file.
       
    51          * Returns number of objects of (objSize) bytes read from file, -1
       
    52          *  if complete failure.
       
    53          * On failure, call __PHYSFS_setError().
       
    54          */
       
    55     int (*read)(FileHandle *handle, void *buffer,
       
    56                 unsigned int objSize, unsigned int objCount);
       
    57 
       
    58         /*
       
    59          * Write more to the file. Archives don't have to implement this.
       
    60          *  (Set it to NULL if not implemented).
       
    61          * Returns number of objects of (objSize) bytes written to file, -1
       
    62          *  if complete failure.
       
    63          * On failure, call __PHYSFS_setError().
       
    64          */
       
    65     int (*write)(FileHandle *handle, void *buffer,
       
    66                  unsigned int objSize, unsigned int objCount);
       
    67 
       
    68         /*
       
    69          * Returns non-zero if at end of file.
       
    70          */
       
    71     int (*eof)(FileHandle *handle);
       
    72 
       
    73         /*
       
    74          * Returns byte offset from start of file.
       
    75          */
       
    76     int (*tell)(FileHandle *handle);
       
    77 
       
    78         /*
       
    79          * Move read/write pointer to byte offset from start of file.
       
    80          *  Returns non-zero on success, zero on error.
       
    81          * On failure, call __PHYSFS_setError().
       
    82          */
       
    83     int (*seek)(FileHandle *handle, int offset);
       
    84 
       
    85         /*
       
    86          * Close the file, and free the FileHandle structure (including "opaque").
       
    87          *  returns non-zero on success, zero if can't close file.
       
    88          * On failure, call __PHYSFS_setError().
       
    89          */
       
    90     int (*fileClose)(FileHandle *handle);
       
    91 } FileFunctions;
       
    92 
       
    93 
       
    94 typedef struct __PHYSFS_DIRHANDLE__
       
    95 {
       
    96         /*
       
    97          * This is reserved for the driver to store information.
       
    98          */
       
    99     void *opaque;
       
   100 
       
   101         /*
       
   102          * Pointer to the directory i/o functions for this handle.
       
   103          */
       
   104     const struct __PHYSFS_DIRFUNCTIONS__ *funcs;
       
   105 } DirHandle;
       
   106 
   105 
   107 
   106 /*
   108 /*
   107  * Symlinks should always be followed; PhysicsFS will use
   109  * Symlinks should always be followed; PhysicsFS will use
   108  *  DirFunctions->isSymLink() and make a judgement on whether to
   110  *  DirFunctions->isSymLink() and make a judgement on whether to
   109  *  continue to call other methods based on that.
   111  *  continue to call other methods based on that.
   160         /*
   162         /*
   161          * Open file for reading, and return a FileHandle.
   163          * Open file for reading, and return a FileHandle.
   162          *  This filename is in platform-independent notation.
   164          *  This filename is in platform-independent notation.
   163          * If you can't handle multiple opens of the same file,
   165          * If you can't handle multiple opens of the same file,
   164          *  you can opt to fail for the second call.
   166          *  you can opt to fail for the second call.
       
   167          * Fail if the file does not exist.
   165          * Returns NULL on failure, and calls __PHYSFS_setError().
   168          * Returns NULL on failure, and calls __PHYSFS_setError().
   166          */
   169          */
   167     FileHandle *(*openRead)(DirHandle *r, const char *filename);
   170     FileHandle *(*openRead)(DirHandle *r, const char *filename);
   168 
   171 
   169         /*
   172         /*
   170          * Open file for writing, and return a FileHandle.
   173          * Open file for writing, and return a FileHandle.
   171          *  This filename is in platform-independent notation.
   174          * If the file does not exist, it should be created. If it exists,
       
   175          *  it should be truncated to zero bytes. The writing
       
   176          *  offset should be the start of the file.
       
   177          * This filename is in platform-independent notation.
   172          *  This method may be NULL.
   178          *  This method may be NULL.
   173          * If you can't handle multiple opens of the same file,
   179          * If you can't handle multiple opens of the same file,
   174          *  you can opt to fail for the second call.
   180          *  you can opt to fail for the second call.
   175          * Returns NULL on failure, and calls __PHYSFS_setError().
   181          * Returns NULL on failure, and calls __PHYSFS_setError().
   176          */
   182          */
   177     FileHandle *(*openWrite)(DirHandle *r, const char *filename);
   183     FileHandle *(*openWrite)(DirHandle *r, const char *filename);
   178 
   184 
   179         /*
   185         /*
   180          * Open file for appending, and return a FileHandle.
   186          * Open file for appending, and return a FileHandle.
   181          *  This filename is in platform-independent notation.
   187          * If the file does not exist, it should be created. The writing
       
   188          *  offset should be the end of the file.
       
   189          * This filename is in platform-independent notation.
   182          *  This method may be NULL.
   190          *  This method may be NULL.
   183          * If you can't handle multiple opens of the same file,
   191          * If you can't handle multiple opens of the same file,
   184          *  you can opt to fail for the second call.
   192          *  you can opt to fail for the second call.
   185          * Returns NULL on failure, and calls __PHYSFS_setError().
   193          * Returns NULL on failure, and calls __PHYSFS_setError().
   186          */
   194          */
   210         /*
   218         /*
   211          * Close directories/archives, and free the handle, including
   219          * Close directories/archives, and free the handle, including
   212          *  the "opaque" entry. This should assume that it won't be called if
   220          *  the "opaque" entry. This should assume that it won't be called if
   213          *  there are still files open from this DirHandle.
   221          *  there are still files open from this DirHandle.
   214          */
   222          */
   215     void (*close)(DirHandle *r);
   223     void (*dirClose)(DirHandle *r);
   216 } DirFunctions;
   224 } DirFunctions;
   217 
   225 
   218 
   226 
   219 /* error messages... */
   227 /* error messages... */
   220 #define ERR_IS_INITIALIZED       "Already initialized"
   228 #define ERR_IS_INITIALIZED       "Already initialized"
   246 /*
   254 /*
   247  * Convert (dirName) to platform-dependent notation, then prepend (prepend)
   255  * Convert (dirName) to platform-dependent notation, then prepend (prepend)
   248  *  and append (append) to the converted string.
   256  *  and append (append) to the converted string.
   249  *
   257  *
   250  *  So, on Win32, calling:
   258  *  So, on Win32, calling:
   251  *     __PHYSFS_convertToDependentNotation("C:\", "my/files", NULL);
   259  *     __PHYSFS_convertToDependent("C:\", "my/files", NULL);
   252  *  ...will return the string "C:\my\files".
   260  *  ...will return the string "C:\my\files".
   253  *
   261  *
   254  * This is a convenience function; you might want to hack something out that
   262  * This is a convenience function; you might want to hack something out that
   255  *  is less generic (and therefore more efficient).
   263  *  is less generic (and therefore more efficient).
   256  *
   264  *
   257  * Be sure to free() the return value when done with it.
   265  * Be sure to free() the return value when done with it.
   258  */
   266  */
   259 char *__PHYSFS_convertToDependentNotation(const char *prepend,
   267 char *__PHYSFS_convertToDependent(const char *prepend,
   260                                           const char *dirName,
   268                                   const char *dirName,
   261                                           const char *append);
   269                                   const char *append);
   262 
   270 
   263 /*
   271 /*
   264  * Verify that (fname) (in platform-independent notation), in relation
   272  * Verify that (fname) (in platform-independent notation), in relation
   265  *  to (h) is secure. That means that each element of fname is checked
   273  *  to (h) is secure. That means that each element of fname is checked
   266  *  for symlinks (if they aren't permitted). Also, elements such as
   274  *  for symlinks (if they aren't permitted). Also, elements such as
   335  * This is a pass-through to whatever stricmp() is called on your platform.
   343  * This is a pass-through to whatever stricmp() is called on your platform.
   336  */
   344  */
   337 int __PHYSFS_platformStricmp(const char *str1, const char *str2);
   345 int __PHYSFS_platformStricmp(const char *str1, const char *str2);
   338 
   346 
   339 /*
   347 /*
       
   348  * Return non-zero if filename (in platform-dependent notation) exists.
       
   349  *  Symlinks should be followed; if what the symlink points to is missing,
       
   350  *  then the retval is false.
       
   351  */
       
   352 int __PHYSFS_platformExists(const char *fname);
       
   353 
       
   354 /*
   340  * Return non-zero if filename (in platform-dependent notation) is a symlink.
   355  * Return non-zero if filename (in platform-dependent notation) is a symlink.
   341  */
   356  */
   342 int __PHYSFS_platformIsSymlink(const char *fname);
   357 int __PHYSFS_platformIsSymLink(const char *fname);
   343 
   358 
   344 /*
   359 /*
   345  * Return non-zero if filename (in platform-dependent notation) is a symlink.
   360  * Return non-zero if filename (in platform-dependent notation) is a symlink.
       
   361  *  Symlinks should be followed; if what the symlink points to is missing,
       
   362  *  or isn't a directory, then the retval is false.
   346  */
   363  */
   347 int __PHYSFS_platformIsDirectory(const char *fname);
   364 int __PHYSFS_platformIsDirectory(const char *fname);
       
   365 
       
   366 /*
       
   367  * Convert (dirName) to platform-dependent notation, then prepend (prepend)
       
   368  *  and append (append) to the converted string.
       
   369  *
       
   370  *  So, on Win32, calling:
       
   371  *     __PHYSFS_platformCvtToDependent("C:\", "my/files", NULL);
       
   372  *  ...will return the string "C:\my\files".
       
   373  *
       
   374  * This can be implemented in a platform-specific manner, so you can get
       
   375  *  get a speed boost that the default implementation can't, since
       
   376  *  you can make assumptions about the size of strings, etc..
       
   377  *
       
   378  * Platforms that choose not to implement this may just call
       
   379  *  __PHYSFS_convertToDependent() as a passthrough.
       
   380  *
       
   381  * Be sure to free() the return value when done with it.
       
   382  */
       
   383 char *__PHYSFS_platformCvtToDependent(const char *prepend,
       
   384                                       const char *dirName,
       
   385                                       const char *append);
       
   386 
       
   387 /*
       
   388  * Make the current thread give up a timeslice. This is called in a loop
       
   389  *  while waiting for various external forces to get back to us.
       
   390  */
       
   391 void __PHYSFS_platformTimeslice(void);
       
   392 
       
   393 
       
   394 /*
       
   395  * Enumerate a directory of files. This follows the rules for the
       
   396  *  DirFunctions->enumerateFiles() method (see above), except that the
       
   397  *  (dirName) that is passed to this function is converted to
       
   398  *  platform-DEPENDENT notation by the caller. The DirFunctions version
       
   399  *  uses platform-independent notation.
       
   400  */
       
   401 LinkedStringList *__PHYSFS_platformEnumerateFiles(const char *dirname);
   348 
   402 
   349 
   403 
   350 #ifdef __cplusplus
   404 #ifdef __cplusplus
   351 extern "C" {
   405 extern "C" {
   352 #endif
   406 #endif