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);