/* Copyright (c) 2006 NVIDIA Corporation.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property 
 * and proprietary rights in and to this software, related documentation 
 * and any modifications thereto.  Any use, reproduction, disclosure or 
 * distribution of this software and related documentation without an 
 * express license agreement from NVIDIA Corporation is strictly prohibited.
 */

/** @file GFFDev.h
    GFSDK File Device API header file.
*/

#ifndef __GFFDEV_H__
#define __GFFDEV_H__

#include "nvtypes.h"

#ifdef __cplusplus
extern "C"
{
#endif  /* __cplusplus */

/** @addtogroup groupFDev FDevAPI File Device API
    <ul>
    <li> @ref pageFDevAppNotes
        <ul>
        <li> @ref pageFDevAppNotes1
        </ul>
    </ul>
*/
/*@{*/

/** FDev capability flag.
    @see GFFDevMount()
 */
#define GFFDEV_CAP_STANDARD 0x00010000  /**< Standard C Library */

/** FDev capability flag.
    @see GFFDevMount()
 */
#define GFFDEV_CAP_DEVICE_SD 0x00000001  /**< SD Device Supported */

/** FDev capability flag.
    @see GFFDevMount()
 */
#define GFFDEV_CAP_FAT 0x00020000  /**< Fat FileSystem */

/** FDev capability flag.
    @see GFFDevMount()
 */
#define GFFDEV_CAP_DEVICE_MASK  0x00000FFF

/** FDev capability flag - default on the selected OS. 
    Linux, Windows -> Standard, else -> SD
    @see GFFDevMount()
 */
#if !NVOS_IS_WINDOWS && !NVOS_IS_LINUX
#define GFFDEV_CAP_DEFAULT_FOR_OS GFFDEV_CAP_DEVICE_SD
#else
#define GFFDEV_CAP_DEFAULT_FOR_OS GFFDEV_CAP_STANDARD
#endif
  
/** Parameter enum for GFFDevSeekFile.
    @see GFFDevSeekFile
 */
typedef enum
{
    GFFDEV_SEEK_SET = 0,  /**< Set fileHandle relative to beginning of file */
    GFFDEV_SEEK_CUR,  /**< Set fileHandle relative to specified offset location */
    GFFDEV_SEEK_END  /**< Set fileHandle relative to end of file */
} GFFDEVSEEKTYPE;

/** Public File Info structure.
    Matches Microsoft's struct _finddata_t .

    @see FDevFindFirstFile()
    @see FDevFindNextFile()
 */
typedef struct _GFFDEVFILEINFO
{
    unsigned attrib;
    NvU32    time_create;  /**< -1 for FAT file systems */
    NvU32    time_access;  /**< -1 for FAT file systems */
    NvU32    time_write;
    NvU32    size;
    char     name[260];
} GFFDEVFILEINFO, *PGFFDEVFILEINFO;

// Typesafe functions for opening and closing this component
GF_RETTYPE GFFDevOpen(GFRmHandle hRm, GFFDevHandle *phFDev,
                      GF_STATE_TYPE state, GFRmChHandle hCh);
void GFFDevClose(GFFDevHandle *phFDev);

/** @name Functions
@{*/

/** Mounts a filesystem.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param capType (NvU32) capability type

    The filesystem pointed to by #FDevHandle will be mounted based on
    the #capType.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevMount(GFFDevHandle FDevHandle, NvU32 capType);

/** Unmounts a mounted filesystem.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
 
    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
*/
GF_RETTYPE GFFDevUnmount(GFFDevHandle FDevHandle);

/** Opens a file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileName (const char *) name of the file
    @param fileSpec (const char *) read/write/etc flags
    @param pFileHandle (#GFFDevFileHandle) Pointer to the handle of the opened file -
                                    will be filled in by #GFFDevOpenFile()

    Opens a file on the mounted filesystem with #fileName.  Open flags,
    given by #fileSpec, are the same as libc's fopen.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevOpenFile(GFFDevHandle FDevhandle,
                          const char *fileName,
                          const char *fileSpec,
                          GFFDevFileHandle *pFileHandle);

/** Closes an open file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param pFileHandle (#GFFDevFileHandle *) Pointer to the open file

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevCloseFile(GFFDevHandle FDevhandle,
                           GFFDevFileHandle *pFileHandle);

/** Reads data from a file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileHandle (#GFFDevFileHandle) Handle to the open file
    @param pReadBuf (void *) Buffer for file bytes
    @param pCount (NvU32 *) Pointer to number of bytes to read, will be
                            written to the actual number of bytes read.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevReadFile(GFFDevHandle FDevhandle,
                          GFFDevFileHandle fileHandle,
                          void *    pReadBuf,
                          NvU32     *pCount);

/** Writes data to an open file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileHandle (#GFFDevFileHandle) Handle to open file
    @param pWriteBuf (void *) pointer to bytes to write to the file
    @param pCount (NvU32 *) pointer to number of bytes to write, will
                            be written to actual number of bytes written.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevWriteFile(GFFDevHandle FDevHandle,
                           GFFDevFileHandle fileHandle,
                           void *    pWriteBuf,
                           NvU32     *pCount );

/** Sets the file read/write position.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileHandle (#GFFDevFileHandle) Handle to open file
    @param offset (NvS32) offset to be used with #where
    @param where (#GFFDEVSEEKTYPE) file offset base

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevSeekFile(GFFDevHandle FDevHandle,
                          GFFDevFileHandle fileHandle,
                          NvS32          offset,
                          GFFDEVSEEKTYPE where);

/** Gets the current file position.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileHandle (#GFFDevFileHandle) Handle to open file
    @param pOffset (NvU32 *) pointer to offset, will be filled in

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevTellFile(GFFDevHandle FDevHandle,
                          GFFDevFileHandle fileHandle,
                          NvU32     *pOffset);

/** Gets the file size.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileName (#GFFDevFileHandle) Handle of open file
    @param pSize (NvU32 *) pointer to file size, will be filled in.

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevGetFileSize(GFFDevHandle FDevHandle,
                             const char *fileName,
                             NvU32      *pSize);

/** Renames a file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param oldFileName (const char *) name of existing file
    @param newFileName (const char *) name to which to rename the file

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevRenameFile(GFFDevHandle FDevHandle,
                            const char *oldFileName,
                            const char *newFileName);

/** Removes a file from the filesystem
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileName (#GFFDevFileHandle) Handle of open file

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevDeleteFile(GFFDevHandle FDevHandle,
                            const char *fileName);

/** Gets the first file in a directory.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param dirName (const char *) Name of the directory to enumerate
    @param pFileInfo (#GFFDEVFILEINFO *) pointer to the file info for the
                                         first file
    @param pDirHandle (#GFFDevDirHandle *) pointer to the handle to the directory

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevFindFirstFile(GFFDevHandle FDevHandle,
                               const char *dirName,
                               GFFDEVFILEINFO *pFileInfo,
                               GFFDevDirHandle *pDirHandle);

/** Gets the next file in the directory.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param pFileInfo (#GFFDEVFILEINFO *) pointer ot the info for the next file
    @param pDirHandle (#GFFDevDirHandle *) pointer to the directory handle

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevFindNextFile(GFFDevHandle FDevHandle,
                              GFFDEVFILEINFO *pFileInfo,
                              GFFDevDirHandle *pDirHandle);

/** Closes the directory.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param pDirHandle (#GFFDevDirHandle *) pointer to the directory handle

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevFindCloseFile(GFFDevHandle FDevHandle,
                               GFFDevDirHandle *pdirHandle);

/** Flushes all buffered data to the file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileName (#GFFDevFileHandle) Handle of open file

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevFlushFile(GFFDevHandle FDevHandle,
                           GFFDevFileHandle fileHandle);

/** Gets the filesystem blocks for the file.
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param fileName (#GFFDevFileHandle) Handle of open file
    @param size (NvU32) size of the file
    @param ppBlockList (#PGFBLOCKLIST *) block list to be allocated

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevBlockListAlloc(GFFDevHandle FDevHandle,
                                GFFDevFileHandle fileHandle,
                                NvU32        size,
                                PGFBLOCKLIST *ppBlockList );

/** Gets the FDev API properties
    @param FDevHandle (#GFFDevHandle) Handle to FDev API
    @param pBlockList (#PGFBLOCKLIST) Block list to deallocate

    @retval #GF_SUCCESS Success
    @retval #GF_ERROR   Error
 */
GF_RETTYPE GFFDevBlockListFree(GFFDevHandle FDevHandle,
                               PGFBLOCKLIST pBlockList );

/*@}*/
/*@}*/

#ifdef __cplusplus
}
#endif  /* __cplusplus */

/** @page pageFDevAppNotes FDevAPI Application Notes

    @section pageFDevAppNotes1 Todo

*/

#endif  /* __GFFDEV_H__ */