physfs.h
changeset 508 0e75524a96af
parent 397 12ff23d3d716
child 527 fa0330949c77
equal deleted inserted replaced
507:e13baf8efaaa 508:0e75524a96af
   256  * \sa PHYSFS_read
   256  * \sa PHYSFS_read
   257  * \sa PHYSFS_write
   257  * \sa PHYSFS_write
   258  * \sa PHYSFS_seek
   258  * \sa PHYSFS_seek
   259  * \sa PHYSFS_tell
   259  * \sa PHYSFS_tell
   260  * \sa PHYSFS_eof
   260  * \sa PHYSFS_eof
       
   261  * \sa PHYSFS_setBuffer
       
   262  * \sa PHYSFS_flush
   261  */
   263  */
   262 typedef struct
   264 typedef struct
   263 {
   265 {
   264     void *opaque;  /**< That's all you get. Don't touch. */
   266     void *opaque;  /**< That's all you get. Don't touch. */
   265 } PHYSFS_file;
   267 } PHYSFS_file;
   287     const char *description; /**< Human-readable archive description. */
   289     const char *description; /**< Human-readable archive description. */
   288     const char *author;      /**< Person who did support for this archive. */
   290     const char *author;      /**< Person who did support for this archive. */
   289     const char *url;         /**< URL related to this archive */
   291     const char *url;         /**< URL related to this archive */
   290 } PHYSFS_ArchiveInfo;
   292 } PHYSFS_ArchiveInfo;
   291 
   293 
       
   294 
   292 /**
   295 /**
   293  * \struct PHYSFS_Version
   296  * \struct PHYSFS_Version
   294  * \brief Information the version of PhysicsFS in use.
   297  * \brief Information the version of PhysicsFS in use.
   295  *
   298  *
   296  * Represents the library's version as three levels: major revision
   299  * Represents the library's version as three levels: major revision
   312 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
   315 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
   313 #define PHYSFS_VER_MAJOR 0
   316 #define PHYSFS_VER_MAJOR 0
   314 #define PHYSFS_VER_MINOR 1
   317 #define PHYSFS_VER_MINOR 1
   315 #define PHYSFS_VER_PATCH 7
   318 #define PHYSFS_VER_PATCH 7
   316 #endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
   319 #endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
       
   320 
       
   321 
       
   322 /* PhysicsFS state stuff ... */
   317 
   323 
   318 /**
   324 /**
   319  * \def PHYSFS_VERSION(x)
   325  * \def PHYSFS_VERSION(x)
   320  * \brief Macro to determine PhysicsFS version program was compiled against.
   326  * \brief Macro to determine PhysicsFS version program was compiled against.
   321  *
   327  *
   773                                     const char *archiveExt,
   779                                     const char *archiveExt,
   774                                     int includeCdRoms,
   780                                     int includeCdRoms,
   775                                     int archivesFirst);
   781                                     int archivesFirst);
   776 
   782 
   777 
   783 
       
   784 /* Directory management stuff ... */
       
   785 
   778 /**
   786 /**
   779  * \fn int PHYSFS_mkdir(const char *dirName)
   787  * \fn int PHYSFS_mkdir(const char *dirName)
   780  * \brief Create a directory.
   788  * \brief Create a directory.
   781  *
   789  *
   782  * This is specified in platform-independent notation in relation to the
   790  * This is specified in platform-independent notation in relation to the
   854  *             the file in question. NULL if not found.
   862  *             the file in question. NULL if not found.
   855  */
   863  */
   856 __EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
   864 __EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
   857 
   865 
   858 
   866 
   859 
       
   860 /**
   867 /**
   861  * \fn char **PHYSFS_enumerateFiles(const char *dir)
   868  * \fn char **PHYSFS_enumerateFiles(const char *dir)
   862  * \brief Get a file listing of a search path's directory.
   869  * \brief Get a file listing of a search path's directory.
   863  *
   870  *
   864  * Matching directories are interpolated. That is, if "C:\mydir" is in the
   871  * Matching directories are interpolated. That is, if "C:\mydir" is in the
   955  */
   962  */
   956 __EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
   963 __EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
   957 
   964 
   958 
   965 
   959 /**
   966 /**
       
   967  * \fn PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
       
   968  * \brief Get the last modification time of a file.
       
   969  *
       
   970  * The modtime is returned as a number of seconds since the epoch
       
   971  *  (Jan 1, 1970). The exact derivation and accuracy of this time depends on
       
   972  *  the particular archiver. If there is no reasonable way to obtain this
       
   973  *  information for a particular archiver, or there was some sort of error,
       
   974  *  this function returns (-1).
       
   975  *
       
   976  *   \param filename filename to check, in platform-independent notation.
       
   977  *  \return last modified time of the file. -1 if it can't be determined.
       
   978  */
       
   979 __EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
       
   980 
       
   981 
       
   982 /* i/o stuff... */
       
   983 
       
   984 /**
   960  * \fn PHYSFS_file *PHYSFS_openWrite(const char *filename)
   985  * \fn PHYSFS_file *PHYSFS_openWrite(const char *filename)
   961  * \brief Open a file for writing.
   986  * \brief Open a file for writing.
   962  *
   987  *
   963  * Open a file for writing, in platform-independent notation and in relation
   988  * Open a file for writing, in platform-independent notation and in relation
   964  *  to the write dir as the root of the writable filesystem. The specified
   989  *  to the write dir as the root of the writable filesystem. The specified
  1049  * \sa PHYSFS_openRead
  1074  * \sa PHYSFS_openRead
  1050  * \sa PHYSFS_openWrite
  1075  * \sa PHYSFS_openWrite
  1051  * \sa PHYSFS_openAppend
  1076  * \sa PHYSFS_openAppend
  1052  */
  1077  */
  1053 __EXPORT__ int PHYSFS_close(PHYSFS_file *handle);
  1078 __EXPORT__ int PHYSFS_close(PHYSFS_file *handle);
  1054 
       
  1055 
       
  1056 /**
       
  1057  * \fn PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
       
  1058  * \brief Get the last modification time of a file.
       
  1059  *
       
  1060  * The modtime is returned as a number of seconds since the epoch
       
  1061  *  (Jan 1, 1970). The exact derivation and accuracy of this time depends on
       
  1062  *  the particular archiver. If there is no reasonable way to obtain this
       
  1063  *  information for a particular archiver, or there was some sort of error,
       
  1064  *  this function returns (-1).
       
  1065  *
       
  1066  *   \param filename filename to check, in platform-independent notation.
       
  1067  *  \return last modified time of the file. -1 if it can't be determined.
       
  1068  */
       
  1069 __EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
       
  1070 
  1079 
  1071 
  1080 
  1072 /**
  1081 /**
  1073  * \fn PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
  1082  * \fn PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
  1074  * \brief Read data from a PhysicsFS filehandle
  1083  * \brief Read data from a PhysicsFS filehandle
  1106 __EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle,
  1115 __EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle,
  1107                                       const void *buffer,
  1116                                       const void *buffer,
  1108                                       PHYSFS_uint32 objSize,
  1117                                       PHYSFS_uint32 objSize,
  1109                                       PHYSFS_uint32 objCount);
  1118                                       PHYSFS_uint32 objCount);
  1110 
  1119 
       
  1120 
       
  1121 /* File position stuff... */
       
  1122 
  1111 /**
  1123 /**
  1112  * \fn int PHYSFS_eof(PHYSFS_file *handle)
  1124  * \fn int PHYSFS_eof(PHYSFS_file *handle)
  1113  * \brief Check for end-of-file state on a PhysicsFS filehandle.
  1125  * \brief Check for end-of-file state on a PhysicsFS filehandle.
  1114  *
  1126  *
  1115  * Determine if the end of file has been reached in a PhysicsFS filehandle.
  1127  * Determine if the end of file has been reached in a PhysicsFS filehandle.
  1170  * \sa PHYSFS_seek
  1182  * \sa PHYSFS_seek
  1171  */
  1183  */
  1172 __EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
  1184 __EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
  1173 
  1185 
  1174 
  1186 
       
  1187 /* Buffering stuff... */
       
  1188 
       
  1189 /**
       
  1190  * \fn int PHYSFS_setBuffer(PHYSFS_file *handle, PHYSFS_uint64 bufsize)
       
  1191  * \brief Set up buffering for a PhysicsFS file handle.
       
  1192  *
       
  1193  * Define an i/o buffer for a file handle. A memory block of (bufsize) bytes
       
  1194  *  will be allocated and associated with (handle).
       
  1195  *
       
  1196  * For files opened for reading, up to (bufsize) bytes are read from (handle)
       
  1197  *  and stored in the internal buffer. Calls to PHYSFS_read() will pull
       
  1198  *  from this buffer until it is empty, and then refill it for more reading.
       
  1199  *  Note that compressed files, like ZIP archives, will decompress while
       
  1200  *  buffering, so this can be handy for offsetting CPU-intensive operations.
       
  1201  *  The buffer isn't filled until you do your next read.
       
  1202  *
       
  1203  * For files opened for writing, data will be buffered to memory until the
       
  1204  *  buffer is full or the buffer is flushed. Closing a handle implicitly
       
  1205  *  causes a flush...check your return values!
       
  1206  *
       
  1207  * Seeking, etc transparently accounts for buffering.
       
  1208  *
       
  1209  * You can resize an existing buffer by calling this function more than once
       
  1210  *  on the same file. Setting the buffer size to zero will free an existing
       
  1211  *  buffer.
       
  1212  *
       
  1213  * PhysicsFS file handles are unbuffered by default.
       
  1214  *
       
  1215  * Please check the return value of this function! Failures can include
       
  1216  *  not being able to seek backwards in a read-only file when removing the
       
  1217  *  buffer, not being able to allocate the buffer, and not being able to
       
  1218  *  flush the buffer to disk, among other unexpected problems.
       
  1219  *
       
  1220  *   \param handle handle returned from PHYSFS_open*().
       
  1221  *   \param bufsize size, in bytes, of buffer to allocate.
       
  1222  *  \return nonzero if successful, zero on error.
       
  1223  *
       
  1224  * \sa PHYSFS_flush
       
  1225  * \sa PHYSFS_read
       
  1226  * \sa PHYSFS_write
       
  1227  * \sa PHYSFS_close
       
  1228  */
       
  1229 __EXPORT__ int PHYSFS_setBuffer(PHYSFS_file *handle, PHYSFS_uint64 bufsize);
       
  1230 
       
  1231 
       
  1232 /**
       
  1233  * \fn int PHYSFS_flush(PHYSFS_file *handle, PHYSFS_uint64 bufsize)
       
  1234  * \brief Flush a buffered PhysicsFS file handle.
       
  1235  *
       
  1236  * For buffered files opened for writing, this will put the current contents
       
  1237  *  of the buffer to disk and flag the buffer as empty if possible.
       
  1238  *
       
  1239  * For buffered files opened for reading or unbuffered files, this is a safe
       
  1240  *  no-op, and will report success.
       
  1241  *
       
  1242  *   \param handle handle returned from PHYSFS_open*().
       
  1243  *  \return nonzero if successful, zero on error.
       
  1244  *
       
  1245  * \sa PHYSFS_setBuffer
       
  1246  * \sa PHYSFS_close
       
  1247  */
       
  1248 __EXPORT__ int PHYSFS_flush(PHYSFS_file *handle);
       
  1249 
       
  1250 
  1175 /* Byteorder stuff... */
  1251 /* Byteorder stuff... */
  1176 
  1252 
  1177 /**
  1253 /**
  1178  * \fn PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val)
  1254  * \fn PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val)
  1179  * \brief Swap littleendian signed 16 to platform's native byte order.
  1255  * \brief Swap littleendian signed 16 to platform's native byte order.