Host library for controlling a WiConnect enabled Wi-Fi module.
Dependents: wiconnect-ota_example wiconnect-web_setup_example wiconnect-test-console wiconnect-tcp_server_example ... more
Diff: FileInterface.h
- Revision:
- 13:2b51f5267c92
- Parent:
- 11:ea484e1b7fc4
- Child:
- 16:7f1d6d359787
--- a/FileInterface.h Tue Aug 12 02:44:34 2014 -0700 +++ b/FileInterface.h Wed Aug 13 03:14:30 2014 -0700 @@ -40,47 +40,90 @@ /** - * @ingroup types_file + * @ingroup api_file_types * * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets. * A client socket connects to a remote server. * + * @note This class is an interface to the Wiconnect class. It should never be + * independently instantiated or the parent of another class. */ class FileInterface { public: /** - * @ingroup api_file + * @ingroup api_file_methods + * + * @brief Create a file on the Wiconnect WiFi module filesystem. + * + * This creates a file on the module's filesystem. The file's name and size are required. + * Optionally specify the version, type and if it's essential (i.e. if it should never be automatically deleted, careful with + * this optional as it could cause the the module to not be able to update its firmware). * - * @brief Create a file on the Wiconnect WiFi module flash filesystem. + * When this method is executed, the file is created on the module then the 'reader' parameter callback is + * called until all the file data is read from the HOST and written to the module file. + * + * @param[in] reader Callback to be executed until all file data has been read from the HOST and written to the module + * @param[in] user This is supplied to the @ref ReaderFunc callback. It is not used by the library. Leave NULL if not needed. + * @param[in] name The name of the file to create + * @param[in] size The size in bytes of the file + * @param[in] version Optional, the version of the file, defaults to 1.0.0.0 + * @param[in] type Optional, the file type, defaults to FILE_TYPE_MISC_FIX_LEN + * @param[in] isEssential Optional, specify if the file should never be automatically deleted during a firmware upgrade + * @param[in] checksum The CRC16 checksum of the file data. The module verifies the written data against this checksum + * @return Result of method. See @ref WiconnectResult */ WiconnectResult createFile(const ReaderFunc &reader, void *user, const char *name, uint32_t size, uint32_t version = 0, FileType type = FILE_TYPE_ANY, bool isEssential = false, int32_t checksum = -1); /** - * @ingroup api_file + * @ingroup api_file_methods + * + * @brief Open a file on the Wiconnect WiFi module filesystem for reading. * - * @brief Open a file on the Wiconnect WiFi module flash filesystem for reading. + * Once opened, the returned @ref File object may only be read. + * + * @param[out] file The @ref File object to read data from + * @param[in] name The name of the file to open + * @return Result of method. See @ref WiconnectResult */ WiconnectResult openFile(File &file, const char *name); /** - * @ingroup api_file + * @ingroup api_file_methods * - * @brief Delete a file for the Wiconnect WiFi module flash filesystem. + * @brief Delete a file for the Wiconnect WiFi module filesystem. + * + * @param[in] name The name of the file to delete + * @return Result of method. See @ref WiconnectResult */ WiconnectResult deleteFile(const char *name); /** - * @ingroup api_file + * @ingroup api_file_methods * - * @brief Delete a file for the Wiconnect WiFi module flash filesystem. + * @brief Delete a file for the Wiconnect WiFi module filesystem. + * + * @param[in] file The @ref File object of the file to delete + * @return Result of method. See @ref WiconnectResult */ WiconnectResult deleteFile(const File &file); /** - * @ingroup api_file + * @ingroup api_file_methods + * + * @brief List the files on the Wiconnect WiFi module filesystem. * - * @brief List the files on the Wiconnect WiFi module flash filesystem. + * This lists all the files on the filesystem. + * Optionally filter by one or more parameters: + * * name - list files only with given name. If the name started with the wildcard character '*', then + * only the characters after it are used for filter. + * Example: + * @code + * wiconnect.listFiles(fileList, "*.txt"); // only list files with '.txt' extension + * @endcode + * * type - only list files with given type + * * version - only list file with given version + * @return Result of method. See @ref WiconnectResult */ WiconnectResult listFiles(FileList &list, const char *name = NULL, FileType type = FILE_TYPE_ANY, uint32_t version = 0);