ACKme / WiConnect

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

FileInterface.h@17:7268f365676b, 2014-08-23 (annotated)

Committer:
dan_ackme
Date:
Sat Aug 23 05:39:17 2014 -0700
Revision:
17:7268f365676b
Parent:
16:7f1d6d359787
Child:
21:17bb3eddcbae
Fixes and documentation updates

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dan_ackme 16:7f1d6d359787 1 /**
dan_ackme 16:7f1d6d359787 2 * ACKme WiConnect Host Library is licensed under the BSD licence:
dan_ackme 16:7f1d6d359787 3 *
dan_ackme 16:7f1d6d359787 4 * Copyright (c)2014 ACKme Networks.
dan_ackme 16:7f1d6d359787 5 * All rights reserved.
dan_ackme 16:7f1d6d359787 6 *
dan_ackme 16:7f1d6d359787 7 * Redistribution and use in source and binary forms, with or without modification,
dan_ackme 16:7f1d6d359787 8 * are permitted provided that the following conditions are met:
dan_ackme 16:7f1d6d359787 9 *
dan_ackme 16:7f1d6d359787 10 * 1. Redistributions of source code must retain the above copyright notice,
dan_ackme 16:7f1d6d359787 11 * this list of conditions and the following disclaimer.
dan_ackme 16:7f1d6d359787 12 * 2. Redistributions in binary form must reproduce the above copyright notice,
dan_ackme 16:7f1d6d359787 13 * this list of conditions and the following disclaimer in the documentation
dan_ackme 16:7f1d6d359787 14 * and/or other materials provided with the distribution.
dan_ackme 16:7f1d6d359787 15 * 3. The name of the author may not be used to endorse or promote products
dan_ackme 16:7f1d6d359787 16 * derived from this software without specific prior written permission.
dan_ackme 16:7f1d6d359787 17 *
dan_ackme 16:7f1d6d359787 18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS AND ANY EXPRESS OR IMPLIED
dan_ackme 16:7f1d6d359787 19 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
dan_ackme 16:7f1d6d359787 20 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
dan_ackme 16:7f1d6d359787 21 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
dan_ackme 16:7f1d6d359787 22 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
dan_ackme 16:7f1d6d359787 23 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
dan_ackme 16:7f1d6d359787 24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
dan_ackme 16:7f1d6d359787 25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
dan_ackme 16:7f1d6d359787 26 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
dan_ackme 16:7f1d6d359787 27 * OF SUCH DAMAGE.
dan_ackme 0:ea85c4bb5e1f 28 */
dan_ackme 0:ea85c4bb5e1f 29 #pragma once
dan_ackme 0:ea85c4bb5e1f 30
dan_ackme 0:ea85c4bb5e1f 31
dan_ackme 0:ea85c4bb5e1f 32 #include "WiconnectTypes.h"
dan_ackme 0:ea85c4bb5e1f 33 #include "types/FileList.h"
dan_ackme 0:ea85c4bb5e1f 34
dan_ackme 0:ea85c4bb5e1f 35
dan_ackme 11:ea484e1b7fc4 36 /**
dan_ackme 11:ea484e1b7fc4 37 * @ingroup api_file_macro
dan_ackme 11:ea484e1b7fc4 38 * @brief The maximum filename size of a file on the WiConnect WiFi module filesystem
dan_ackme 11:ea484e1b7fc4 39 */
dan_ackme 0:ea85c4bb5e1f 40 #define FILE_NAME_MAX_SIZE 96
dan_ackme 11:ea484e1b7fc4 41
dan_ackme 11:ea484e1b7fc4 42 /**
dan_ackme 11:ea484e1b7fc4 43 * @ingroup api_file_macro
dan_ackme 11:ea484e1b7fc4 44 * @def FILE_MAKE_VERSION(major, minor, patch, rc)
dan_ackme 11:ea484e1b7fc4 45 * @brief Combine <\a major>.<\a minor>.<\a patch>.<\a rc> and create version as a uint32_t
dan_ackme 11:ea484e1b7fc4 46 */
dan_ackme 0:ea85c4bb5e1f 47 #define FILE_MAKE_VERSION(major, minor, patch, rc) ((unsigned int)((major) << 27)|(unsigned int)((minor) << 21)|(unsigned int)((patch) << 8)|(unsigned int)((rc) << 0))
dan_ackme 11:ea484e1b7fc4 48 /**
dan_ackme 11:ea484e1b7fc4 49 * @ingroup api_file_macro
dan_ackme 11:ea484e1b7fc4 50 * @def FILE_VERSION_ARGS(version)
dan_ackme 11:ea484e1b7fc4 51 * @brief Given a uint32_t \a version, return arguments for a variable argument function such as printf(). The format string is: %d.%d.%d.%d
dan_ackme 11:ea484e1b7fc4 52 */
dan_ackme 0:ea85c4bb5e1f 53 #define FILE_VERSION_ARGS(version) (unsigned int)((version >> 27) & 0x1F),(unsigned int)((version >> 21) & 0x3F),(unsigned int)((version >> 8) & 0x1FFF),(unsigned int)(version & 0xFF)
dan_ackme 0:ea85c4bb5e1f 54
dan_ackme 0:ea85c4bb5e1f 55
dan_ackme 0:ea85c4bb5e1f 56 namespace wiconnect {
dan_ackme 0:ea85c4bb5e1f 57
dan_ackme 0:ea85c4bb5e1f 58
dan_ackme 11:ea484e1b7fc4 59 /**
dan_ackme 13:2b51f5267c92 60 * @ingroup api_file_types
dan_ackme 11:ea484e1b7fc4 61 *
dan_ackme 11:ea484e1b7fc4 62 * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets.
dan_ackme 11:ea484e1b7fc4 63 * A client socket connects to a remote server.
dan_ackme 11:ea484e1b7fc4 64 *
dan_ackme 13:2b51f5267c92 65 * @note This class is an interface to the Wiconnect class. It should never be
dan_ackme 13:2b51f5267c92 66 * independently instantiated or the parent of another class.
dan_ackme 11:ea484e1b7fc4 67 */
dan_ackme 0:ea85c4bb5e1f 68 class FileInterface
dan_ackme 0:ea85c4bb5e1f 69 {
dan_ackme 0:ea85c4bb5e1f 70 public:
dan_ackme 11:ea484e1b7fc4 71 /**
dan_ackme 13:2b51f5267c92 72 * @ingroup api_file_methods
dan_ackme 13:2b51f5267c92 73 *
dan_ackme 13:2b51f5267c92 74 * @brief Create a file on the Wiconnect WiFi module filesystem.
dan_ackme 13:2b51f5267c92 75 *
dan_ackme 13:2b51f5267c92 76 * This creates a file on the module's filesystem. The file's name and size are required.
dan_ackme 13:2b51f5267c92 77 * Optionally specify the version, type and if it's essential (i.e. if it should never be automatically deleted, careful with
dan_ackme 13:2b51f5267c92 78 * this optional as it could cause the the module to not be able to update its firmware).
dan_ackme 11:ea484e1b7fc4 79 *
dan_ackme 13:2b51f5267c92 80 * When this method is executed, the file is created on the module then the 'reader' parameter callback is
dan_ackme 13:2b51f5267c92 81 * called until all the file data is read from the HOST and written to the module file.
dan_ackme 13:2b51f5267c92 82 *
dan_ackme 13:2b51f5267c92 83 * @param[in] reader Callback to be executed until all file data has been read from the HOST and written to the module
dan_ackme 13:2b51f5267c92 84 * @param[in] user This is supplied to the @ref ReaderFunc callback. It is not used by the library. Leave NULL if not needed.
dan_ackme 13:2b51f5267c92 85 * @param[in] name The name of the file to create
dan_ackme 13:2b51f5267c92 86 * @param[in] size The size in bytes of the file
dan_ackme 13:2b51f5267c92 87 * @param[in] version Optional, the version of the file, defaults to 1.0.0.0
dan_ackme 13:2b51f5267c92 88 * @param[in] type Optional, the file type, defaults to FILE_TYPE_MISC_FIX_LEN
dan_ackme 13:2b51f5267c92 89 * @param[in] isEssential Optional, specify if the file should never be automatically deleted during a firmware upgrade
dan_ackme 13:2b51f5267c92 90 * @param[in] checksum The CRC16 checksum of the file data. The module verifies the written data against this checksum
dan_ackme 13:2b51f5267c92 91 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 92 */
dan_ackme 0:ea85c4bb5e1f 93 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);
dan_ackme 11:ea484e1b7fc4 94
dan_ackme 11:ea484e1b7fc4 95 /**
dan_ackme 13:2b51f5267c92 96 * @ingroup api_file_methods
dan_ackme 13:2b51f5267c92 97 *
dan_ackme 13:2b51f5267c92 98 * @brief Open a file on the Wiconnect WiFi module filesystem for reading.
dan_ackme 11:ea484e1b7fc4 99 *
dan_ackme 17:7268f365676b 100 * Once opened, the returned @ref WiconnectFile object may only be read.
dan_ackme 13:2b51f5267c92 101 *
dan_ackme 17:7268f365676b 102 * @param[out] file The @ref WiconnectFile object to read data from
dan_ackme 13:2b51f5267c92 103 * @param[in] name The name of the file to open
dan_ackme 13:2b51f5267c92 104 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 105 */
dan_ackme 17:7268f365676b 106 WiconnectResult openFile(WiconnectFile &file, const char *name);
dan_ackme 11:ea484e1b7fc4 107
dan_ackme 11:ea484e1b7fc4 108 /**
dan_ackme 13:2b51f5267c92 109 * @ingroup api_file_methods
dan_ackme 11:ea484e1b7fc4 110 *
dan_ackme 13:2b51f5267c92 111 * @brief Delete a file for the Wiconnect WiFi module filesystem.
dan_ackme 13:2b51f5267c92 112 *
dan_ackme 13:2b51f5267c92 113 * @param[in] name The name of the file to delete
dan_ackme 13:2b51f5267c92 114 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 115 */
dan_ackme 0:ea85c4bb5e1f 116 WiconnectResult deleteFile(const char *name);
dan_ackme 11:ea484e1b7fc4 117
dan_ackme 11:ea484e1b7fc4 118 /**
dan_ackme 13:2b51f5267c92 119 * @ingroup api_file_methods
dan_ackme 11:ea484e1b7fc4 120 *
dan_ackme 13:2b51f5267c92 121 * @brief Delete a file for the Wiconnect WiFi module filesystem.
dan_ackme 13:2b51f5267c92 122 *
dan_ackme 17:7268f365676b 123 * @param[in] file The @ref WiconnectFile object of the file to delete
dan_ackme 13:2b51f5267c92 124 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 125 */
dan_ackme 17:7268f365676b 126 WiconnectResult deleteFile(const WiconnectFile &file);
dan_ackme 11:ea484e1b7fc4 127
dan_ackme 11:ea484e1b7fc4 128 /**
dan_ackme 13:2b51f5267c92 129 * @ingroup api_file_methods
dan_ackme 13:2b51f5267c92 130 *
dan_ackme 13:2b51f5267c92 131 * @brief List the files on the Wiconnect WiFi module filesystem.
dan_ackme 11:ea484e1b7fc4 132 *
dan_ackme 13:2b51f5267c92 133 * This lists all the files on the filesystem.
dan_ackme 13:2b51f5267c92 134 * Optionally filter by one or more parameters:
dan_ackme 13:2b51f5267c92 135 * * name - list files only with given name. If the name started with the wildcard character '*', then
dan_ackme 13:2b51f5267c92 136 * only the characters after it are used for filter.
dan_ackme 13:2b51f5267c92 137 * Example:
dan_ackme 13:2b51f5267c92 138 * @code
dan_ackme 13:2b51f5267c92 139 * wiconnect.listFiles(fileList, "*.txt"); // only list files with '.txt' extension
dan_ackme 13:2b51f5267c92 140 * @endcode
dan_ackme 13:2b51f5267c92 141 * * type - only list files with given type
dan_ackme 13:2b51f5267c92 142 * * version - only list file with given version
dan_ackme 13:2b51f5267c92 143 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 144 */
dan_ackme 0:ea85c4bb5e1f 145 WiconnectResult listFiles(FileList &list, const char *name = NULL, FileType type = FILE_TYPE_ANY, uint32_t version = 0);
dan_ackme 0:ea85c4bb5e1f 146
dan_ackme 11:ea484e1b7fc4 147
dan_ackme 11:ea484e1b7fc4 148 // ------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 149
dan_ackme 11:ea484e1b7fc4 150
dan_ackme 11:ea484e1b7fc4 151 /**
dan_ackme 11:ea484e1b7fc4 152 * @ingroup conversion_util
dan_ackme 11:ea484e1b7fc4 153 *
dan_ackme 11:ea484e1b7fc4 154 * @brief Convert file version uint32 to string.
dan_ackme 11:ea484e1b7fc4 155 */
dan_ackme 0:ea85c4bb5e1f 156 static const char* fileVersionIntToStr(uint32_t version, bool verbose = true, char *buffer = NULL);
dan_ackme 11:ea484e1b7fc4 157
dan_ackme 11:ea484e1b7fc4 158 /**
dan_ackme 11:ea484e1b7fc4 159 * @ingroup conversion_util
dan_ackme 11:ea484e1b7fc4 160 *
dan_ackme 11:ea484e1b7fc4 161 * @brief Convert string to file version uint32.
dan_ackme 11:ea484e1b7fc4 162 */
dan_ackme 0:ea85c4bb5e1f 163 static bool fileVersionStrToInt(const char *versionStr, uint32_t *versionIntPtr);
dan_ackme 11:ea484e1b7fc4 164
dan_ackme 11:ea484e1b7fc4 165 /**
dan_ackme 11:ea484e1b7fc4 166 * @ingroup conversion_util
dan_ackme 11:ea484e1b7fc4 167 *
dan_ackme 11:ea484e1b7fc4 168 * Convert @ref FileType to string.
dan_ackme 11:ea484e1b7fc4 169 */
dan_ackme 0:ea85c4bb5e1f 170 static const char* fileTypeToStr(FileType type);
dan_ackme 11:ea484e1b7fc4 171
dan_ackme 11:ea484e1b7fc4 172 /**
dan_ackme 11:ea484e1b7fc4 173 * @ingroup conversion_util
dan_ackme 11:ea484e1b7fc4 174 *
dan_ackme 11:ea484e1b7fc4 175 * @brief Convert @ref FileFlags to string.
dan_ackme 11:ea484e1b7fc4 176 */
dan_ackme 0:ea85c4bb5e1f 177 static const char* fileFlagsToStr(FileFlags flags, char *buffer = NULL);
dan_ackme 0:ea85c4bb5e1f 178
dan_ackme 0:ea85c4bb5e1f 179 protected:
dan_ackme 1:6ec9998427ad 180 FileInterface(Wiconnect *wiconnect);
dan_ackme 1:6ec9998427ad 181
dan_ackme 0:ea85c4bb5e1f 182 WiconnectResult processFileList(char *responseStr, FileList &list, const char *name, FileType type, uint32_t version);
dan_ackme 0:ea85c4bb5e1f 183 private:
dan_ackme 0:ea85c4bb5e1f 184 Wiconnect *wiconnect;
dan_ackme 0:ea85c4bb5e1f 185 };
dan_ackme 0:ea85c4bb5e1f 186
dan_ackme 0:ea85c4bb5e1f 187 }