Improved some documentation.
This commit is contained in:
parent
cc3ac9539e
commit
0d61295781
|
@ -1892,6 +1892,8 @@ int PHYSFS_setSaneConfig(const char *organization, const char *appName,
|
||||||
|
|
||||||
BAIL_IF(!PHYSFS_setWriteDir(prefdir), PHYSFS_ERR_NO_WRITE_DIR, 0);
|
BAIL_IF(!PHYSFS_setWriteDir(prefdir), PHYSFS_ERR_NO_WRITE_DIR, 0);
|
||||||
|
|
||||||
|
/* !!! FIXME-3.0: these can fail... */
|
||||||
|
|
||||||
/* Put write dir first in search path... */
|
/* Put write dir first in search path... */
|
||||||
PHYSFS_mount(prefdir, NULL, 0);
|
PHYSFS_mount(prefdir, NULL, 0);
|
||||||
|
|
||||||
|
|
70
src/physfs.h
70
src/physfs.h
|
@ -3010,7 +3010,15 @@ typedef struct PHYSFS_Io
|
||||||
/**
|
/**
|
||||||
* \brief Duplicate this i/o instance.
|
* \brief Duplicate this i/o instance.
|
||||||
*
|
*
|
||||||
* // !!! FIXME-3.0: write me.
|
* This needs to result in a full copy of this PHYSFS_Io, that can live
|
||||||
|
* completely independently. The copy needs to be able to perform all
|
||||||
|
* its operations without altering the original, including either object
|
||||||
|
* being destroyed separately (so, for example: they can't share a file
|
||||||
|
* handle; they each need their own).
|
||||||
|
*
|
||||||
|
* If you can't duplicate a handle, it's legal to return NULL, but you
|
||||||
|
* almost certainly need this functionality if you want to use this to
|
||||||
|
* PHYSFS_Io to back an archive.
|
||||||
*
|
*
|
||||||
* \param io The i/o instance to duplicate.
|
* \param io The i/o instance to duplicate.
|
||||||
* \return A new value for a stream's (opaque) field, or NULL on error.
|
* \return A new value for a stream's (opaque) field, or NULL on error.
|
||||||
|
@ -3481,11 +3489,10 @@ typedef struct PHYSFS_Archiver
|
||||||
*/
|
*/
|
||||||
PHYSFS_ArchiveInfo info;
|
PHYSFS_ArchiveInfo info;
|
||||||
|
|
||||||
// !!! FIXME-3.0: documentation: \brief?
|
|
||||||
/**
|
/**
|
||||||
* \brief
|
* \brief Open an archive provided by (io).
|
||||||
*
|
*
|
||||||
* Open an archive provided by (io).
|
* This is where resources are allocated and data is parsed when mounting an archive.
|
||||||
* (name) is a filename associated with (io), but doesn't necessarily
|
* (name) is a filename associated with (io), but doesn't necessarily
|
||||||
* map to anything, let alone a real filename. This possibly-
|
* map to anything, let alone a real filename. This possibly-
|
||||||
* meaningless name is in platform-dependent notation.
|
* meaningless name is in platform-dependent notation.
|
||||||
|
@ -3501,10 +3508,11 @@ typedef struct PHYSFS_Archiver
|
||||||
void *(*openArchive)(PHYSFS_Io *io, const char *name, int forWrite);
|
void *(*openArchive)(PHYSFS_Io *io, const char *name, int forWrite);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* List all files in (dirname). Each file is passed to (cb),
|
* \brief List all files in (dirname).
|
||||||
* where a copy is made if appropriate, so you can dispose of
|
*
|
||||||
* it, if appropriate, upon return from the callback.
|
* Each file is passed to (cb), where a copy is made if appropriate, so
|
||||||
* (dirname) is in platform-independent notation.
|
* you can dispose of it upon return from the callback. (dirname) is in
|
||||||
|
* platform-independent notation.
|
||||||
* If you have a failure, call PHYSFS_SetErrorCode() with whatever code
|
* If you have a failure, call PHYSFS_SetErrorCode() with whatever code
|
||||||
* seem appropriate and return -1.
|
* seem appropriate and return -1.
|
||||||
* If the callback returns -1, please call
|
* If the callback returns -1, please call
|
||||||
|
@ -3526,10 +3534,9 @@ typedef struct PHYSFS_Archiver
|
||||||
const char *origdir, void *callbackdata);
|
const char *origdir, void *callbackdata);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Open file for reading.
|
* \brief Open a file in this archive for reading.
|
||||||
|
*
|
||||||
* This filename, (fnm), is in platform-independent notation.
|
* This filename, (fnm), is in platform-independent notation.
|
||||||
* If you can't handle multiple opens of the same file,
|
|
||||||
* you can opt to fail for the second call.
|
|
||||||
* Fail if the file does not exist.
|
* Fail if the file does not exist.
|
||||||
* Returns NULL on failure, and calls PHYSFS_setErrorCode().
|
* Returns NULL on failure, and calls PHYSFS_setErrorCode().
|
||||||
* Returns non-NULL on success. The pointer returned will be
|
* Returns non-NULL on success. The pointer returned will be
|
||||||
|
@ -3538,13 +3545,13 @@ typedef struct PHYSFS_Archiver
|
||||||
PHYSFS_Io *(*openRead)(void *opaque, const char *fnm);
|
PHYSFS_Io *(*openRead)(void *opaque, const char *fnm);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Open file for writing.
|
* \brief Open a file in this archive for writing.
|
||||||
|
*
|
||||||
* If the file does not exist, it should be created. If it exists,
|
* If the file does not exist, it should be created. If it exists,
|
||||||
* it should be truncated to zero bytes. The writing
|
* it should be truncated to zero bytes. The writing offset should
|
||||||
* offset should be the start of the file.
|
* be the start of the file.
|
||||||
|
* If the archive is read-only, this operation should fail.
|
||||||
* This filename is in platform-independent notation.
|
* This filename is in platform-independent notation.
|
||||||
* If you can't handle multiple opens of the same file,
|
|
||||||
* you can opt to fail for the second call.
|
|
||||||
* Returns NULL on failure, and calls PHYSFS_setErrorCode().
|
* Returns NULL on failure, and calls PHYSFS_setErrorCode().
|
||||||
* Returns non-NULL on success. The pointer returned will be
|
* Returns non-NULL on success. The pointer returned will be
|
||||||
* passed as the "opaque" parameter for later file calls.
|
* passed as the "opaque" parameter for later file calls.
|
||||||
|
@ -3552,12 +3559,12 @@ typedef struct PHYSFS_Archiver
|
||||||
PHYSFS_Io *(*openWrite)(void *opaque, const char *filename);
|
PHYSFS_Io *(*openWrite)(void *opaque, const char *filename);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Open file for appending.
|
* \brief Open a file in this archive for appending.
|
||||||
|
*
|
||||||
* If the file does not exist, it should be created. The writing
|
* If the file does not exist, it should be created. The writing
|
||||||
* offset should be the end of the file.
|
* offset should be the end of the file.
|
||||||
|
* If the archive is read-only, this operation should fail.
|
||||||
* This filename is in platform-independent notation.
|
* This filename is in platform-independent notation.
|
||||||
* If you can't handle multiple opens of the same file,
|
|
||||||
* you can opt to fail for the second call.
|
|
||||||
* Returns NULL on failure, and calls PHYSFS_setErrorCode().
|
* Returns NULL on failure, and calls PHYSFS_setErrorCode().
|
||||||
* Returns non-NULL on success. The pointer returned will be
|
* Returns non-NULL on success. The pointer returned will be
|
||||||
* passed as the "opaque" parameter for later file calls.
|
* passed as the "opaque" parameter for later file calls.
|
||||||
|
@ -3565,35 +3572,48 @@ typedef struct PHYSFS_Archiver
|
||||||
PHYSFS_Io *(*openAppend)(void *opaque, const char *filename);
|
PHYSFS_Io *(*openAppend)(void *opaque, const char *filename);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Delete a file in the archive/directory.
|
* \brief Delete a file or directory in the archive.
|
||||||
|
*
|
||||||
|
* This same call is used for both files and directories; there is not a
|
||||||
|
* separate rmdir() call. Directories are only meant to be removed if
|
||||||
|
* they are empty.
|
||||||
|
* If the archive is read-only, this operation should fail.
|
||||||
|
*
|
||||||
* Return non-zero on success, zero on failure.
|
* Return non-zero on success, zero on failure.
|
||||||
* This filename is in platform-independent notation.
|
* This filename is in platform-independent notation.
|
||||||
* This method may be NULL.
|
|
||||||
* On failure, call PHYSFS_setErrorCode().
|
* On failure, call PHYSFS_setErrorCode().
|
||||||
*/
|
*/
|
||||||
int (*remove)(void *opaque, const char *filename);
|
int (*remove)(void *opaque, const char *filename);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Create a directory in the archive/directory.
|
* \brief Create a directory in the archive.
|
||||||
|
*
|
||||||
* If the application is trying to make multiple dirs, PhysicsFS
|
* If the application is trying to make multiple dirs, PhysicsFS
|
||||||
* will split them up into multiple calls before passing them to
|
* will split them up into multiple calls before passing them to
|
||||||
* your driver.
|
* your driver.
|
||||||
|
* If the archive is read-only, this operation should fail.
|
||||||
* Return non-zero on success, zero on failure.
|
* Return non-zero on success, zero on failure.
|
||||||
* This filename is in platform-independent notation.
|
* This filename is in platform-independent notation.
|
||||||
* This method may be NULL.
|
|
||||||
* On failure, call PHYSFS_setErrorCode().
|
* On failure, call PHYSFS_setErrorCode().
|
||||||
*/
|
*/
|
||||||
int (*mkdir)(void *opaque, const char *filename);
|
int (*mkdir)(void *opaque, const char *filename);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Obtain basic file metadata.
|
* \brief Obtain basic file metadata.
|
||||||
|
*
|
||||||
|
* On success, fill in all the fields in (stat), using
|
||||||
|
* reasonable defaults for fields that apply to your archive.
|
||||||
|
*
|
||||||
* Returns non-zero on success, zero on failure.
|
* Returns non-zero on success, zero on failure.
|
||||||
|
* This filename is in platform-independent notation.
|
||||||
* On failure, call PHYSFS_setErrorCode().
|
* On failure, call PHYSFS_setErrorCode().
|
||||||
*/
|
*/
|
||||||
int (*stat)(void *opaque, const char *fn, PHYSFS_Stat *stat);
|
int (*stat)(void *opaque, const char *fn, PHYSFS_Stat *stat);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Close directories/archives, and free any associated memory,
|
* \brief Destruct a previously-opened archive.
|
||||||
|
*
|
||||||
|
* Close this archive, and free any associated memory,
|
||||||
* including the original PHYSFS_Io and (opaque) itself, if
|
* including the original PHYSFS_Io and (opaque) itself, if
|
||||||
* applicable. Implementation can assume that it won't be called if
|
* applicable. Implementation can assume that it won't be called if
|
||||||
* there are still files open from this archive.
|
* there are still files open from this archive.
|
||||||
|
|
Loading…
Reference in New Issue