spinal cord / PokittoLib_

PokittoLib is the library needed for programming the Pokitto DIY game console (www.pokitto.com)

POKITTO_CORE/PokittoCookie.h@64:6e6c6c2b664e, 2018-11-18 (annotated)

Committer:
spinal
Date:
Sun Nov 18 15:47:54 2018 +0000
Revision:
64:6e6c6c2b664e
Parent:
51:113b1d84c34f 
added fix for directrectangle()

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Pokitto 51:113b1d84c34f 1 /**************************************************************************/
Pokitto 51:113b1d84c34f 2 /*!
Pokitto 51:113b1d84c34f 3 @file PokittoCookie.h
Pokitto 51:113b1d84c34f 4 @author Jonne Valola
Pokitto 51:113b1d84c34f 5
Pokitto 51:113b1d84c34f 6 @section LICENSE
Pokitto 51:113b1d84c34f 7
Pokitto 51:113b1d84c34f 8 Software License Agreement (BSD License)
Pokitto 51:113b1d84c34f 9
Pokitto 51:113b1d84c34f 10 Copyright (c) 2018, Jonne Valola
Pokitto 51:113b1d84c34f 11 All rights reserved.
Pokitto 51:113b1d84c34f 12
Pokitto 51:113b1d84c34f 13 Redistribution and use in source and binary forms, with or without
Pokitto 51:113b1d84c34f 14 modification, are permitted provided that the following conditions are met:
Pokitto 51:113b1d84c34f 15 1. Redistributions of source code must retain the above copyright
Pokitto 51:113b1d84c34f 16 notice, this list of conditions and the following disclaimer.
Pokitto 51:113b1d84c34f 17 2. Redistributions in binary form must reproduce the above copyright
Pokitto 51:113b1d84c34f 18 notice, this list of conditions and the following disclaimer in the
Pokitto 51:113b1d84c34f 19 documentation and/or other materials provided with the distribution.
Pokitto 51:113b1d84c34f 20 3. Neither the name of the copyright holders nor the
Pokitto 51:113b1d84c34f 21 names of its contributors may be used to endorse or promote products
Pokitto 51:113b1d84c34f 22 derived from this software without specific prior written permission.
Pokitto 51:113b1d84c34f 23
Pokitto 51:113b1d84c34f 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
Pokitto 51:113b1d84c34f 25 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
Pokitto 51:113b1d84c34f 26 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
Pokitto 51:113b1d84c34f 27 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
Pokitto 51:113b1d84c34f 28 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
Pokitto 51:113b1d84c34f 29 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Pokitto 51:113b1d84c34f 30 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
Pokitto 51:113b1d84c34f 31 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Pokitto 51:113b1d84c34f 32 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
Pokitto 51:113b1d84c34f 33 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Pokitto 51:113b1d84c34f 34 */
Pokitto 51:113b1d84c34f 35 /**************************************************************************/
Pokitto 51:113b1d84c34f 36
Pokitto 51:113b1d84c34f 37 #ifndef POKITTO_COOKIE_H
Pokitto 51:113b1d84c34f 38 #define POKITTO_COOKIE_H
Pokitto 51:113b1d84c34f 39
Pokitto 51:113b1d84c34f 40 #include "Pokitto_settings.h"
Pokitto 51:113b1d84c34f 41 #include <stdint.h>
Pokitto 51:113b1d84c34f 42
Pokitto 51:113b1d84c34f 43 #define SBNOMOREKEYS 1
Pokitto 51:113b1d84c34f 44 #define SBNOTENOUGHBLOCKSFREE 2
Pokitto 51:113b1d84c34f 45 #define SBMAXKEYS 48 //number of available keys
Pokitto 51:113b1d84c34f 46 #define SBMAXBLOCKS 112 //0xF8C (settings reserved area) - 0x180 (start of block table) / 32 bytes (block size)
Pokitto 51:113b1d84c34f 47 #define SBBLOCKSIZE 32 //block size in bytes
Pokitto 51:113b1d84c34f 48 #define SBKEYSIZE 8
Pokitto 51:113b1d84c34f 49 #define SBINVALIDSLOT 255
Pokitto 51:113b1d84c34f 50 #define SBINVALIDBLOCK -1
Pokitto 51:113b1d84c34f 51
Pokitto 51:113b1d84c34f 52 namespace Pokitto {
Pokitto 51:113b1d84c34f 53
Pokitto 51:113b1d84c34f 54 /** Pokitto Cookies are queues of 32 byte blocks that are saved in the EEPROM in a safe way
Pokitto 51:113b1d84c34f 55 *
Pokitto 51:113b1d84c34f 56 * Example:
Pokitto 51:113b1d84c34f 57 * @code
Pokitto 51:113b1d84c34f 58 * // Create saveable data and initialize your app to use Cookies
Pokitto 51:113b1d84c34f 59 *
Pokitto 51:113b1d84c34f 60 * class gdata : public Cookie {
Pokitto 51:113b1d84c34f 61 * int highscore;
Pokitto 51:113b1d84c34f 62 * }
Pokitto 51:113b1d84c34f 63 *
Pokitto 51:113b1d84c34f 64 * gdata gamedata;
Pokitto 51:113b1d84c34f 65 *
Pokitto 51:113b1d84c34f 66 * gamedata.begin("ASTEROCK"); // register your Cookie with key "ASTEROCK"
Pokitto 51:113b1d84c34f 67 *
Pokitto 51:113b1d84c34f 68 * // you use the data objects inside the Cookie as normal:
Pokitto 51:113b1d84c34f 69 *
Pokitto 51:113b1d84c34f 70 * gamedata.highscore = player.currentscore; // It's a new highscore!
Pokitto 51:113b1d84c34f 71 *
Pokitto 51:113b1d84c34f 72 * // Finally you call the save method to write your data to EEPROM
Pokitto 51:113b1d84c34f 73 *
Pokitto 51:113b1d84c34f 74 * gamedata.save;
Pokitto 51:113b1d84c34f 75 * @endcode
Pokitto 51:113b1d84c34f 76 */
Pokitto 51:113b1d84c34f 77
Pokitto 51:113b1d84c34f 78 class Cookie {
Pokitto 51:113b1d84c34f 79 public:
Pokitto 51:113b1d84c34f 80 /** Cookie class constructor
Pokitto 51:113b1d84c34f 81 */
Pokitto 51:113b1d84c34f 82 Cookie();
Pokitto 51:113b1d84c34f 83
Pokitto 51:113b1d84c34f 84 /** begin - Register your Cookie with a 8-byte key to begin using it
Pokitto 51:113b1d84c34f 85 *
Pokitto 51:113b1d84c34f 86 * @param 8-byte key string
Pokitto 51:113b1d84c34f 87 * @param size of cookie data in bytes
Pokitto 51:113b1d84c34f 88 * @param pointer to beginning of cookie data in memory
Pokitto 51:113b1d84c34f 89 *
Pokitto 51:113b1d84c34f 90 * @returns
Pokitto 51:113b1d84c34f 91 * 0 on success (free blocks available),
Pokitto 51:113b1d84c34f 92 * non-0 on failure (no more free keys/blocks)
Pokitto 51:113b1d84c34f 93 */
Pokitto 51:113b1d84c34f 94 int begin(const char*, int, char*);
Pokitto 51:113b1d84c34f 95
Pokitto 51:113b1d84c34f 96
Pokitto 51:113b1d84c34f 97 /** begin - Register your Cookie with a 8-byte key to begin using it
Pokitto 51:113b1d84c34f 98 *
Pokitto 51:113b1d84c34f 99 * @param 8-byte key string
Pokitto 51:113b1d84c34f 100 * @param reference to cookie data object in memory
Pokitto 51:113b1d84c34f 101 *
Pokitto 51:113b1d84c34f 102 * @returns
Pokitto 51:113b1d84c34f 103 * 0 on success (free blocks available),
Pokitto 51:113b1d84c34f 104 * non-0 on failure (no more free keys/blocks)
Pokitto 51:113b1d84c34f 105 */
Pokitto 51:113b1d84c34f 106 template< typename T >
Pokitto 51:113b1d84c34f 107 int begin(const char * key, T & object) {
Pokitto 51:113b1d84c34f 108 return begin(key, sizeof(T), reinterpret_cast<char *>(&object));
Pokitto 51:113b1d84c34f 109 }
Pokitto 51:113b1d84c34f 110
Pokitto 51:113b1d84c34f 111 /** initialize - create cookie structure. Can be called many times
Pokitto 51:113b1d84c34f 112 * @returns
Pokitto 51:113b1d84c34f 113 * 0 on success (free blocks available),
Pokitto 51:113b1d84c34f 114 * non-0 on failure (no more free keys/blocks)
Pokitto 51:113b1d84c34f 115 */
Pokitto 51:113b1d84c34f 116 int initialize();
Pokitto 51:113b1d84c34f 117
Pokitto 51:113b1d84c34f 118 /** saveCookie - Save your Cookie
Pokitto 51:113b1d84c34f 119 *
Pokitto 51:113b1d84c34f 120 * @returns
Pokitto 51:113b1d84c34f 121 * true on success (saved successfully and verified),
Pokitto 51:113b1d84c34f 122 * false on failure (something is wrong)
Pokitto 51:113b1d84c34f 123 */
Pokitto 51:113b1d84c34f 124 bool saveCookie();
Pokitto 51:113b1d84c34f 125
Pokitto 51:113b1d84c34f 126 /** loadCookie - Load your Cookie
Pokitto 51:113b1d84c34f 127 *
Pokitto 51:113b1d84c34f 128 * @returns
Pokitto 51:113b1d84c34f 129 * true on success
Pokitto 51:113b1d84c34f 130 * false on failure
Pokitto 51:113b1d84c34f 131 */
Pokitto 51:113b1d84c34f 132 bool loadCookie();
Pokitto 51:113b1d84c34f 133
Pokitto 51:113b1d84c34f 134 /** deleteCookie - your Cookie
Pokitto 51:113b1d84c34f 135 */
Pokitto 51:113b1d84c34f 136 void deleteCookie();
Pokitto 51:113b1d84c34f 137
Pokitto 51:113b1d84c34f 138 /** isOK - Get status of Cookie
Pokitto 51:113b1d84c34f 139 *
Pokitto 51:113b1d84c34f 140 * @returns
Pokitto 51:113b1d84c34f 141 * true on success (Cookie is initialized and ready to use),
Pokitto 51:113b1d84c34f 142 * false on failure (Cookie did not initialize and can't be used)
Pokitto 51:113b1d84c34f 143 */
Pokitto 51:113b1d84c34f 144 bool isOK();
Pokitto 51:113b1d84c34f 145
Pokitto 51:113b1d84c34f 146 /** readKeytableEntry - return the key at slot n
Pokitto 51:113b1d84c34f 147 *
Pokitto 51:113b1d84c34f 148 * @param slot number to check
Pokitto 51:113b1d84c34f 149 * @param pointer to a 9 char buffer for return answer
Pokitto 51:113b1d84c34f 150 *
Pokitto 51:113b1d84c34f 151 */
Pokitto 51:113b1d84c34f 152 void readKeytableEntry(int, char*);
Pokitto 51:113b1d84c34f 153
Pokitto 51:113b1d84c34f 154
Pokitto 51:113b1d84c34f 155 /** formatKeyTable(int) - erase all keys
Pokitto 51:113b1d84c34f 156 *
Pokitto 51:113b1d84c34f 157 * @param slot number to erase
Pokitto 51:113b1d84c34f 158 *
Pokitto 51:113b1d84c34f 159 */
Pokitto 51:113b1d84c34f 160 void formatKeytable();
Pokitto 51:113b1d84c34f 161
Pokitto 51:113b1d84c34f 162
Pokitto 51:113b1d84c34f 163 /** eraseKeyAt(int) - erase key at slot n
Pokitto 51:113b1d84c34f 164 *
Pokitto 51:113b1d84c34f 165 * @param slot number to erase
Pokitto 51:113b1d84c34f 166 *
Pokitto 51:113b1d84c34f 167 */
Pokitto 51:113b1d84c34f 168 void eraseKeytableEntry(int);
Pokitto 51:113b1d84c34f 169
Pokitto 51:113b1d84c34f 170 /** cleanKeytable() - erase keys that have no blocks reserved from the keyTable
Pokitto 51:113b1d84c34f 171 *
Pokitto 51:113b1d84c34f 172 */
Pokitto 51:113b1d84c34f 173 void cleanKeytable();
Pokitto 51:113b1d84c34f 174
Pokitto 51:113b1d84c34f 175 //private:
Pokitto 51:113b1d84c34f 176 public:
Pokitto 51:113b1d84c34f 177
Pokitto 51:113b1d84c34f 178 /** exists - find out if the key exists
Pokitto 51:113b1d84c34f 179 *
Pokitto 51:113b1d84c34f 180 * @param 8-byte key string
Pokitto 51:113b1d84c34f 181 *
Pokitto 51:113b1d84c34f 182 * @returns
Pokitto 51:113b1d84c34f 183 * slotnumber on key exists ,
Pokitto 51:113b1d84c34f 184 * SBINVALIDSLOT on does not exist
Pokitto 51:113b1d84c34f 185 */
Pokitto 51:113b1d84c34f 186 int exists(const char*);
Pokitto 51:113b1d84c34f 187
Pokitto 51:113b1d84c34f 188 /** getFreeKeytableSlot - Are there any keys left to use
Pokitto 51:113b1d84c34f 189 *
Pokitto 51:113b1d84c34f 190 * @returns
Pokitto 51:113b1d84c34f 191 * slot number 0...47 on success
Pokitto 51:113b1d84c34f 192 * -1 on failure
Pokitto 51:113b1d84c34f 193 */
Pokitto 51:113b1d84c34f 194 int getFreeKeytableSlot();
Pokitto 51:113b1d84c34f 195
Pokitto 51:113b1d84c34f 196 /** getFreeBlocks - Are there any storage blocks left to use
Pokitto 51:113b1d84c34f 197 *
Pokitto 51:113b1d84c34f 198 * @returns
Pokitto 51:113b1d84c34f 199 * number of blocks available
Pokitto 51:113b1d84c34f 200 */
Pokitto 51:113b1d84c34f 201 int getFreeBlocks();
Pokitto 51:113b1d84c34f 202
Pokitto 51:113b1d84c34f 203 /** getAssignedBlocks - return number of blocks already reserved for cookie
Pokitto 51:113b1d84c34f 204 *
Pokitto 51:113b1d84c34f 205 * @returns
Pokitto 51:113b1d84c34f 206 * number of blocks assigned to cookie
Pokitto 51:113b1d84c34f 207 */
Pokitto 51:113b1d84c34f 208 int getAssignedBlocks();
Pokitto 51:113b1d84c34f 209
Pokitto 51:113b1d84c34f 210
Pokitto 51:113b1d84c34f 211 /** isFreeBlock - check if block n is free to use
Pokitto 51:113b1d84c34f 212 *
Pokitto 51:113b1d84c34f 213 * @param block number
Pokitto 51:113b1d84c34f 214 * @returns
Pokitto 51:113b1d84c34f 215 * true when free
Pokitto 51:113b1d84c34f 216 * false when reserved
Pokitto 51:113b1d84c34f 217 */
Pokitto 51:113b1d84c34f 218 bool isFreeBlock(int);
Pokitto 51:113b1d84c34f 219
Pokitto 51:113b1d84c34f 220 /** isMyBlock - check if block n is already reserved for this cookie
Pokitto 51:113b1d84c34f 221 *
Pokitto 51:113b1d84c34f 222 * @param block number
Pokitto 51:113b1d84c34f 223 * @returns
Pokitto 51:113b1d84c34f 224 * true when is already reserved
Pokitto 51:113b1d84c34f 225 * false when is not
Pokitto 51:113b1d84c34f 226 */
Pokitto 51:113b1d84c34f 227 bool isMyBlock(int);
Pokitto 51:113b1d84c34f 228
Pokitto 51:113b1d84c34f 229 /** blockIsOwnedBy - check if block n is owned by Keytable entry k
Pokitto 51:113b1d84c34f 230 *
Pokitto 51:113b1d84c34f 231 * @param block number
Pokitto 51:113b1d84c34f 232 * @param keytable entry number
Pokitto 51:113b1d84c34f 233 * @returns
Pokitto 51:113b1d84c34f 234 * true when keytable entry k is owner of block n
Pokitto 51:113b1d84c34f 235 * false when is not
Pokitto 51:113b1d84c34f 236 */
Pokitto 51:113b1d84c34f 237 bool blockIsOwnedBy(int,int);
Pokitto 51:113b1d84c34f 238
Pokitto 51:113b1d84c34f 239 /** writeKeyToKeyTable - write the key into the key table
Pokitto 51:113b1d84c34f 240 *
Pokitto 51:113b1d84c34f 241 * @param 8-byte key string
Pokitto 51:113b1d84c34f 242 * @param slot number into which the key is written 0...47
Pokitto 51:113b1d84c34f 243 *
Pokitto 51:113b1d84c34f 244 */
Pokitto 51:113b1d84c34f 245 void writeKeyToKeytable(const char*, int);
Pokitto 51:113b1d84c34f 246
Pokitto 51:113b1d84c34f 247
Pokitto 51:113b1d84c34f 248 /** getBlockTableEntry - read an entry from the blocktable
Pokitto 51:113b1d84c34f 249 *
Pokitto 51:113b1d84c34f 250 * @param block table index number
Pokitto 51:113b1d84c34f 251 *
Pokitto 51:113b1d84c34f 252 * @returns
Pokitto 51:113b1d84c34f 253 * block table entry (1 byte)
Pokitto 51:113b1d84c34f 254 */
Pokitto 51:113b1d84c34f 255 char getBlockTableEntry(int);
Pokitto 51:113b1d84c34f 256
Pokitto 51:113b1d84c34f 257 /** readBlock - read the data of a block
Pokitto 51:113b1d84c34f 258 *
Pokitto 51:113b1d84c34f 259 * @param block index number
Pokitto 51:113b1d84c34f 260 * @param pointer to a buffer of SBBLOCKSIZE size to hold the return data
Pokitto 51:113b1d84c34f 261 *
Pokitto 51:113b1d84c34f 262 */
Pokitto 51:113b1d84c34f 263 void readBlock(int, char*);
Pokitto 51:113b1d84c34f 264
Pokitto 51:113b1d84c34f 265 /** freeBlock - free block from blocktable and delete data of block in EEPROM
Pokitto 51:113b1d84c34f 266 *
Pokitto 51:113b1d84c34f 267 * @param block index number
Pokitto 51:113b1d84c34f 268 *
Pokitto 51:113b1d84c34f 269 */
Pokitto 51:113b1d84c34f 270 void freeBlock(int);
Pokitto 51:113b1d84c34f 271
Pokitto 51:113b1d84c34f 272 /** reserveBlock - search and reserve a block from blocktable for use by this cookie
Pokitto 51:113b1d84c34f 273 *
Pokitto 51:113b1d84c34f 274 * @returns
Pokitto 51:113b1d84c34f 275 * true when it was possible to reserve a block
Pokitto 51:113b1d84c34f 276 * false when it was not
Pokitto 51:113b1d84c34f 277 *
Pokitto 51:113b1d84c34f 278 */
Pokitto 51:113b1d84c34f 279 bool reserveBlock();
Pokitto 51:113b1d84c34f 280
Pokitto 51:113b1d84c34f 281 /** writeQueue - write the cookie data as a stream of bytes into the EEPROM blocks
Pokitto 51:113b1d84c34f 282 *
Pokitto 51:113b1d84c34f 283 * @param byte to be written
Pokitto 51:113b1d84c34f 284 */
Pokitto 51:113b1d84c34f 285 void writeQueue(char);
Pokitto 51:113b1d84c34f 286
Pokitto 51:113b1d84c34f 287 /** readQueue - write the cookie data as a stream of bytes into the EEPROM blocks
Pokitto 51:113b1d84c34f 288 *
Pokitto 51:113b1d84c34f 289 * @returns
Pokitto 51:113b1d84c34f 290 * byte value from EEPROM memory
Pokitto 51:113b1d84c34f 291 */
Pokitto 51:113b1d84c34f 292 char readQueue();
Pokitto 51:113b1d84c34f 293
Pokitto 51:113b1d84c34f 294
Pokitto 51:113b1d84c34f 295 /** findMyNextBlock - find the next block assigned to this cookie
Pokitto 51:113b1d84c34f 296 *
Pokitto 51:113b1d84c34f 297 * @returns
Pokitto 51:113b1d84c34f 298 * number of next block
Pokitto 51:113b1d84c34f 299 */
Pokitto 51:113b1d84c34f 300 int findMyNextBlock();
Pokitto 51:113b1d84c34f 301
Pokitto 51:113b1d84c34f 302 /** keystring
Pokitto 51:113b1d84c34f 303 * identification string for the Cookie
Pokitto 51:113b1d84c34f 304 */
Pokitto 51:113b1d84c34f 305 char _key[SBKEYSIZE];
Pokitto 51:113b1d84c34f 306
Pokitto 51:113b1d84c34f 307 /** Keyorder
Pokitto 51:113b1d84c34f 308 * order number of key in key table
Pokitto 51:113b1d84c34f 309 */
Pokitto 51:113b1d84c34f 310 char _keyorder;
Pokitto 51:113b1d84c34f 311
Pokitto 51:113b1d84c34f 312 /** Status
Pokitto 51:113b1d84c34f 313 * false = uninitialized
Pokitto 51:113b1d84c34f 314 * true = ready
Pokitto 51:113b1d84c34f 315 */
Pokitto 51:113b1d84c34f 316 bool _status;
Pokitto 51:113b1d84c34f 317
Pokitto 51:113b1d84c34f 318 /** Datasize
Pokitto 51:113b1d84c34f 319 * size (in bytes) of cookie data to be saved and reloaded
Pokitto 51:113b1d84c34f 320 */
Pokitto 51:113b1d84c34f 321 int _datasize;
Pokitto 51:113b1d84c34f 322
Pokitto 51:113b1d84c34f 323 /** Pointer
Pokitto 51:113b1d84c34f 324 * pointer to cookie data
Pokitto 51:113b1d84c34f 325 */
Pokitto 51:113b1d84c34f 326 char* _pointer;
Pokitto 51:113b1d84c34f 327
Pokitto 51:113b1d84c34f 328 /** Head
Pokitto 51:113b1d84c34f 329 * data "head" for byte write/read operations
Pokitto 51:113b1d84c34f 330 */
Pokitto 51:113b1d84c34f 331 int _head;
Pokitto 51:113b1d84c34f 332
Pokitto 51:113b1d84c34f 333 /** Current block
Pokitto 51:113b1d84c34f 334 * block number that we are reading/writing
Pokitto 51:113b1d84c34f 335 */
Pokitto 51:113b1d84c34f 336 char _block;
Pokitto 51:113b1d84c34f 337 };
Pokitto 51:113b1d84c34f 338
Pokitto 51:113b1d84c34f 339
Pokitto 51:113b1d84c34f 340 } // namespace
Pokitto 51:113b1d84c34f 341
Pokitto 51:113b1d84c34f 342
Pokitto 51:113b1d84c34f 343 #endif // POKITTO_Cookie_H
Pokitto 51:113b1d84c34f 344