00001 /** ============================================================================ 00002 * @file kfiledefs.h 00003 * 00004 * @path $(DSPLINK)/gpp/inc/usr/ 00005 * 00006 * @brief Defines data types and structures used by KFILE module. 00007 * 00008 * @ver 1.65.00.03 00009 * ============================================================================ 00010 * @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated - 00011 * http://www.ti.com/ 00012 * 00013 * Redistribution and use in source and binary forms, with or without 00014 * modification, are permitted provided that the following conditions 00015 * are met: 00016 * 00017 * * Redistributions of source code must retain the above copyright 00018 * notice, this list of conditions and the following disclaimer. 00019 * 00020 * * Redistributions in binary form must reproduce the above copyright 00021 * notice, this list of conditions and the following disclaimer in the 00022 * documentation and/or other materials provided with the distribution. 00023 * 00024 * * Neither the name of Texas Instruments Incorporated nor the names of 00025 * its contributors may be used to endorse or promote products derived 00026 * from this software without specific prior written permission. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00029 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00030 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00031 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00032 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00033 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00034 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00035 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00036 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00037 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00038 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00039 * ============================================================================ 00040 */ 00041 00042 00043 #if !defined (KFILEDEFS_H) 00044 #define KFILEDEFS_H 00045 00046 /* ----------------------------------- DSP/BIOS Link */ 00047 #include <dsplink.h> 00048 00049 00050 #if defined (__cplusplus) 00051 extern "C" { 00052 #endif /* defined (__cplusplus) */ 00053 00054 00055 /** ============================================================================ 00056 * @name KFILE_Seek 00057 * 00058 * @brief Enumerates the values used for repositioning the 00059 * file position indicator. 00060 * 00061 * @param KFILE_SeekSet 00062 * Seek from beginning of file. 00063 * @param KFILE_SeekCur 00064 * Seek from current position. 00065 * @param KFILE_SeekEnd 00066 * Seek from end of file. 00067 * ============================================================================ 00068 */ 00069 typedef enum { 00070 KFILE_SeekSet = 0x00, 00071 KFILE_SeekCur = 0x01, 00072 KFILE_SeekEnd = 0x02 00073 } KFILE_FileSeek ; 00074 00075 00076 /** ============================================================================ 00077 * @name FileName 00078 * 00079 * @brief Definition for identifying files. 00080 * ============================================================================ 00081 */ 00082 typedef Pstr FileName ; 00083 00084 00085 /** ============================================================================ 00086 * @name FnKfileOpen 00087 * 00088 * @brief Signature of the function for opening a handle to a KFILE file. 00089 * 00090 * @param fileName 00091 * Name of the file to be opened. 00092 * @param mode 00093 * Mode for opening the file. This argument is case-sensitive. 00094 * Expected modes are: "r" for read, "w" for write and 00095 * "a" for append. 00096 * @param fileHandle 00097 * Pointer to the file object. 00098 * 00099 * @return DSP_SOK 00100 * Operation successfully completed. 00101 * DSP_EINVALIDARG 00102 * Invalid arguments. 00103 * DSP_EFILE 00104 * File not found. 00105 * DSP_EMEMORY 00106 * Out of memory error. 00107 * 00108 * @pre Subcomponent must be initialized. 00109 * fileName must be valid. 00110 * mode must be valid. 00111 * fileHandle must be valid. 00112 * 00113 * @post fileHandle contains the fileObject on success. 00114 * 00115 * @see FnKfileClose 00116 * ============================================================================ 00117 */ 00118 typedef DSP_STATUS (*FnKfileOpen) (IN CONST FileName fileName, 00119 IN CONST Char8 * mode, 00120 IN Void ** fileHandlePtr) ; 00121 00122 00123 /** ============================================================================ 00124 * @name FnKfileClose 00125 * 00126 * @brief Signature of the function for closing a handle to a KFILE file. 00127 * 00128 * @param fileHandle 00129 * Handle of file to be closed, returned from KFILE_Open. 00130 * 00131 * @return DSP_SOK 00132 * Operation successfully completed. 00133 * DSP_EFILE 00134 * File is not open. 00135 * DSP_EPOINTER 00136 * Invalid file object. 00137 * 00138 * @pre Subcomponent must be initialized. 00139 * fileHandle must be a valid handle to a file opened earlier. 00140 * 00141 * @post Memory allocated for fileHandle is freed. 00142 * 00143 * @see FnKfileOpen 00144 * ============================================================================ 00145 */ 00146 typedef DSP_STATUS (*FnKfileClose) (IN Void * fileHandle) ; 00147 00148 00149 /** ============================================================================ 00150 * @name FnKfileRead 00151 * 00152 * @brief Signature of the function for reading from a KFILE file. 00153 * 00154 * @param buffer 00155 * Buffer in which the contents of file are read. 00156 * @param size 00157 * Size of each object to read from file. 00158 * @param count 00159 * Number of objects to read. 00160 * @param fileHandle 00161 * KFileObject to read from. 00162 * 00163 * @return DSP_SOK 00164 * Operation successfully completed. 00165 * DSP_EINVALIDARG 00166 * Invalid arguments. 00167 * DSP_EPOINTER 00168 * Invalid file object. 00169 * DSP_EFILE 00170 * File is not open or error reading file. 00171 * DSP_ERANGE 00172 * The requested number of bytes is beyond EOF. 00173 * 00174 * @pre Subcomponent must be initialized. 00175 * fileHandle must be a valid file pointer opened earlier. 00176 * 00177 * @post None 00178 * 00179 * @see FnKfileOpen 00180 * ============================================================================ 00181 */ 00182 typedef DSP_STATUS (*FnKfileRead) (OUT Char8 * buffer, 00183 IN Uint32 size, 00184 IN Uint32 count, 00185 IN Void * fileHandle) ; 00186 00187 00188 /** ============================================================================ 00189 * @name FnKfileSeek 00190 * 00191 * @brief Signature of the function for repositioning the file pointer within 00192 * a KFILE file. 00193 * 00194 * @param fileHandle 00195 * The fileObject to seek into. 00196 * @param offset 00197 * Offset for positioning the file pointer. 00198 * @param origin 00199 * Origin for calculating absolute position where file pointer 00200 * is to be positioned. This can take the following values: 00201 * KFILE_SeekSet 00202 * KFILE_SeekCur 00203 * KFILE_SeekEnd 00204 * 00205 * @return DSP_SOK 00206 * Operation successfully completed. 00207 * DSP_EINVALIDARG 00208 * Invalid arguments. 00209 * DSP_EPOINTER 00210 * Invalid file object. 00211 * DSP_EFILE 00212 * File is not opened. 00213 * DSP_ERANGE 00214 * Offset and origin combination is beyond file size range. 00215 * 00216 * @pre Subcomponent must be initialized. 00217 * fileHandle must be a valid handle to a file opened earlier. 00218 * 00219 * @post None 00220 * 00221 * @see FnKfileTell 00222 * ============================================================================ 00223 */ 00224 typedef DSP_STATUS (*FnKfileSeek) (IN Void * fileHandle, 00225 IN Int32 offset, 00226 IN KFILE_FileSeek origin) ; 00227 00228 00229 /** ============================================================================ 00230 * @name FnKfileTell 00231 * 00232 * @brief Signature of the function for returning the current file pointer 00233 * position within a KFILE file. 00234 * 00235 * @param fileHandle 00236 * The fileObject pointer. 00237 * @param pos 00238 * Out argument for holding the current file position 00239 * indicator value. 00240 * 00241 * @return DSP_SOK 00242 * Operation successfully completed. 00243 * DSP_EINVALIDARG 00244 * Invalid arguments. 00245 * DSP_EPOINTER 00246 * Invalid file object. 00247 * DSP_EFILE 00248 * file is not opened. 00249 * 00250 * @pre Subcomponent must be initialized. 00251 * fileHandle must be a valid handle to a file opened earlier. 00252 * 00253 * @post None 00254 * 00255 * @see FnKfileSeek 00256 * ============================================================================ 00257 */ 00258 typedef DSP_STATUS (*FnKfileTell) (IN Void * fileHandle, 00259 OUT Int32 * pos) ; 00260 00261 00262 /** ============================================================================ 00263 * @name FnKfileGetSize 00264 * 00265 * @brief Signature of the function for returning the file size of the KFILE 00266 * file. 00267 * 00268 * @param fileHandle 00269 * Handle to the file object. 00270 * @param size 00271 * Out argument for holding the file size. 00272 * 00273 * @return None. 00274 * 00275 * @pre Subcomponent must be initialized. 00276 * fileHandle must be a valid handle to a file opened earlier. 00277 * 00278 * @post None 00279 * 00280 * @see FnKfileSeek 00281 * ============================================================================ 00282 */ 00283 typedef Void (*FnKfileGetSize) (IN Void * fileHandle, 00284 OUT Uint32 * size) ; 00285 00286 00287 /** ============================================================================ 00288 * @name KFILE_Interface 00289 * 00290 * @brief Structure containing interface functions exported by the KFILE 00291 * OSAL subcomponent. 00292 * 00293 * @param kfileOpen 00294 * Function pointer providing the abstraction to the KFILE module's 00295 * open function 00296 * @param kfileClose 00297 * Function pointer providing the abstraction to the KFILE module's 00298 * close function. 00299 * @param kfileRead 00300 * Function pointer providing the abstraction to the KFILE module's 00301 * read function. 00302 * @param kfileSeek 00303 * Function pointer providing the abstraction to the KFILE module's 00304 * seek function. 00305 * @param kfileTell 00306 * Function pointer providing the abstraction to the KFILE module's 00307 * tell function. 00308 * @param kfileGetSize 00309 * Function pointer providing the abstraction to the KFILE module's 00310 * getSize function. 00311 * ============================================================================ 00312 */ 00313 typedef struct KFILE_Interface_tag { 00314 FnKfileOpen kfileOpen ; 00315 FnKfileClose kfileClose ; 00316 FnKfileRead kfileRead ; 00317 FnKfileSeek kfileSeek ; 00318 FnKfileTell kfileTell ; 00319 FnKfileGetSize kfileGetSize ; 00320 } KFILE_Interface ; 00321 00322 /** ============================================================================ 00323 * @name KFileObject 00324 * 00325 * @brief Definition of the KFILE object used by all KFILE functions. 00326 * 00327 * @param signature 00328 * Signature of the KFILE object. 00329 * @param fnTable 00330 * Pointer to the KFILE function table. 00331 * @param fileObj 00332 * Pointer to the KFILE module-specific KFILE object. 00333 * @param isOpen 00334 * Flag to track whether the file is isOpen. 00335 * 00336 * @see KFILE_Open () 00337 * ============================================================================ 00338 */ 00339 typedef struct KFileObject_tag { 00340 Uint32 signature ; 00341 KFILE_Interface * fnTable ; 00342 Void * fileObj ; 00343 Bool isOpen ; 00344 } KFileObject ; 00345 00346 00347 #if defined (__cplusplus) 00348 } 00349 #endif /* defined (__cplusplus) */ 00350 00351 00352 #endif /* !defined (KFILEDEFS_H) */