mirror of
https://github.com/mudita/MuditaOS.git
synced 2026-07-04 05:06:58 -04:00
353 lines
17 KiB
C
353 lines
17 KiB
C
/*
|
|
* Copyright 2008 - 2014 Stonestreet One.
|
|
* All Rights Reserved.
|
|
* Author: David Wooldridge
|
|
*** MODIFICATION HISTORY ****************************************************
|
|
*
|
|
* mm/dd/yy F. Lastname Description of Modification
|
|
* -------- ----------- ------------------------------------------------
|
|
* 03/05/08 D. Wooldridge Initial implementation.
|
|
* 06/17/09 D. Lange Updated to support new API type schema.
|
|
****************************************************************************
|
|
*/
|
|
|
|
/**
|
|
* @file BFILEAPI.h
|
|
*
|
|
* @brief Stonestreet One Bluetooth Stack File Access Abstraction API
|
|
* Type Definitions, Constants, and Prototypes. To use any of the following API's,
|
|
* include the following declaration in your application.
|
|
*
|
|
* @code
|
|
* #include "BTPSFILE.h"
|
|
* @endcode
|
|
* ============================================================================
|
|
*/
|
|
#ifndef __BFILEAPIH__
|
|
#define __BFILEAPIH__
|
|
|
|
#include "BTAPITyp.h" /*! Bluetooth API Type Definitions. */
|
|
#include "BTTypes.h" /*! Bluetooth basic type definitions */
|
|
|
|
/*! The following values define the valid return values for the
|
|
* BTPS_Make_Directory() function.
|
|
*/
|
|
#define BTPS_FILE_MAKE_DIRECTORY_SUCCESS 0
|
|
#define BTPS_FILE_MAKE_DIRECTORY_ERROR_ALREADY_EXISTS (-1)
|
|
#define BTPS_FILE_MAKE_DIRECTORY_ERROR_UNABLE_TO_CREATE (-2)
|
|
|
|
/*! The following type is a generic container type that represents a
|
|
* File Descriptor (supported by this module).
|
|
*/
|
|
typedef void *BTPS_File_Descriptor_t;
|
|
|
|
/*! The following type is a generic container type that represents a
|
|
* Directory Descriptor (supported by this module).
|
|
*/
|
|
typedef void *BTPS_Directory_Descriptor_t;
|
|
|
|
/*! The following enumerated type defines the supported File Types
|
|
* that this module can detect and report.
|
|
*/
|
|
typedef enum
|
|
{
|
|
ftUnknown,
|
|
ftFile,
|
|
ftDirectory,
|
|
ftLink
|
|
} BTPS_File_Type_t;
|
|
|
|
/*! The following enumerated type defines the supported modes that can
|
|
* be specified to open an individual file.
|
|
*/
|
|
typedef enum
|
|
{
|
|
omReadOnly,
|
|
omWriteOnly,
|
|
omReadWrite,
|
|
omCreate,
|
|
omAppend
|
|
} BTPS_Open_Mode_t;
|
|
|
|
/*! The following enumerated type defines the supported modes that can
|
|
* be specified to seek to a particular offset in an individual file.
|
|
*/
|
|
typedef enum
|
|
{
|
|
smBeginning,
|
|
smCurrent,
|
|
smEnd
|
|
} BTPS_Seek_Mode_t;
|
|
|
|
/*! The following structure defines the Date/Time Information that
|
|
* this module can detect and report.
|
|
*/
|
|
typedef struct _tagBTPS_File_Time_t
|
|
{
|
|
Word_t Seconds;
|
|
Word_t Minute;
|
|
Word_t Hour;
|
|
Word_t DayOfMonth;
|
|
Word_t Month;
|
|
Word_t Year;
|
|
Boolean_t UTC_Time;
|
|
} BTPS_File_Time_t;
|
|
|
|
#define BTPS_FILE_TIME_SIZE (sizeof(BTPS_File_Time_t))
|
|
|
|
/*! The following structure represents the information that this
|
|
* module supports for complete File Information about a particular
|
|
* File/Directory entry.
|
|
*/
|
|
typedef struct _tagBTPS_File_Information_t
|
|
{
|
|
BTPS_File_Type_t FileType;
|
|
DWord_t FileSize;
|
|
BTPS_File_Time_t FileTime;
|
|
} BTPS_File_Information_t;
|
|
|
|
#define BTPS_FILE_INFORMATION_SIZE (sizeof(BTPS_File_Information_t))
|
|
|
|
/*! @brief The following function is provided to allow a mechanism for the
|
|
* caller to create a directory. @param Path The parameter to this function
|
|
* specifies the (path qualified) directory name to create.
|
|
* @return This function returns one of the following:
|
|
* - BTPS_FILE_MAKE_DIRECTORY_SUCCESS
|
|
* - BTPS_FILE_MAKE_DIRECTORY_ERROR_ALREADY_EXISTS
|
|
* - BTPS_FILE_MAKE_DIRECTORY_ERROR_UNABLE_TO_CREATE
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION int BTPSAPI BTPS_Make_Directory(BTPSCONST char *Path);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef int (BTPSAPI *PFN_BTPS_Make_Directory_t)(BTPSCONST char *Path);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechanism for the
|
|
* caller to delete a specified file. @param Path The parameter to this
|
|
* function specifies the (path qualified) file name to delete.
|
|
* @return This function returns a BOOLEAN TRUE if successful, or FALSE if an
|
|
* error occurred.
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Delete_File(BTPSCONST char *Path);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Delete_File_t)(BTPSCONST char *Path);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechanism for the
|
|
* caller to delete a specified directory. @param Path The parameter to this
|
|
* function specifies the (path qualified) directory name to delete.
|
|
* @return This function returns a BOOLEAN TRUE if successful, or FALSE if an
|
|
* error occurred.
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Delete_Directory(BTPSCONST char *Path);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Delete_Directory_t)(BTPSCONST char *Path);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechanism for the
|
|
* caller to open a file (of the specified file name). @param Path This first
|
|
* parameter to this function specifies the (path qualified) name of
|
|
* the file to open. @param OpenMode The final parameter specifies the mode that
|
|
* the file is to be opened with. The supported modes are:
|
|
* - omReadOnly - open for read only access
|
|
* - omWriteOnly - open for write only access
|
|
* - omReadWrite - open for read/write access
|
|
* - omCreate - create new file (truncate if already exists)
|
|
* - omAppend - open for writing (create if doesn't exist)
|
|
* @return This function returns a NON-NULL File Descriptor if the specified
|
|
* file was opened successfully, or NULL if there was an error.
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION BTPS_File_Descriptor_t BTPSAPI BTPS_Open_File(BTPSCONST char *Path, BTPS_Open_Mode_t OpenMode);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef BTPS_File_Descriptor_t (BTPSAPI *PFN_BTPS_Open_File_t)(BTPSCONST char *Path, BTPS_Open_Mode_t OpenMode);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to close a file that was previously successfully opened via
|
|
* the BTPS_Open_File() function.
|
|
* This function accepts as @param FileDescriptor The first parameter the NON-NULL File Descriptor (successful return value
|
|
* from the BTPS_Open_File() function).
|
|
*/
|
|
BTPSAPI_DECLARATION void BTPSAPI BTPS_Close_File(BTPS_File_Descriptor_t FileDescriptor);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef void (BTPSAPI *PFN_BTPS_Close_File_t)(BTPS_File_Descriptor_t FileDescriptor);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to seek to specific byte offset within the specified file.
|
|
* @param FileDescriptor The first parameter specifies the file descriptor of the
|
|
* previously opened file (via the BTPS_Open_File() function).
|
|
* @param SeekMode The second parameter specifies the location to apply the Seek Offset
|
|
* to (final parameter). The values that this parameter can be is
|
|
* one of the following:
|
|
* - smBeginning - Apply SeekOffset from beginning of file
|
|
* - smCurrent - Apply SeekOffset from current location in file
|
|
* - smEnd - Apply SeekOffset from end of file
|
|
* @param SeekOffset The final parameter, SeekOffset, specifies the offset (in bytes)
|
|
* to seek (taking into account the Seek Mode type - second
|
|
* parameter). This function will return BOOLEAN TRUE if successful
|
|
* or a FALSE if there was an error.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Seek_File(BTPS_File_Descriptor_t FileDescriptor, BTPS_Seek_Mode_t SeekMode, SDWord_t SeekOffset);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Seek_File_t)(BTPS_File_Descriptor_t FileDescriptor, BTPS_Seek_Mode_t SeekMode, SDWord_t SeekOffset);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to read data from a previously opened file. @param FileDescriptor The first parameter specifies the file descriptor of the previously opened
|
|
* file (via the BTPS_Open_File() function). @param BufferSize The second parameter
|
|
* specifies the number of bytes to read from the file. @param Buffer The third parameter specifies the Buffer to read the data into (must be
|
|
* (at least) as many bytes as specified by the second parameter).
|
|
* @param BytesRead The final parameter is optional, and if specified, points to a
|
|
* buffer that will contain (on success) the number of bytes that
|
|
* were actually read and placed into the buffer.
|
|
* @return This function returns BOOLEAN TRUE if the data was successfully read or a
|
|
* BOOLEAN FALSE if an error occurred.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Read_File(BTPS_File_Descriptor_t FileDescriptor, DWord_t BufferSize, Byte_t *Buffer, DWord_t *BytesRead);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Read_File_t)(BTPS_File_Descriptor_t FileDescriptor, DWord_t BufferSize, Byte_t *Buffer, DWord_t *BytesRead);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to write data to a previously opened file.
|
|
* @param FileDescriptor The first parameter specifies the file descriptor of the previously opened
|
|
* file (via the BTPS_Open_File() function). @param BufferSize The second parameter
|
|
* specifies the number of bytes to write to the file.
|
|
* @param Buffer The third parameter specifies the Buffer that contains the bytes to write to
|
|
* the file (must be (at least) as many bytes as specified by the second parameter).
|
|
* @param BytesWritten The first parameter is optional, and if
|
|
* specified, points to a buffer that will contain (on success) the
|
|
* number of bytes that were actually written to the file.
|
|
* @return This function returns BOOLEAN TRUE if the data was successfully read or
|
|
* a BOOLEAN FALSE if an error occurred.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Write_File(BTPS_File_Descriptor_t FileDescriptor, DWord_t BufferSize, Byte_t *Buffer, DWord_t *BytesWritten);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Write_File_t)(BTPS_File_Descriptor_t FileDescriptor, DWord_t BufferSize, Byte_t *Buffer, DWord_t *BytesWritten);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to begin the process of iterating through the directory
|
|
* specified by this function. This is useful to iterate through all
|
|
* entries contained in the specified directory (see
|
|
* BTPS_Get_Next_Directory_Entry() for more information).
|
|
* @param Path The first parameter to this function specifies the (path qualified)
|
|
* directory name to open. @return This function returns a NON-NULL
|
|
* directory descriptor if successful, or NULL if there as an error.
|
|
* If this function returns success, then this return value can be
|
|
* passed to the BTPS_Get_Next_Directory_Entry() and the
|
|
* BTPS_Close_Directory() functions.
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION BTPS_Directory_Descriptor_t BTPSAPI BTPS_Open_Directory(BTPSCONST char *Path);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef BTPS_Directory_Descriptor_t (BTPSAPI *PFN_BTPS_Open_Directory_t)(BTPSCONST char *Path);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to close a directory that was previously successfully
|
|
* opened via the BTPS_Open_Directory() function. This function
|
|
* accepts as @param DirectoryDescriptor The first parameter the NON-NULL Directory Descriptor
|
|
* (successful return value from the BTPS_Open_Directory() function).
|
|
*/
|
|
BTPSAPI_DECLARATION void BTPSAPI BTPS_Close_Directory(BTPS_Directory_Descriptor_t DirectoryDescriptor);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef void (BTPSAPI *PFN_BTPS_Close_Directory_t)(BTPS_Directory_Descriptor_t DirectoryDescriptor);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechansim for the
|
|
* caller to interate through the directory entries contained in the
|
|
* directory specified by the specified Directory Descriptor.
|
|
* @param DirectoryDescriptor The first parameter specifies the Directory Descriptor (obtained from
|
|
* a previously successful call to the BTP_Open_Directory() function)
|
|
* which specifies the directory to iterate through.
|
|
* @param EntryName The final parameter specifies the last retrieved directory entry name that
|
|
* was returned from this function (to iterate to the next entry), or
|
|
* an empty string if this is the first time this function is being
|
|
* called for the specified directory. If this function is
|
|
* successful, it will return a BOOLEAN TRUE value and the buffer
|
|
* pointed to by the final parmeter will contain the name of the next
|
|
* directory entry. If @return This function returns FALSE then the contents
|
|
* of this buffer will be undefined (error occurred).
|
|
* \note The final parameter *MUST* point to a buffer that is
|
|
* (at least) BTPS_MAXIMUM_FILE_NAME_LENGTH bytes long.
|
|
* \note The directory entry names returned from this function
|
|
* are not path qualified (i.e. they do not contain the
|
|
* path of the actual directory name in them).
|
|
* \note The final parameter should point to an empty string
|
|
* (first character is a NULL character) to signify that the
|
|
* first directory entry should be retrieved. After this,
|
|
* this parameter should specify the previously returned
|
|
* directory entry name (to retrieve the next entry).
|
|
* \note The value that is returned in the first parameter will
|
|
* be in the UTF-8 character set (NULL terminated).
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Get_Next_Directory_Entry(BTPS_Directory_Descriptor_t DirectoryDescriptor, char *EntryName);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Get_Next_Directory_Entry_t)(BTPS_Directory_Descriptor_t DirectoryDescriptor, char *EntryName);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechanism for the
|
|
* caller to determine if the specified Path, specifies the Root of
|
|
* a drive.
|
|
* @param Path The first parameter to this function specifies the (path qualified)
|
|
* directory name to open.
|
|
* Examples of this function returning TRUE are:
|
|
* - C:\ - TRUE on Windows based machines
|
|
* - / - TRUE on Linux/UNIX based machines
|
|
* @return This function returns a BOOLEAN TRUE if the specified Path
|
|
* specifies the root directory of a drive, or FALSE, otherwise.
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Query_Directory_Is_Root_Of_Drive(BTPSCONST char *Path);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Query_Directory_Is_Root_Of_Drive_t)(BTPSCONST char *Path);
|
|
#endif
|
|
|
|
/*! @brief The following function is provided to allow a mechanism for the
|
|
* caller to obtain File Information about a specific File or
|
|
* directory. @param Path The first parameter to this function specifies the
|
|
* (path qualified) file or directory name to query the information
|
|
* about. @param FileInformation The second parameter specifies a buffer that will contain
|
|
* the File/Directory information on return if this function is
|
|
* successful. @return This function returns a BOOLEAN TRUE if successful,
|
|
* or FALSE if an error occurred. Note that the final parameter is
|
|
* *CANNOT* be NULL and must point to a valid buffer to store the
|
|
* information into. If this function returns success (TRUE) then
|
|
* this buffer will contain the file information for the specified
|
|
* input file/directory. If this function returns an error (FALSE)
|
|
* then the contents of the buffer pointed to by the final parameter
|
|
* will be undefined.
|
|
* \note The Path parameter should be specified in the UTF-8
|
|
* character set.
|
|
*/
|
|
BTPSAPI_DECLARATION Boolean_t BTPSAPI BTPS_Query_File_Information(BTPSCONST char *Path, BTPS_File_Information_t *FileInformation);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef Boolean_t (BTPSAPI *PFN_BTPS_Query_File_Information_t)(BTPSCONST char *Path, BTPS_File_Information_t *FileInformation);
|
|
#endif
|
|
|
|
#endif
|