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