Subversion Repositories Games.Descent

Rev

Blame | Last modification | View Log | Download | RSS feed

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