PokittoCookie.h

00001 /**************************************************************************/
00002 /*!
00003     @file     PokittoCookie.h
00004     @author   Jonne Valola
00005 
00006     @section LICENSE
00007 
00008     Software License Agreement (BSD License)
00009 
00010     Copyright (c) 2018, Jonne Valola
00011     All rights reserved.
00012 
00013     Redistribution and use in source and binary forms, with or without
00014     modification, are permitted provided that the following conditions are met:
00015     1. Redistributions of source code must retain the above copyright
00016     notice, this list of conditions and the following disclaimer.
00017     2. Redistributions in binary form must reproduce the above copyright
00018     notice, this list of conditions and the following disclaimer in the
00019     documentation and/or other materials provided with the distribution.
00020     3. Neither the name of the copyright holders nor the
00021     names of its contributors may be used to endorse or promote products
00022     derived from this software without specific prior written permission.
00023 
00024     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
00025     EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00026     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
00028     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00029     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00031     ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00032     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00033     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034 */
00035 /**************************************************************************/
00036 
00037 #ifndef POKITTO_COOKIE_H
00038 #define POKITTO_COOKIE_H
00039 
00040 #include "Pokitto_settings.h "
00041 #include <stdint.h>
00042 
00043 #define SBNOMOREKEYS 1
00044 #define SBNOTENOUGHBLOCKSFREE 2
00045 #define SBMAXKEYS 48 //number of available keys
00046 #define SBMAXBLOCKS 112 //0xF8C (settings reserved area) - 0x180 (start of block table) / 32 bytes (block size)
00047 #define SBBLOCKSIZE 32 //block size in bytes
00048 #define SBKEYSIZE 8
00049 #define SBINVALIDSLOT 255
00050 #define SBINVALIDBLOCK -1
00051 
00052 namespace Pokitto {
00053 
00054 /** Pokitto Cookies are queues of 32 byte blocks that are saved in the EEPROM in a safe way
00055  *
00056  * Example:
00057  * @code
00058  * // Create saveable data and initialize your app to use Cookies
00059  *
00060  *   class gdata : public Cookie {
00061  *   int highscore;
00062  *   }
00063  *
00064  *   gdata gamedata;
00065  *
00066  *   gamedata.begin("ASTEROCK"); // register your Cookie with key "ASTEROCK"
00067  *
00068  *   // you use the data objects inside the Cookie as normal:
00069  *
00070  *   gamedata.highscore = player.currentscore; // It's a new highscore!
00071  *
00072  *   // Finally you call the save method to write your data to EEPROM
00073  *
00074  *   gamedata.save;
00075  * @endcode
00076  */
00077 
00078 class Cookie {
00079 public:
00080     /** Cookie class constructor
00081     */
00082     Cookie();
00083 
00084     /** begin - Register your Cookie with a 8-byte key to begin using it
00085      *
00086      *  @param 8-byte key string
00087      *  @param size of cookie data in bytes
00088      *  @param pointer to beginning of cookie data in memory
00089      *
00090      *  @returns
00091      *       0 on success (free blocks available),
00092      *   non-0 on failure (no more free keys/blocks)
00093      */
00094      int begin(const char*, int, char*);
00095 
00096 
00097     /** begin - Register your Cookie with a 8-byte key to begin using it
00098      *
00099      *  @param 8-byte key string
00100      *  @param reference to cookie data object in memory
00101      *
00102      *  @returns
00103      *       0 on success (free blocks available),
00104      *   non-0 on failure (no more free keys/blocks)
00105      */
00106      template< typename T >
00107      int begin(const char * key, T & object) {
00108        return begin(key, sizeof(T), reinterpret_cast<char *>(&object));
00109      }
00110 
00111     /** initialize - create cookie structure. Can be called many times
00112      *  @returns
00113      *       0 on success (free blocks available),
00114      *   non-0 on failure (no more free keys/blocks)
00115      */
00116      int initialize();
00117 
00118     /** saveCookie - Save your Cookie
00119      *
00120      *  @returns
00121      *      true on success (saved successfully and verified),
00122      *      false on failure (something is wrong)
00123      */
00124      bool saveCookie();
00125 
00126      /** loadCookie - Load your Cookie
00127      *
00128      *  @returns
00129      *      true on success
00130      *      false on failure
00131      */
00132      bool loadCookie();
00133 
00134      /** deleteCookie -  your Cookie
00135      */
00136      void deleteCookie();
00137 
00138     /** isOK - Get status of Cookie
00139      *
00140      *  @returns
00141      *       true on success (Cookie is initialized and ready to use),
00142      *      false on failure (Cookie did not initialize and can't be used)
00143      */
00144      bool isOK();
00145 
00146     /** readKeytableEntry - return the key at slot n
00147      *
00148      *  @param slot number to check
00149      *  @param pointer to a 9 char buffer for return answer
00150      *
00151      */
00152      void readKeytableEntry(int, char*);
00153 
00154 
00155     /** formatKeyTable(int) - erase all keys
00156      *
00157      *  @param slot number to erase
00158      *
00159      */
00160      void formatKeytable();
00161 
00162 
00163     /** eraseKeyAt(int) - erase key at slot n
00164      *
00165      *  @param slot number to erase
00166      *
00167      */
00168      void eraseKeytableEntry(int);
00169 
00170      /** cleanKeytable() - erase keys that have no blocks reserved from the keyTable
00171      *
00172      */
00173      void cleanKeytable();
00174 
00175 //private:
00176 public:
00177 
00178     /** exists - find out if the key exists
00179      *
00180      *  @param 8-byte key string
00181      *
00182      *  @returns
00183      *       slotnumber on key exists ,
00184      *       SBINVALIDSLOT on does not exist
00185      */
00186      int exists(const char*);
00187 
00188     /** getFreeKeytableSlot - Are there any keys left to use
00189      *
00190      *  @returns
00191      *      slot number 0...47 on success
00192      *      -1 on failure
00193      */
00194      int getFreeKeytableSlot();
00195 
00196     /** getFreeBlocks - Are there any storage blocks left to use
00197      *
00198      *  @returns
00199      *      number of blocks available
00200      */
00201      int getFreeBlocks();
00202 
00203     /** getAssignedBlocks - return number of blocks already reserved for cookie
00204      *
00205      *  @returns
00206      *      number of blocks assigned to cookie
00207      */
00208      int getAssignedBlocks();
00209 
00210 
00211     /** isFreeBlock - check if block n is free to use
00212      *
00213      *  @param block number
00214      *  @returns
00215      *      true when free
00216      *      false when reserved
00217      */
00218      bool isFreeBlock(int);
00219 
00220     /** isMyBlock - check if block n is already reserved for this cookie
00221      *
00222      *  @param block number
00223      *  @returns
00224      *      true when is already reserved
00225      *      false when is not
00226      */
00227      bool isMyBlock(int);
00228 
00229     /** blockIsOwnedBy - check if block n is owned by Keytable entry k
00230      *
00231      *  @param block number
00232      *  @param keytable entry number
00233      *  @returns
00234      *      true when keytable entry k is owner of block n
00235      *      false when is not
00236      */
00237      bool blockIsOwnedBy(int,int);
00238 
00239     /** writeKeyToKeyTable - write the key into the key table
00240      *
00241      *  @param 8-byte key string
00242      *  @param slot number into which the key is written 0...47
00243      *
00244      */
00245      void writeKeyToKeytable(const char*, int);
00246 
00247 
00248     /** getBlockTableEntry - read an entry from the blocktable
00249      *
00250      *  @param block table index number
00251      *
00252      *  @returns
00253      *         block table entry (1 byte)
00254      */
00255      char getBlockTableEntry(int);
00256 
00257      /** readBlock - read the data of a block
00258      *
00259      *  @param block index number
00260      *  @param pointer to a buffer of SBBLOCKSIZE size to hold the return data
00261      *
00262      */
00263      void readBlock(int, char*);
00264 
00265      /** freeBlock - free block from blocktable and delete data of block in EEPROM
00266      *
00267      *  @param block index number
00268      *
00269      */
00270      void freeBlock(int);
00271 
00272      /** reserveBlock - search and reserve a block from blocktable for use by this cookie
00273      *
00274      *  @returns
00275      *      true when it was possible to reserve a block
00276      *      false when it was not
00277      *
00278      */
00279      bool reserveBlock();
00280 
00281     /** writeQueue - write the cookie data as a stream of bytes into the EEPROM blocks
00282      *
00283      *  @param byte to be written
00284      */
00285      void writeQueue(char);
00286 
00287     /** readQueue - write the cookie data as a stream of bytes into the EEPROM blocks
00288      *
00289      *  @returns
00290      *      byte value from EEPROM memory
00291      */
00292      char readQueue();
00293 
00294 
00295     /** findMyNextBlock - find the next block assigned to this cookie
00296      *
00297      *  @returns
00298      *      number of next block
00299      */
00300      int findMyNextBlock();
00301 
00302     /** keystring
00303     * identification string for the Cookie
00304     */
00305      char _key[SBKEYSIZE];
00306 
00307     /** Keyorder
00308     * order number of key in key table
00309     */
00310      unsigned char _keyorder;
00311 
00312     /** Status
00313     * false = uninitialized
00314     * true = ready
00315     */
00316      bool _status;
00317 
00318     /** Datasize
00319     * size (in bytes) of cookie data to be saved and reloaded
00320     */
00321     int _datasize;
00322 
00323     /** Pointer
00324     * pointer to cookie data
00325     */
00326     char* _pointer;
00327 
00328     /** Head
00329     * data "head" for byte write/read operations
00330     */
00331     int _head;
00332 
00333     /** Current block
00334     * block number that we are reading/writing
00335     */
00336     char _block;
00337 };
00338 
00339 
00340 } // namespace
00341 
00342 
00343 #endif // POKITTO_Cookie_H
00344