1 /* ///////////////////////////////////////////////////////////////////////// 2 * File: unixem/dirent.h 3 * 4 * Purpose: Declaration of the opendir() API functions and types for the 5 * Win32 platform. 6 * 7 * Created: 19th October 2002 8 * Updated: 13th August 2010 9 * 10 * Home: http://synesis.com.au/software/ 11 * 12 * Copyright (c) 2002-2010, Matthew Wilson and Synesis Software 13 * All rights reserved. 14 * 15 * Redistribution and use in source and binary forms, with or without 16 * modification, are permitted provided that the following conditions are 17 * met: 18 * 19 * - Redistributions of source code must retain the above copyright notice, 20 * this list of conditions and the following disclaimer. 21 * - Redistributions in binary form must reproduce the above copyright 22 * notice, this list of conditions and the following disclaimer in the 23 * documentation and/or other materials provided with the distribution. 24 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the 25 * names of any contributors may be used to endorse or promote products 26 * derived from this software without specific prior written permission. 27 * 28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 29 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 30 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 31 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 32 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 33 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 34 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 35 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 36 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 37 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 38 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 39 * 40 * ////////////////////////////////////////////////////////////////////// */ 41 42 43 /** \file unixem/dirent.h 44 * 45 * Contains the declarations for the opendir()/readdir() API. 46 */ 47 48 #ifndef SYNSOFT_UNIXEM_INCL_UNIXEM_H_DIRENT 49 #define SYNSOFT_UNIXEM_INCL_UNIXEM_H_DIRENT 50 51 #ifndef UNIXEM_DOCUMENTATION_SKIP_SECTION 52 # define SYNSOFT_UNIXEM_VER_UNIXEM_H_DIRENT_MAJOR 4 53 # define SYNSOFT_UNIXEM_VER_UNIXEM_H_DIRENT_MINOR 0 54 # define SYNSOFT_UNIXEM_VER_UNIXEM_H_DIRENT_REVISION 1 55 # define SYNSOFT_UNIXEM_VER_UNIXEM_H_DIRENT_EDIT 34 56 #endif /* !UNIXEM_DOCUMENTATION_SKIP_SECTION */ 57 58 /* ////////////////////////////////////////////////////////////////////// */ 59 60 /** \weakgroup unixem Synesis Software UNIX Emulation for Win32 61 * \brief The UNIX emulation library 62 */ 63 64 /** \weakgroup unixem_dirent opendir()/readdir() API 65 * \ingroup UNIXem unixem 66 * \brief This API provides facilities for enumerating the contents of directories 67 * @{ 68 */ 69 70 /* ////////////////////////////////////////////////////////////////////// */ 71 72 #ifndef _WIN32 73 # error This file is only currently defined for compilation on Win32 systems 74 #endif /* _WIN32 */ 75 76 /* ///////////////////////////////////////////////////////////////////////// 77 * Includes 78 */ 79 80 #include <unixem/unixem.h> 81 #include <stddef.h> 82 83 /* ///////////////////////////////////////////////////////////////////////// 84 * Constants and definitions 85 */ 86 87 #ifndef NAME_MAX 88 # define NAME_MAX (260) /*!< The maximum number of characters (including null terminator) in a directory entry name */ 89 #endif /* !NAME_MAX */ 90 91 /* ///////////////////////////////////////////////////////////////////////// 92 * Typedefs 93 */ 94 95 typedef struct dirent_dir unixem_DIR; /*!< Handle type for multibyte string directory enumeration. \note dirent_dir is defined internally */ 96 typedef struct wdirent_dir unixem_wDIR; /*!< Handle type for wide string directory enumeration. \note dirent_dir is defined internally */ 97 98 /** Results structure for readdir() 99 */ 100 struct unixem_dirent 101 { 102 char d_name[NAME_MAX + 1]; /*!< file name (null-terminated) */ 103 int d_mode; /*!< currently unused */ 104 }; 105 106 /** Results structure for wreaddir() 107 */ 108 struct unixem_wdirent 109 { 110 wchar_t d_name[NAME_MAX + 1]; /*!< file name (null-terminated) */ 111 int d_mode; /*!< currently unused */ 112 }; 113 114 /* ///////////////////////////////////////////////////////////////////////// 115 * API functions 116 */ 117 118 #ifdef __cplusplus 119 extern "C" { 120 #endif /* __cplusplus */ 121 122 /** Returns a pointer to the next directory entry. 123 * 124 * This function opens the directory named by filename, and returns a 125 * directory to be used to in subsequent operations. NULL is returned 126 * if name cannot be accessed, or if resources cannot be acquired to 127 * process the request. 128 * 129 * \param name The name of the directory to search 130 * \return The directory handle from which the entries are read or NULL 131 */ 132 unixem_DIR* unixem_opendir(char const* name); 133 /** Identical semantics to opendir(), but for wide string searches. 134 */ 135 unixem_wDIR* unixem_wopendir(wchar_t const* name); 136 137 /** Closes a directory handle 138 * 139 * This function closes a directory handle that was opened with opendir() 140 * and releases any resources associated with that directory handle. 141 * 142 * \param dir The directory handle from which the entries are read 143 * \return 0 on success, or -1 to indicate error. 144 */ 145 int unixem_closedir(unixem_DIR* dir); 146 /** Identical semantics to closedir(), but for wide string searches. 147 */ 148 int unixem_wclosedir(unixem_wDIR* dir); 149 150 /** Resets a directory search position 151 * 152 * This function resets the position of the named directory handle to 153 * the beginning of the directory. 154 * 155 * \param dir The directory handle whose position should be reset 156 */ 157 void unixem_rewinddir(unixem_DIR* dir); 158 /** Identical semantics to rewinddir(), but for wide string searches. 159 */ 160 void unixem_wrewinddir(unixem_wDIR* dir); 161 162 /** Returns a pointer to the next directory entry. 163 * 164 * This function returns a pointer to the next directory entry, or NULL upon 165 * reaching the end of the directory or detecting an invalid seekdir() operation 166 * 167 * \param dir The directory handle from which the entries are read 168 * \return A dirent structure or NULL 169 */ 170 struct unixem_dirent* unixem_readdir(unixem_DIR* dir); 171 /** Identical semantics to readdir(), but for wide string searches. 172 */ 173 struct unixem_wdirent* unixem_wreaddir(unixem_wDIR* dir); 174 175 176 #ifdef __cplusplus 177 } 178 #endif /* __cplusplus */ 179 180 /* ////////////////////////////////////////////////////////////////////// */ 181 182 /** @} // end of group unixem_dirent */ 183 184 /* ////////////////////////////////////////////////////////////////////// */ 185 186 #endif /* SYNSOFT_UNIXEM_INCL_UNIXEM_H_DIRENT */ 187 188 /* ///////////////////////////// end of file //////////////////////////// */ 189