FileInterface.h

00001 /**
00002  * ACKme WiConnect Host Library is licensed under the BSD licence: 
00003  * 
00004  * Copyright (c)2014 ACKme Networks.
00005  * All rights reserved. 
00006  * 
00007  * Redistribution and use in source and binary forms, with or without modification, 
00008  * are permitted provided that the following conditions are met: 
00009  * 
00010  * 1. Redistributions of source code must retain the above copyright notice, 
00011  * this list of conditions and the following disclaimer. 
00012  * 2. Redistributions in binary form must reproduce the above copyright notice, 
00013  * this list of conditions and the following disclaimer in the documentation 
00014  * and/or other materials provided with the distribution. 
00015  * 3. The name of the author may not be used to endorse or promote products 
00016  * derived from this software without specific prior written permission. 
00017  * 
00018  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS AND ANY EXPRESS OR IMPLIED 
00019  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
00020  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
00021  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00022  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
00023  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
00024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
00025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
00026  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
00027  * OF SUCH DAMAGE.
00028  */
00029 #pragma once
00030 
00031 
00032 #include "WiconnectTypes.h"
00033 #include "types/FileList.h"
00034 
00035 
00036 /**
00037  * @ingroup api_file_macro
00038  * @brief The maximum filename size of a file on the WiConnect WiFi module filesystem
00039  */
00040 #define FILE_NAME_MAX_SIZE 96
00041 
00042 /**
00043  * @ingroup api_file_macro
00044  * @def FILE_MAKE_VERSION(major, minor, patch, rc)
00045  * @brief Combine <\a major>.<\a minor>.<\a patch>.<\a rc> and create version as a uint32_t
00046  */
00047 #define FILE_MAKE_VERSION(major, minor, patch, rc) ((unsigned int)((major) << 27)|(unsigned int)((minor) << 21)|(unsigned int)((patch) << 8)|(unsigned int)((rc) << 0))
00048 /**
00049  * @ingroup api_file_macro
00050  * @def FILE_VERSION_ARGS(version)
00051  * @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
00052  */
00053 #define FILE_VERSION_ARGS(version) (unsigned int)((version >> 27) & 0x1F),(unsigned int)((version >> 21) & 0x3F),(unsigned int)((version >> 8) & 0x1FFF),(unsigned int)(version & 0xFF)
00054 
00055 
00056 namespace wiconnect {
00057 
00058 
00059 /**
00060  * @ingroup api_file_types
00061  *
00062  * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets.
00063  * A client socket connects to a remote server.
00064  *
00065  * @note This class is an interface to the Wiconnect class. It should never be
00066  *       independently instantiated or the parent of another class.
00067  */
00068 class FileInterface
00069 {
00070 public:
00071     /**
00072      * @ingroup api_file_methods
00073      *
00074      * @brief Create a file on the Wiconnect WiFi module filesystem.
00075      *
00076      * This creates a file on the module's filesystem. The file's name and size are required.
00077      * Optionally specify the version, type and if it's essential (i.e. if it should never be automatically deleted, careful with
00078      * this optional as it could cause the the module to not be able to update its firmware).
00079      *
00080      * When this method is executed, the file is created on the module then the 'reader' parameter callback is
00081      * called until all the file data is read from the HOST and written to the module file.
00082      *
00083      * @param[in] reader Callback to be executed until all file data has been read from the HOST and written to the module
00084      * @param[in] user This is supplied to the @ref ReaderFunc callback. It is not used by the library. Leave NULL if not needed.
00085      * @param[in] name The name of the file to create
00086      * @param[in] size The size in bytes of the file
00087      * @param[in] version Optional, the version of the file, defaults to 1.0.0.0
00088      * @param[in] type Optional, the file type, defaults to FILE_TYPE_MISC_FIX_LEN
00089      * @param[in] isEssential Optional, specify if the file should never be automatically deleted during a firmware upgrade
00090      * @param[in] checksum The CRC16 checksum of the file data. The module verifies the written data against this checksum
00091      * @return Result of method. See @ref WiconnectResult
00092      */
00093     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);
00094 
00095     /**
00096      * @ingroup api_file_methods
00097      *
00098      * @brief Open a file on the Wiconnect WiFi module filesystem for reading.
00099      *
00100      * Once opened, the returned @ref WiconnectFile object may only be read.
00101      *
00102      * @param[out] file The @ref WiconnectFile object to read data from
00103      * @param[in] name The name of the file to open
00104      * @return Result of method. See @ref WiconnectResult
00105      */
00106     WiconnectResult openFile(WiconnectFile &file, const char *name);
00107 
00108     /**
00109      * @ingroup api_file_methods
00110      *
00111      * @brief Delete a file for the Wiconnect WiFi module filesystem.
00112      *
00113      * @param[in] name The name of the file to delete
00114      * @return Result of method. See @ref WiconnectResult
00115      */
00116     WiconnectResult deleteFile(const char *name);
00117 
00118     /**
00119      * @ingroup api_file_methods
00120      *
00121      * @brief Delete a file for the Wiconnect WiFi module filesystem.
00122      *
00123      * @param[in] file The @ref WiconnectFile object of the file to delete
00124      * @return Result of method. See @ref WiconnectResult
00125      */
00126     WiconnectResult deleteFile(const WiconnectFile &file);
00127 
00128     /**
00129      * @ingroup api_file_methods
00130      *
00131      * @brief List the files on the Wiconnect WiFi module filesystem.
00132      *
00133      * This lists all the files on the filesystem.
00134      * Optionally filter by one or more parameters:
00135      * * name - list files only with given name. If the name started with the wildcard character '*', then
00136      *          only the characters after it are used for filter.
00137      *          Example:
00138      *          @code
00139      *          wiconnect.listFiles(fileList, "*.txt"); // only list files with '.txt' extension
00140      *          @endcode
00141      * * type - only list files with given type
00142      * * version - only list file with given version
00143      * @return Result of method. See @ref WiconnectResult
00144      */
00145     WiconnectResult listFiles(FileList &list, const char *name = NULL, FileType type = FILE_TYPE_ANY, uint32_t version = 0);
00146 
00147 
00148     // ------------------------------------------------------------------------
00149 
00150 
00151     /**
00152      * @ingroup conversion_util
00153      *
00154      * @brief Convert file version uint32 to string.
00155      */
00156     static const char* fileVersionIntToStr(uint32_t version, bool verbose = true, char *buffer = NULL);
00157 
00158     /**
00159      * @ingroup conversion_util
00160      *
00161      * @brief Convert string to file version uint32.
00162      */
00163     static bool fileVersionStrToInt(const char *versionStr, uint32_t *versionIntPtr);
00164 
00165     /**
00166      * @ingroup conversion_util
00167      *
00168      * Convert @ref FileType to string.
00169      */
00170     static const char* fileTypeToStr(FileType type);
00171 
00172     /**
00173      * @ingroup conversion_util
00174      *
00175      * @brief Convert @ref FileFlags to string.
00176      */
00177     static const char* fileFlagsToStr(FileFlags flags, char *buffer = NULL);
00178 
00179 protected:
00180     FileInterface(Wiconnect *wiconnect);
00181 
00182     WiconnectResult processFileList(char *responseStr, FileList &list, const char *name, FileType type, uint32_t version);
00183 private:
00184     Wiconnect *wiconnect;
00185 };
00186 
00187 }