Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

kfiledefs.h

Go to the documentation of this file.
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) */

Generated on Fri Jul 16 14:34:02 2010 for DSP/BIOSLink by  doxygen 1.4.4