deps/libretro-common/include/lists/dir_list.h

   1 /* Copyright  (C) 2010-2020 The RetroArch team
   2  *
   3  * ---------------------------------------------------------------------------------------
   4  * The following license statement only applies to this file (dir_list.h).
   5  * ---------------------------------------------------------------------------------------
   6  *
   7  * Permission is hereby granted, free of charge,
   8  * to any person obtaining a copy of this software and associated documentation files (the "Software"),
   9  * to deal in the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
  11  * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
  16  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  19  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  */
  22
  23 #ifndef __LIBRETRO_SDK_DIR_LIST_H
  24 #define __LIBRETRO_SDK_DIR_LIST_H
  25
  26 #include <retro_common_api.h>
  27 #include <boolean.h>
  28
  29 #include <lists/string_list.h>
  30
  31 RETRO_BEGIN_DECLS
  32
  33 /**
  34  * dir_list_append:
  35  * @list               : existing list to append to.
  36  * @dir                : directory path.
  37  * @ext                : allowed extensions of file directory entries to include.
  38  * @include_dirs       : include directories as part of the finished directory listing?
  39  * @include_hidden     : include hidden files and directories as part of the finished directory listing?
  40  * @include_compressed : Only include files which match ext. Do not try to match compressed files, etc.
  41  * @recursive          : list directory contents recursively
  42  *
  43  * Create a directory listing, appending to an existing list
  44  *
  45  * @return Returns true on success, otherwise false.
  46  **/
  47 bool dir_list_append(struct string_list *list, const char *dir, const char *ext,
  48       bool include_dirs, bool include_hidden, bool include_compressed, bool recursive);
  49
  50 /**
  51  * dir_list_new:
  52  * @dir                : directory path.
  53  * @ext                : allowed extensions of file directory entries to include.
  54  * @include_dirs       : include directories as part of the finished directory listing?
  55  * @include_hidden     : include hidden files and directories as part of the finished directory listing?
  56  * @include_compressed : include compressed files, even when not part of ext.
  57  * @recursive          : list directory contents recursively
  58  *
  59  * Create a directory listing.
  60  *
  61  * @return pointer to a directory listing of type 'struct string_list *' on success,
  62  * NULL in case of error. Has to be freed manually.
  63  **/
  64 struct string_list *dir_list_new(const char *dir, const char *ext,
  65       bool include_dirs, bool include_hidden, bool include_compressed, bool recursive);
  66
  67 /**
  68  * dir_list_initialize:
  69  *
  70  * NOTE: @list must zero initialised before
  71  * calling this function, otherwise UB.
  72  **/
  73 bool dir_list_initialize(struct string_list *list,
  74       const char *dir,
  75       const char *ext, bool include_dirs,
  76       bool include_hidden, bool include_compressed,
  77       bool recursive);
  78
  79 /**
  80  * dir_list_sort:
  81  * @list      : pointer to the directory listing.
  82  * @dir_first : move the directories in the listing to the top?
  83  *
  84  * Sorts a directory listing.
  85  **/
  86 void dir_list_sort(struct string_list *list, bool dir_first);
  87
  88 /**
  89  * dir_list_free:
  90  * @list : pointer to the directory listing
  91  *
  92  * Frees a directory listing.
  93  **/
  94 void dir_list_free(struct string_list *list);
  95
  96 bool dir_list_deinitialize(struct string_list *list);
  97
  98 RETRO_END_DECLS
  99
 100 #endif