fsal.h

最新MTK手机软件源码

 * @return None.
 */
FSAL_Status FSAL_Close(STFSAL *pstFSAL);

/* ------ buffering functions (fsal_buffer.c) ------ */

/**
 * Read data from the file.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbBuf memory location of the data.
 * @param uSize number of bytes to read. uSize must be larger than 0.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Read(STFSAL *pstFSAL, kal_uint8* pbBuf, kal_uint32 uSize);

/**
 * Write data to the file.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbBuf memory location of the data.
 * @param uSize number of bytes to write. uSize must be larger than 0.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Write(STFSAL *pstFSAL, kal_uint8 *pbBuf, kal_uint32 uSize);

/**
 * Change file offset.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param uOffset offsets in unit of bytes.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Seek(STFSAL *pstFSAL, kal_uint32 uOffset);

/**
 * Flush FSAL cache to the underlying file system.
 *
 * @param pstFSAL pointer to FSAL structure.
 *
 * @return None.
 */
FSAL_Status FSAL_CacheFlush(STFSAL *pstFSAL);

/**
 * Get the current file position.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puPosition memory location for retrieving the file position.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_GetCurPos(STFSAL *pstFSAL, kal_uint32 *puPosition);

/**
 * Get the file size.
 * The current file position remains the same after invocation.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puFileSize memory location for retrieving the file size.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_GetFileSize(STFSAL *pstFSAL, kal_uint32 *puFileSize);



/* ------ bits/bytes read access functions (fsal_read.c) ------ */

/**
 * Read n bytes.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbData memory location for storing the result bytes
 * @param uLen number of bytes to read
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Read_Bytes(STFSAL *pstFSAL, kal_uint8 *pbData, kal_uint32 uLen);

/**
 * Read n bits.
 * When calling this function for the first time, *puBitCnt must be 0.
 * *puBitCnt will be updated after each invocation.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puBitCnt memory location for storing the bit offset.
 * @param pbValue memory location for storing the result bits.
 * @param uBitLen number of bits to read (1~8).
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Read_Bits(STFSAL *pstFSAL, kal_uint32 *puBitCnt, kal_uint8 *pbValue, kal_uint32 uBitLen);

/**
 * Read 4 bytes representing an unsigned integer.
 * The content stored on the file is assumed to be big-endian.
 * This function will handle the endian-conversion issue.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puValue memory location for storing the result unsigned integer
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Read_UINT(STFSAL *pstFSAL, kal_uint32 *puValue);

/**
 * Read 3 bytes representing an unsigned integer.
 * The content stored on the file is assumed to be big-endian.
 * This function will handle the endian-conversion issue.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puValue memory location for storing the result unsigned integer
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Read_UINT24(STFSAL *pstFSAL, kal_uint32 *puValue);

/**
 * Read 2 bytes representing an unsigned integer.
 * The content stored on the file is assumed to be big-endian.
 * This function will handle the endian-conversion issue.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pwValue memory location for storing the result unsigned integer
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Read_UINT16(STFSAL *pstFSAL, kal_uint16 *pwValue);

/**
 * Skip n bytes.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param uLen number of bytes to skip
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Skip_Bytes(STFSAL *pstFSAL, kal_uint32 uLen);

/**
 * Get next n bytes. The file offset does not change after invocation.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbValue memory location for storing the result bytes
 * @param uLen number of bytes to peek
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Peek_Bytes(STFSAL *pstFSAL, kal_uint8 *pbValue, kal_uint32 uLen);

/**
 * Get next unsinged integer. The file offset does not change after invocation.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puValue memory location for storing the result unsigned integer
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Peek_UINT(STFSAL *pstFSAL, kal_uint32 *puValue);


/* ------ bits/bytes write access functions (fsal_write.c) ------ */

/**
 * Write n bytes.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbData memory location of the bytes
 * @param uLen number of bytes to write
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Write_Bytes(STFSAL *pstFSAL, kal_uint8 *pbData, kal_uint32 uLen);

/**
 * Write 4 bytes representing an unsigned integer.
 * The value written to the file will be stored as big-endian.
 * This function will handle the endian-conversion issue.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param uValue The value to be written to the file.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Write_UINT(STFSAL *pstFSAL, kal_uint32 uValue);

/**
 * Write 2 bytes representing an unsigned integer.
 * The value written to the file will be stored as big-endian.
 * This function will handle the endian-conversion issue.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param wValue The value to be written to the file.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Write_UINT16(STFSAL* pstFSAL, kal_uint16 wValue);

/**
 * Write 1 byte representing an unsigned character.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param bValue The value to be written to the file.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Write_UINT8(STFSAL* pstFSAL, kal_uint8 bValue);

/**
 * Write 4 bytes representing an unsigned integer at a given file offset.
 * File position remains the same after the invocation.
 * The value written to the file will be stored as big-endian.
 * This function will handle the endian-conversion issue.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param uValue The value to be written to the file.
 * @param uOffset The file offset to write to.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Write_UINT_AT(STFSAL* pstFSAL, kal_uint32 uValue, kal_uint32 uOffset);

/* ------ direct access functions (bypass buffering mechanism) ------ */

/**
 * Open the file. (Internal Use by FSAL Only)
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param szFile pointer to a string contained the file name.
 * @param eMode file operation mode.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_Open(STFSAL *pstFSAL, void *szFile, FSAL_FileMode eMode);

/**
 * Close the file. (Internal Use by FSAL Only)
 *
 * @param pstFSAL pointer to FSAL structure.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_Close(STFSAL *pstFSAL);

/**
 * Read data from the file directly.
 *
 * Use with caution. Becuase the file offset will be out-of-sync
 * between FSAL and underlying file system.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbBuf memory location of the data.
 * @param uSize number of bytes to read. uSize must be larger than 0.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_Read(STFSAL *pstFSAL, kal_uint8* pbBuf, kal_uint32 uSize);

/**
 * Write data to the file directly.
 *
 * Use with caution. Becuase the file offset will be out-of-sync
 * between FSAL and underlying file system.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param pbBuf memory location of the data.
 * @param uSize number of bytes to write. uSize must be larger than 0.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_Write(STFSAL *pstFSAL, kal_uint8* pbBuf, kal_uint32 uSize);

/**
 * Change file offset of the underlying file system directly.
 *
 * Use with caution. Becuase the file offset will be out-of-sync
 * between FSAL and underlying file system.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param uOffset offsets in unit of bytes.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_Seek(STFSAL *pstFSAL, kal_uint32 uOffset);

/**
 * Get the current file position of the underlying file system directly.
 *
 * Use with caution. Becuase the file offset may be out-of-sync
 * between FSAL and underlying file system.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puPosition memory location for retrieving the file position.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_GetCurPos(STFSAL *pstFSAL, kal_uint32* puPosition);

/**
 * Get the file size of the underlying file system directly.
 * The current file position remains the same after invocation.
 *
 * Use with caution. Becuase the file size may be out-of-sync
 * between FSAL and underlying file system.
 *
 * @param pstFSAL pointer to FSAL structure.
 * @param puFileSize memory location for retrieving the file size.
 *
 * @return If the function succeeds, the return value is FSAL_OK.
 * Otherwise, an error code is returned.
 */
FSAL_Status FSAL_Direct_GetFileSize(STFSAL *pstFSAL, kal_uint32 *puFileSize);

/**
 * When using ram file, this funtion shall be called before calling FSAL_Open.
 */
void FSAL_Direct_SetRamFileSize(STFSAL *pstFSAL, kal_uint32 uSize);

/**
 * When writing to ram file, if after a write operation, the file offset exceeds
 * the specified ram file size, an assertion will be issued in order to detect
 * memory corruption.
 */
void FSAL_Direct_SetMaxRamFileSize(STFSAL *pstFSAL, kal_uint32 uSize);

/**
 * Get the last file system error.
 */
int FSAL_GetLastError(STFSAL *pstFSAL);

/**
 * If the pstFSAL is a handle of ram file, return KAL_TRUE; otherwise return KAL_FALSE.
 */
kal_bool FSAL_IsRamFile(STFSAL *pstFSAL);

/**
 * If the pstFSAL is a handle of ram file, return pointer to the memory block; otherwise return NULL.
 */
kal_uint8* FSAL_GetRamFilePointer(STFSAL *pstFSAL);

#endif