Skip to content

Commit b9a2cb4

Browse files
sebromerosebromero
authored
Merge pull request #8 from arduino-libraries/api-docs
Add API documentation
2 parents 27a8ebf + 84a2ede commit b9a2cb4

File tree

3 files changed

+115
-61
lines changed

3 files changed

+115
-61
lines changed

‎docs/README.md

+1-60
Original file line numberDiff line numberDiff line change
@@ -41,66 +41,7 @@ Many ISO C standard functions are also made available. For example: fopen, fprin
4141

4242
Start pathnames on SD Cards with "/sdcard/" and pathnames on USB thumb drives with "/usb/". See the Examples section below for examples.
4343

44-
The following are additional functions provided by the library:
45-
46-
### `int` [`mount`](#)`(enum StorageDevices deviceName, enum FileSystems fileSystem, enum MountFlags mountFlags)`
47-
48-
Attach a file system to a device.
49-
50-
#### Parameters
51-
* `deviceName` The device to attach to: DEV_SDCARD or DEV_USB.
52-
* `fileSystem` The file system type to attach: FS_FAT or FS_LITTLEFS.
53-
* `mountFlags` The only valid flag at this time: MNT_DEFAULT (future platforms might also support MNT_RDONLY).
54-
55-
#### Returns
56-
On success: 0. On failure: -1 with an error code in the errno variable.
57-
58-
59-
### `int` [`umount`](#)`(enum StorageDevices deviceName)`
60-
61-
Remove the attached file system from a device.
62-
63-
#### Parameters
64-
* `deviceName` The device to remove from: DEV_SDCARD or DEV_USB.
65-
66-
#### Returns
67-
On success: 0. On failure: -1 with an error code in the errno variable.
68-
69-
70-
### `int` [`register_hotplug_callback`](#)`(enum StorageDevices deviceName, void (*callbackFunction)())`
71-
72-
Register a hotplug callback function. Currently only supported for DEV_USB on Portenta C33.
73-
74-
#### Parameters
75-
* `deviceName` The device to register for: DEV_SDCARD or DEV_USB.
76-
* `callbackFunction` A function pointer to the callback.
77-
78-
#### Returns
79-
On success: 0. On failure: -1 with an error code in the errno variable.
80-
81-
82-
### `int` [`deregister_hotplug_callback`](#)`(enum StorageDevices deviceName)`
83-
84-
Deregister a previously registered hotplug callback function. Not currently supported on any platform.
85-
86-
#### Parameters
87-
* `deviceName` The device to deregister for: DEV_SDCARD or DEV_USB.
88-
89-
#### Returns
90-
On success: 0. On failure: -1 with an error code in the errno variable.
91-
92-
93-
### `int` [`mkfs`](#)`(enum StorageDevices deviceName, enum FileSystems fileSystem)`
94-
95-
Format a device (make file system).
96-
97-
#### Parameters
98-
* `deviceName` The device to format: DEV_SDCARD or DEV_USB.
99-
* `fileSystem` The file system type to format: FS_FAT or FS_LITTLEFS. FS_FAT is probably the better choice for both SD Cards and USB thumb drives in most cases.
100-
101-
#### Returns
102-
On success: 0. On failure: -1 with an error code in the errno variable.
103-
44+
See [here](./api.md) for a complete description of the API.
10445

10546
## Examples
10647

‎docs/api.md

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Summary
2+
3+
Members | Descriptions
4+
--------------------------------|---------------------------------------------
5+
`enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546) | Enum to select the storage device to use.
6+
`enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35) | Enum to select the file system to use.
7+
`enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85) | Enum to select the mount mode to use. The default mode is Read/Write.
8+
`public int ` [`mount`](#_arduino___p_o_s_i_x_storage_8h_1a22178afb74ae05ab1dcf8c50eb4a9d1f)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem, const enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85)` mountFlags)` | Attach a file system to a device.
9+
`public int ` [`umount`](#_arduino___p_o_s_i_x_storage_8h_1a57b5f0c881dedaf55fe1b9c5fa59e1f8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` | Remove the attached file system from a device.
10+
`public int ` [`register_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1a1a914f0970d317b6a74bef4368cbcae8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, void(*)() callbackFunction)` | Register a hotplug callback function. Currently only supported for DEV_USB on Portenta C33.
11+
`public int ` [`deregister_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1ae80d0ace82aad5ef4a130953290efbd7)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` | Deregister a previously registered hotplug callback function. Not currently supported on any platform.
12+
`public int ` [`mkfs`](#_arduino___p_o_s_i_x_storage_8h_1a834ae6d0e65c5b47f9d8932f7ad0c499)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem)` | Format a device (make file system).
13+
14+
## Members
15+
16+
#### `enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546) <a id="_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546" class="anchor"></a>
17+
18+
Enum to select the storage device to use.
19+
20+
Values | Descriptions
21+
--------------------------------|---------------------------------------------
22+
DEV_SDCARD | SD Card.
23+
DEV_USB | USB Thumb Drive.
24+
25+
<hr />
26+
27+
#### `enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35) <a id="_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35" class="anchor"></a>
28+
29+
Enum to select the file system to use.
30+
31+
Values | Descriptions
32+
--------------------------------|---------------------------------------------
33+
FS_FAT | FAT file system.
34+
FS_LITTLEFS | LittleFS file system.
35+
36+
<hr />
37+
38+
#### `enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85) <a id="_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85" class="anchor"></a>
39+
40+
Enum to select the mount mode to use. The default mode is Read/Write.
41+
42+
Values | Descriptions
43+
--------------------------------|---------------------------------------------
44+
MNT_DEFAULT | Default mount mode (Read/Write)
45+
MNT_RDONLY | Read only mode.
46+
47+
<hr />
48+
49+
#### `public int ` [`mount`](#_arduino___p_o_s_i_x_storage_8h_1a22178afb74ae05ab1dcf8c50eb4a9d1f)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem, const enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85)` mountFlags)` <a id="_arduino___p_o_s_i_x_storage_8h_1a22178afb74ae05ab1dcf8c50eb4a9d1f" class="anchor"></a>
50+
51+
Attach a file system to a device.
52+
53+
#### Parameters
54+
* `deviceName` The device to attach to: DEV_SDCARD or DEV_USB.
55+
56+
* `fileSystem` The file system type to attach: FS_FAT or FS_LITTLEFS.
57+
58+
* `mountFlags` The only valid flag at this time: MNT_DEFAULT.
59+
60+
#### Returns
61+
On success: 0. On failure: -1 with an error code in the errno variable.
62+
<hr />
63+
64+
#### `public int ` [`umount`](#_arduino___p_o_s_i_x_storage_8h_1a57b5f0c881dedaf55fe1b9c5fa59e1f8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` <a id="_arduino___p_o_s_i_x_storage_8h_1a57b5f0c881dedaf55fe1b9c5fa59e1f8" class="anchor"></a>
65+
66+
Remove the attached file system from a device.
67+
68+
#### Parameters
69+
* `deviceName` The device to remove from: DEV_SDCARD or DEV_USB.
70+
71+
#### Returns
72+
On success: 0. On failure: -1 with an error code in the errno variable.
73+
<hr />
74+
75+
#### `public int ` [`register_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1a1a914f0970d317b6a74bef4368cbcae8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, void(*)() callbackFunction)` <a id="_arduino___p_o_s_i_x_storage_8h_1a1a914f0970d317b6a74bef4368cbcae8" class="anchor"></a>
76+
77+
Register a hotplug callback function. Currently only supported for DEV_USB on Portenta C33.
78+
79+
#### Parameters
80+
* `deviceName` The device to register for: DEV_SDCARD or DEV_USB.
81+
82+
* `callbackFunction` A function pointer to the callback.
83+
84+
#### Returns
85+
On success: 0. On failure: -1 with an error code in the errno variable.
86+
<hr />
87+
88+
#### `public int ` [`deregister_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1ae80d0ace82aad5ef4a130953290efbd7)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` <a id="_arduino___p_o_s_i_x_storage_8h_1ae80d0ace82aad5ef4a130953290efbd7" class="anchor"></a>
89+
90+
Deregister a previously registered hotplug callback function. Not currently supported on any platform.
91+
92+
#### Parameters
93+
* `deviceName` The device to deregister for: DEV_SDCARD or DEV_USB.
94+
95+
#### Returns
96+
On success: 0. On failure: -1 with an error code in the errno variable.
97+
<hr />
98+
99+
#### `public int ` [`mkfs`](#_arduino___p_o_s_i_x_storage_8h_1a834ae6d0e65c5b47f9d8932f7ad0c499)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem)` <a id="_arduino___p_o_s_i_x_storage_8h_1a834ae6d0e65c5b47f9d8932f7ad0c499" class="anchor"></a>
100+
101+
Format a device (make file system).
102+
103+
#### Parameters
104+
* `deviceName` The device to format: DEV_SDCARD or DEV_USB.
105+
106+
* `fileSystem` The file system type to format: FS_FAT or FS_LITTLEFS. FS_FAT is probably the better choice for both SD Cards and USB thumb drives in most cases.
107+
108+
#### Returns
109+
On success: 0. On failure: -1 with an error code in the errno variable.
110+
<hr />

‎src/Arduino_POSIXStorage.h

+4-1
Original file line numberDiff line numberDiff line change
@@ -88,21 +88,24 @@
8888
*********************************************************************************************************
8989
*/
9090

91+
/// @brief Enum to select the storage device to use.
9192
enum StorageDevices : uint8_t
9293
{
9394
DEV_SDCARD, ///< SD Card
9495
DEV_USB ///< USB Thumb Drive
9596
};
9697

98+
/// @brief Enum to select the file system to use.
9799
enum FileSystems : uint8_t
98100
{
99101
FS_FAT, ///< FAT file system
100102
FS_LITTLEFS ///< LittleFS file system
101103
};
102104

105+
/// @brief Enum to select the mount mode to use. The default mode is Read/Write.
103106
enum MountFlags : uint8_t
104107
{
105-
MNT_DEFAULT, ///< Default mount mode
108+
MNT_DEFAULT, ///< Default mount mode (Read/Write)
106109
MNT_RDONLY ///< Read only mode
107110
};
108111

0 commit comments

Comments
 (0)