Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 1 | pmbaty | 1 | #ifndef INCL_PHYSFSEXT_IGNORECASE_H |
| 2 | #define INCL_PHYSFSEXT_IGNORECASE_H |
||
| 3 | |||
| 4 | /** \file ignorecase.h */ |
||
| 5 | |||
| 6 | /** |
||
| 7 | * \mainpage PhysicsFS ignorecase |
||
| 8 | * |
||
| 9 | * This is an extension to PhysicsFS to let you handle files in a |
||
| 10 | * case-insensitive manner, regardless of what sort of filesystem or |
||
| 11 | * archive they reside in. It does this by enumerating directories as |
||
| 12 | * needed and manually locating matching entries. |
||
| 13 | * |
||
| 14 | * Please note that this brings with it some caveats: |
||
| 15 | * - On filesystems that are case-insensitive to start with, such as those |
||
| 16 | * used on Windows or MacOS, you are adding extra overhead. |
||
| 17 | * - On filesystems that are case-sensitive, you might select the wrong dir |
||
| 18 | * or file (which brings security considerations and potential bugs). This |
||
| 19 | * code favours exact case matches, but you will lose access to otherwise |
||
| 20 | * duplicate filenames, or you might go down a wrong directory tree, etc. |
||
| 21 | * In practice, this is rarely a problem, but you need to be aware of it. |
||
| 22 | * - This doesn't do _anything_ with the write directory; you're on your |
||
| 23 | * own for opening the right files for writing. You can sort of get around |
||
| 24 | * this by adding your write directory to the search path, but then the |
||
| 25 | * interpolated directory tree can screw you up even more. |
||
| 26 | * |
||
| 27 | * This code should be considered an aid for legacy code. New development |
||
| 28 | * shouldn't do things that require this aid in the first place. :) |
||
| 29 | * |
||
| 30 | * Usage: Set up PhysicsFS as you normally would, then use |
||
| 31 | * PHYSFSEXT_locateCorrectCase() to get a "correct" pathname to pass to |
||
| 32 | * functions like PHYSFS_openRead(), etc. |
||
| 33 | * |
||
| 34 | * License: this code is public domain. I make no warranty that it is useful, |
||
| 35 | * correct, harmless, or environmentally safe. |
||
| 36 | * |
||
| 37 | * This particular file may be used however you like, including copying it |
||
| 38 | * verbatim into a closed-source project, exploiting it commercially, and |
||
| 39 | * removing any trace of my name from the source (although I hope you won't |
||
| 40 | * do that). I welcome enhancements and corrections to this file, but I do |
||
| 41 | * not require you to send me patches if you make changes. This code has |
||
| 42 | * NO WARRANTY. |
||
| 43 | * |
||
| 44 | * Unless otherwise stated, the rest of PhysicsFS falls under the zlib license. |
||
| 45 | * Please see LICENSE.txt in the root of the source tree. |
||
| 46 | * |
||
| 47 | * \author Ryan C. Gordon. |
||
| 48 | */ |
||
| 49 | |||
| 50 | #ifdef __cplusplus |
||
| 51 | extern "C" { |
||
| 52 | #endif |
||
| 53 | |||
| 54 | /** |
||
| 55 | * \fn int PHYSFSEXT_locateCorrectCase(char *buf) |
||
| 56 | * \brief Find an existing filename with matching case. |
||
| 57 | * |
||
| 58 | * This function will look for a path/filename that matches the passed in |
||
| 59 | * buffer. Each element of the buffer's path is checked for a |
||
| 60 | * case-insensitive match. The buffer must specify a null-terminated string |
||
| 61 | * in platform-independent notation. |
||
| 62 | * |
||
| 63 | * Please note results may be skewed differently depending on whether symlinks |
||
| 64 | * are enabled or not. |
||
| 65 | * |
||
| 66 | * Each element of the buffer is overwritten with the actual case of an |
||
| 67 | * existing match. If there is no match, the search aborts and reports an |
||
| 68 | * error. Exact matches are favored over case-insensitive matches. |
||
| 69 | * |
||
| 70 | * THIS IS RISKY. Please do not use this function for anything but legacy code. |
||
| 71 | * |
||
| 72 | * \param buf Buffer with null-terminated string of path/file to locate. |
||
| 73 | * This buffer will be modified by this function. |
||
| 74 | * \return zero if match was found, -1 if the final element (the file itself) |
||
| 75 | * is missing, -2 if one of the parent directories is missing. |
||
| 76 | */ |
||
| 77 | int PHYSFSEXT_locateCorrectCase(char *buf); |
||
| 78 | |||
| 79 | #ifdef __cplusplus |
||
| 80 | } |
||
| 81 | #endif |
||
| 82 | |||
| 83 | #endif /* include-once blocker. */ |
||
| 84 | |||
| 85 | /* end of ignorecase.h ... */ |
||
| 86 |