Skip to content

Latest commit

 

History

History
1365 lines (932 loc) · 42.5 KB

api.md

File metadata and controls

1365 lines (932 loc) · 42.5 KB

Summary

Members Descriptions
class Arduino_UnifiedStorage Abstract class representing the common features of the supported storage methods
class Folder Class representing a directory.
class InternalStorage Represents internal storage using the Arduino Unified Storage library.
class Partitioning
class SDStorage Represents an SD card storage using the Arduino Unified Storage library.
class UFile Class representing a File
class USBStorage USBStorage class provides an interface to access USB storage devices. It inherits from the Arduino_UnifiedStorage class and implements its pure virtual functions.
struct Partition

class Arduino_UnifiedStorage

Abstract class representing the common features of the supported storage methods

Summary

Members Descriptions
begin Initializes the storage.
begin Initializes the storage with the specified file system.
unmount Unmounts the storage.
getRootFolder Retrieves the root folder of the storage.
format Formats the storage with the selected file system.
debugPrint
testPrint

Members

begin 

bool begin()

Initializes the storage.

Returns

true if successful, false if failed.

begin 

bool begin(FileSystems fs)

Initializes the storage with the specified file system.

Parameters

  • fs The desired file system (FS_FAT or FS_LITTLEFS).

Returns

true if successful, false if failed.

unmount 

bool unmount()

Unmounts the storage.

Returns

true if successful, false if failed.

getRootFolder 

Folder getRootFolder()

Retrieves the root folder of the storage.

Returns

The root folder as a Folder object.

format 

bool format(FileSystems fs)

Formats the storage with the selected file system.

Returns

true if successful, false if failed.

debugPrint 

static void debugPrint(String message)

testPrint 

static void testPrint(String message)

class Folder

Class representing a directory.

Summary

Members Descriptions
Folder Creates an empty Folder object. Please note that any operation on this object will fail until a valid directory is assigned to it.
Folder Creates a directory with the specified name. If the directory already exists, it returns a Folder object representing the existing directory. Otherwise, it tries to create a new directory with the specified name. If it fails the path property of the Folder object will be null.
Folder Creates a directory with the specified name. If the directory already exists, it returns a Folder object representing the existing directory. Otherwise, it tries to create a new directory with the specified name. If it fails the path property of the Folder object will be empty.
createFile Creates a file inside the directory.
createFile Creates a file inside the directory.
remove Removes a directory.
rename Renames a directory.
rename Renames a directory.
exists Checks if the directory exists.
getPath Returns the path of the file.
getPathAsString Returns the path of the file.
createSubfolder Creates a subfolder in the directory.
createSubfolder Creates a subfolder in the directory.
getFiles Returns File objects for all files in the current directory.
getFolders Returns Folder objects for all files in the current directory.
copyTo Copies the current directory.
copyTo Copies the current directory.
copyTo Copies the current directory.
moveTo Moves the current directory.
moveTo Moves the current directory.
moveTo Move the current directory.

Members

Folder 

Folder()

Creates an empty Folder object. Please note that any operation on this object will fail until a valid directory is assigned to it.

Folder 

Folder(const char * dirname)

Creates a directory with the specified name. If the directory already exists, it returns a Folder object representing the existing directory. Otherwise, it tries to create a new directory with the specified name. If it fails the path property of the Folder object will be null.

Parameters

  • const char * dirname - The name of the directory.

Folder 

Folder(String dirname)

Creates a directory with the specified name. If the directory already exists, it returns a Folder object representing the existing directory. Otherwise, it tries to create a new directory with the specified name. If it fails the path property of the Folder object will be empty.

Parameters

  • String dirname - The name of the directory.

createFile 

UFile createFile(const char * fileName, FileMode fmode)

Creates a file inside the directory.

Parameters

  • const char * fileName - The name of the file to create.

Returns

A File object if successful, NULL if not.

createFile 

UFile createFile(String fileName, FileMode fmode)

Creates a file inside the directory.

Parameters

  • String fileName - The name of the file to create.

Returns

A File object if successful, NULL if not.

remove 

bool remove()

Removes a directory.

Returns

True if the directory was removed successfully, false otherwise.

rename 

bool rename(const char * newDirname)

Renames a directory.

Parameters

  • const char * newDirname The new name of the directory.

Returns

True if the directory was renamed successfully, false otherwise.

rename 

bool rename(String newDirname)

Renames a directory.

Parameters

  • String newDirname The new name of the directory.

Returns

True if the directory was renamed successfully, false otherwise.

exists 

bool exists()

Checks if the directory exists.

Returns

True if the directory exists, false otherwise.

getPath 

const char * getPath()

Returns the path of the file.

Returns

The path of the file as a const char *

getPathAsString 

String getPathAsString()

Returns the path of the file.

Returns

The path of the file as an Arduino String

createSubfolder 

Folder createSubfolder(const char * subfolderName, bool overwrite)

Creates a subfolder in the directory.

Parameters

  • const char * subfolderName - he name of the subfolder to create.

  • overwrite - behaviour in case the folder already exists, default is false

Returns

The created subfolder.

createSubfolder 

Folder createSubfolder(String subfolderName, bool overwrite)

Creates a subfolder in the directory.

Parameters

  • String subfolderName - he name of the subfolder to create.

  • overwrite - behaviour in case the folder already exists, default is false

Returns

The created subfolder.

getFiles 

std::vector< UFile > getFiles()

Returns File objects for all files in the current directory.

Returns

A std::vector of File objects representing the files in the directory.

getFolders 

std::vector< Folder > getFolders()

Returns Folder objects for all files in the current directory.

Returns

A std::vector of Folder objects representing the files in the directory.

copyTo 

bool copyTo( Folder destination, bool overwrite)

Copies the current directory.

Parameters

  • [Folder](#class_folder) destination - a Folder object representing the destination

Returns

True upon success, false otherwise.

copyTo 

bool copyTo(const char * destination, bool overwrite)

Copies the current directory.

Parameters

  • const char * destination - the path of the destination location

  • overwrite - behaviour in case the folder already exists, default is false

Returns

True upon success, false otherwise.

copyTo 

bool copyTo(String destination, bool overwrite)

Copies the current directory.

Parameters

  • String destination - the path of the destination location

  • overwrite - behaviour in case the folder already exists, default is false

Returns

True upon success, false otherwise.

moveTo 

bool moveTo( Folder destination, bool overwrite)

Moves the current directory.

Parameters

  • [Folder](#class_folder) destination - a Folder object representing the destination

  • overwrite - behaviour in case the folder already exists, default is false

Returns

True upon success, false otherwise.

moveTo 

bool moveTo(const char * destination, bool overwrite)

Moves the current directory.

Parameters

  • const char * destination - the path of the destination location

  • overwrite - behaviour in case the folder already exists, default is false

Returns

True upon success, false otherwise.

moveTo 

bool moveTo(String destination, bool overwrite)

Move the current directory.

Parameters

  • String destination - the path of the destination location

  • overwrite - behaviour in case the folder already exists, default is false

Returns

True upon success, false otherwise.

class InternalStorage 

class InternalStorage
  : public Arduino_UnifiedStorage

Represents internal storage using the Arduino Unified Storage library.

Summary

Members Descriptions
InternalStorage Constructs an InternalStorage object with default settings. If no partitions are available, it restores the default partitioning scheme (See restoreDefaultPartitions() for more info). If partitions are available, it sets the partition number, file system type, and partition name based on the last partition available. When using the default partitioning scheme the last partition would be the user partition.
InternalStorage Constructs an InternalStorage object with the specified partition, name, and file system.
begin Initializes the internal storage.
begin Initializes the internal storage with the specified file system.
unmount Unmounts the internal storage.
getRootFolder Retrieves the root folder of the internal storage.
format Formats the internal storage with the selected file system.
getBlockDevice Retrieves the block device associated with the internal storage.
partition Partitions the internal storage according to the partitioning scheme given in the partitions parameter erasing the existing partitions
partition Creates one partition spanning over the whole size of the internal storage drive erasing the existing partitions.
restoreDefaultPartitions Restores the default partitioning scheme (1MB FAT32 for Certificates, 5MB FAT32 for OTA, 8MB user storage) to the internal storage drive erasing the existing partitions.
readPartitions Reads the partitioning scheme from the MBR sector of the internal storage drive and returns a vector of structs of type Partition that represents the partitioning scheme

Members

InternalStorage 

InternalStorage()

Constructs an InternalStorage object with default settings. If no partitions are available, it restores the default partitioning scheme (See restoreDefaultPartitions() for more info). If partitions are available, it sets the partition number, file system type, and partition name based on the last partition available. When using the default partitioning scheme the last partition would be the user partition.

InternalStorage 

InternalStorage(int partition, const char * name, FileSystems fs)

Constructs an InternalStorage object with the specified partition, name, and file system.

Parameters

  • partition The partition number.

  • name The name of the partition.

  • fs The desired file system (FS_FAT or FS_LITTLEFS).

begin 

virtual bool begin()

Initializes the internal storage.

Returns

true if successful, false if failed.

begin 

virtual bool begin(FileSystems fs)

Initializes the internal storage with the specified file system.

Parameters

  • fs The desired file system (FS_FAT or FS_LITTLEFS).

Returns

true if successful, false if failed.

unmount 

virtual bool unmount()

Unmounts the internal storage.

Returns

true if successful, false if failed.

getRootFolder 

virtual Folder getRootFolder()

Retrieves the root folder of the internal storage.

Returns

The root folder as a Folder object.

format 

virtual bool format(FileSystems fs)

Formats the internal storage with the selected file system.

Returns

true if successful, false if failed.

getBlockDevice 

BlockDeviceType * getBlockDevice()

Retrieves the block device associated with the internal storage.

Returns

The block device as a BlockDevice object.

partition 

static bool partition(std::vector< Partition > partitions)

Partitions the internal storage according to the partitioning scheme given in the partitions parameter erasing the existing partitions

Parameters

  • partitions - vector of structs of type Partition that represents the partitioning scheme

Returns

true if successful, false if failed.

partition 

static bool partition()

Creates one partition spanning over the whole size of the internal storage drive erasing the existing partitions.

Returns

true if successful, false if failed.

restoreDefaultPartitions 

static bool restoreDefaultPartitions()

Restores the default partitioning scheme (1MB FAT32 for Certificates, 5MB FAT32 for OTA, 8MB user storage) to the internal storage drive erasing the existing partitions.

Returns

true if successful, false if failed.

readPartitions 

static std::vector< Partition > readPartitions()

Reads the partitioning scheme from the MBR sector of the internal storage drive and returns a vector of structs of type Partition that represents the partitioning scheme

Returns

vector of structs of type Partition

class Partitioning

Summary

Members Descriptions
eraseMBRSector Erases the first block (4096 bytes) of the BlockDevice to delete any already existing MBR partition table
partitionDrive Partitions the BlockDevice according to the partitioning schemme given by the vector of Partition structs
readPartitions Reads and unpacks the MBR partition information and returns a list of partitions it can find on the drive

Members

eraseMBRSector 

static bool eraseMBRSector(BlockDeviceType * blockDevice)

Erases the first block (4096 bytes) of the BlockDevice to delete any already existing MBR partition table

Parameters

  • The BlockDevice on which the MBR sector is situated.

Returns

True upon success, False on failure

partitionDrive 

static bool partitionDrive(BlockDeviceType * blockDevice, std::vector< Partition > partitions)

Partitions the BlockDevice according to the partitioning schemme given by the vector of Partition structs

Parameters

  • blockDevice - the BlockDevice which we would like to partition.

  • partitions - a vector of Partition structs that represents the partitioning scheme

Returns

True upon success, False on failure

readPartitions 

static std::vector< Partition > readPartitions(BlockDeviceType * blockDevice)

Reads and unpacks the MBR partition information and returns a list of partitions it can find on the drive

Parameters

  • blockDevice on which the MBR sector is situated.

Returns

std::vector of Partition containing size and filesystem information about each partition

class SDStorage 

class SDStorage
  : public Arduino_UnifiedStorage

Represents an SD card storage using the Arduino Unified Storage library.

Summary

Members Descriptions
SDStorage Default constructor for the SDStorage class.
begin Initializes the SD card storage.
begin Initializes the SD card storage with the specified file system.
unmount Unmounts the SD card storage.
getRootFolder Retrieves the root folder of the SD card storage.
format Formats the SD card storage with the selected file system.

Members

SDStorage 

SDStorage()

Default constructor for the SDStorage class.

begin 

virtual bool begin()

Initializes the SD card storage.

Returns

true if successful, false if failed.

begin 

virtual bool begin(FileSystems fs)

Initializes the SD card storage with the specified file system.

Parameters

  • fs The desired file system (FS_FAT or FS_LITTLEFS).

Returns

true if successful, false if failed.

unmount 

virtual bool unmount()

Unmounts the SD card storage.

Returns

true if successful, false if failed.

getRootFolder 

virtual Folder getRootFolder()

Retrieves the root folder of the SD card storage.

Returns

The root folder as a Folder object.

format 

virtual bool format(FileSystems fs)

Formats the SD card storage with the selected file system.

Returns

true if successful, false if failed.

class UFile

Class representing a File

Summary

Members Descriptions
UFile Constructor.
UFile Constructor.
~UFile
changeMode Closes the file, and opens it again with a new file mode.
open Opens a file with the specified mode.
open Opens a file with the specified mode.
close Closes the file and releases any allocated resources.
seek Seeks to a specific position in the file.
read Reads data from the file into a buffer.
readAsString Reads the contents of the file as an Arduino String.
write Writes data to the file from a buffer.
write Writes a string to the file.
remove Removes the file.
rename Renames the file.
rename Renames the file.
exists Checks if the file exists.
copyTo Copies the file to the specified destination path.
copyTo Copies the file to the specified destination path.
copyTo Copies the file to the specified destination path.
moveTo Moves the file to the specified destination path.
moveTo Moves the file to the specified destination path.
moveTo Copies the file to the specified destination folder.
getParentFolder Returns a reference to the parent folder of the current folder.
getPath Returns the path of the directory.
getPathAsString Returns the path of the directory.
available Returns the number of bytes available to read.
read Returns one byte from the file.
write Writes one byte to the file.

Members

UFile 

UFile()

Constructor.

UFile 

UFile(const char * path)

Constructor.

Parameters

  • const char * path - path of the file

~UFile 

~UFile()

changeMode 

bool changeMode(FileMode mode)

Closes the file, and opens it again with a new file mode.

Parameters

  • mode The file mode (READ, WRITE, or APPEND).

Returns

True if operation was successful, false otherwise.

open 

bool open(const char * filename, FileMode mode)

Opens a file with the specified mode.

Parameters

  • const char * filename - The name of the file to open.

  • mode The file mode (READ, WRITE, or APPEND).

Returns

True if the file was opened successfully, false otherwise.

open 

bool open(String filename, FileMode mode)

Opens a file with the specified mode.

Parameters

  • String filename - The name of the file to open.

  • mode The file mode (READ, WRITE, or APPEND).

Returns

True if the file was opened successfully, false otherwise.

close 

void close()

Closes the file and releases any allocated resources.

seek 

bool seek(size_t offset)

Seeks to a specific position in the file.

Parameters

  • offset The offset from the beginning of the file.

Returns

True if the seek operation was successful, false otherwise.

read 

size_t read(uint8_t * buffer, size_t size)

Reads data from the file into a buffer.

Parameters

  • buffer The buffer to read data into.

  • size The size of the buffer.

Returns

The number of bytes read from the file.

readAsString 

String readAsString()

Reads the contents of the file as an Arduino String.

Returns

The file contents as a String.

write 

size_t write(const uint8_t * buffer, size_t size)

Writes data to the file from a buffer.

Parameters

  • buffer The buffer containing the data to write.

  • size The size of the data to write.

Returns

The number of bytes written to the file.

write 

size_t write(String)

Writes a string to the file.

Parameters

  • data The string to write.

Returns

The number of bytes written to the file.

remove 

bool remove()

Removes the file.

Returns

True if the file was removed successfully, false otherwise.

rename 

bool rename(const char * newFilename)

Renames the file.

Parameters

  • const char * newFilename The new name of the file.

Returns

True if the file was renamed successfully, false otherwise.

rename 

bool rename(String newFilename)

Renames the file.

Parameters

  • String newFilename The new name of the file.

Returns

True if the file was renamed successfully, false otherwise.

exists 

bool exists()

Checks if the file exists.

Returns

True if the file exists, false otherwise.

copyTo 

bool copyTo(const char * destinationPath, bool overwrite)

Copies the file to the specified destination path.

Parameters

  • const char * destinationPath - The destination path to copy the file to.

Returns

True upon success, false otherwise.

copyTo 

bool copyTo(String destinationPath, bool overwrite)

Copies the file to the specified destination path.

Parameters

  • String destinationPath The destination path to copy the file to.

Returns

True upon success, false otherwise.

copyTo 

bool copyTo( Folder destinationFolder, bool overwrite)

Copies the file to the specified destination path.

Parameters

  • [Folder](#class_folder) destinationPath - The destination folder to copy the file to.

Returns

True upon success, false otherwise.

moveTo 

bool moveTo(const char * destinationPath, bool overwrite)

Moves the file to the specified destination path.

Parameters

  • const char * destinationPath The destination path to move the file to.

Returns

True upon success, false otherwise.

moveTo 

bool moveTo(String destinationPath, bool overwrite)

Moves the file to the specified destination path.

Parameters

  • String destinationPath The destination path to move the file to.

Returns

True upon success, false otherwise.

moveTo 

bool moveTo( Folder destinationFolder, bool overwrite)

Copies the file to the specified destination folder.

Parameters

  • [Folder](#class_folder) destinationFolder The destination directory to move the file to.

Returns

True upon success, false otherwise.

getParentFolder 

Folder getParentFolder()

Returns a reference to the parent folder of the current folder.

Returns

A directory object representing the current folder.

getPath 

const char * getPath()

Returns the path of the directory.

Returns

The path of the file as a const char *

getPathAsString 

String getPathAsString()

Returns the path of the directory.

Returns

The path of the file as a String

available 

uint32_t available()

Returns the number of bytes available to read.

Returns

The number of bytes available to read as int

read 

int read()

Returns one byte from the file.

Returns

An int representing one byte from the file

write 

size_t write(uint8_t value)

Writes one byte to the file.

Parameters

  • a uint8_t value representing the byte to write

class USBStorage 

class USBStorage
  : public Arduino_UnifiedStorage

USBStorage class provides an interface to access USB storage devices. It inherits from the Arduino_UnifiedStorage class and implements its pure virtual functions.

Summary

Members Descriptions
USBStorage Default constructor for the USBStorage class.
begin Initializes the USB storage.
begin Initializes the USB storage with the specified file system.
unmount Unmounts the USB storage.
getRootFolder Retrieves the root folder of the USB storage.
format Formats the USB storage with the selected file system.
isMounted Checks if the USB storage is mounted.
onConnect Sets the callback function to be called when a USB connection is established.
removeOnConnectCallback Removes the callback function that is executed when the USB storage device is connected.
onDisconnect Sets a callback function to be called when the USB storage device is disconnected.
removeOnDisconnectCallback Removes the callback function that is called when the USB storage device is disconnected.

Members

USBStorage 

USBStorage()

Default constructor for the USBStorage class.

begin 

virtual bool begin()

Initializes the USB storage.

Returns

true if successful, false if failed.

begin 

virtual bool begin(FileSystems fs)

Initializes the USB storage with the specified file system.

Parameters

  • fs The desired file system (FS_FAT or FS_LITTLEFS).

Returns

true if successful, false if failed.

unmount 

virtual bool unmount()

Unmounts the USB storage.

Returns

true if successful, false if failed.

getRootFolder 

virtual Folder getRootFolder()

Retrieves the root folder of the USB storage.

Returns

The root folder as a Folder object.

format 

virtual bool format(FileSystems fs)

Formats the USB storage with the selected file system.

Returns

true if successful, false if failed.

isMounted 

bool isMounted()

Checks if the USB storage is mounted.

Returns

true if mounted, false otherwise.

onConnect 

void onConnect(void(*)() callbackFunction)

Sets the callback function to be called when a USB connection is established.

Parameters

  • callbackFunction A pointer to the function to be called when a USB connection is established.

removeOnConnectCallback 

void removeOnConnectCallback()

Removes the callback function that is executed when the USB storage device is connected.

onDisconnect 

void onDisconnect(void(*)() callbackFunction)

Sets a callback function to be called when the USB storage device is disconnected.

Parameters

  • callbackFunction A pointer to the function to be called when the USB storage device is disconnected.

removeOnDisconnectCallback 

void removeOnDisconnectCallback()

Removes the callback function that is called when the USB storage device is disconnected.

struct Partition

Summary

Members Descriptions
size
fileSystemType

Members

size 

int size

fileSystemType 

FileSystems fileSystemType