1 /** 2 * qrencode - QR Code encoder 3 * 4 * Copyright (C) 2006-2012 Kentaro Fukuchi <kentaro@fukuchi.org> 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 /** \mainpage 22 * Libqrencode is a library for encoding data in a QR Code symbol, a kind of 2D 23 * symbology. 24 * 25 * \section encoding Encoding 26 * 27 * There are two methods to encode data: <b>encoding a string/data</b> or 28 * <b>encoding a structured data</b>. 29 * 30 * \subsection encoding-string Encoding a string/data 31 * You can encode a string by calling QRcode_encodeString(). 32 * The given string is parsed automatically and encoded. If you want to encode 33 * data that can be represented as a C string style (NUL terminated), you can 34 * simply use this way. 35 * 36 * If the input data contains Kanji (Shift-JIS) characters and you want to 37 * encode them as Kanji in QR Code, you should give QR_MODE_KANJI as a hint. 38 * Otherwise, all of non-alphanumeric characters are encoded as 8 bit data. 39 * If you want to encode a whole string in 8 bit mode, you can use 40 * QRcode_encodeString8bit() instead. 41 * 42 * Please note that a C string can not contain NUL characters. If your data 43 * contains NUL, you must use QRcode_encodeData(). 44 * 45 * \subsection encoding-input Encoding a structured data 46 * You can construct a structured input data manually. If the structure of the 47 * input data is known, you can use this way. 48 * At first, create a ::QRinput object by QRinput_new(). Then add input data 49 * to the QRinput object by QRinput_append(). Finally call QRcode_encodeInput() 50 * to encode the QRinput data. 51 * You can reuse the QRinput data again to encode it in other symbols with 52 * different parameters. 53 * 54 * \section result Result 55 * The encoded symbol is resulted as a ::QRcode object. It will contain 56 * its version number, width of the symbol and an array represents the symbol. 57 * See ::QRcode for the details. You can free the object by QRcode_free(). 58 * 59 * Please note that the version of the result may be larger than specified. 60 * In such cases, the input data would be too large to be encoded in a 61 * symbol of the specified version. 62 * 63 * \section structured Structured append 64 * Libqrencode can generate "Structured-appended" symbols that enables to split 65 * a large data set into mulitple QR codes. A QR code reader concatenates 66 * multiple QR code symbols into a string. 67 * Just like QRcode_encodeString(), you can use QRcode_encodeStringStructured() 68 * to generate structured-appended symbols. This functions returns an instance 69 * of ::QRcode_List. The returned list is a singly-linked list of QRcode: you 70 * can retrieve each QR code in this way: 71 * 72 * \code 73 * QRcode_List *qrcodes; 74 * QRcode_List *entry; 75 * QRcode *qrcode; 76 * 77 * qrcodes = QRcode_encodeStringStructured(...); 78 * entry = qrcodes; 79 * while(entry != NULL) { 80 * qrcode = entry->code; 81 * // do something 82 * entry = entry->next; 83 * } 84 * QRcode_List_free(entry); 85 * \endcode 86 * 87 * Instead of using auto-parsing functions, you can construct your own 88 * structured input. At first, instantiate an object of ::QRinput_Struct 89 * by calling QRinput_Struct_new(). This object can hold multiple ::QRinput, 90 * and one QR code is generated for a ::QRinput. 91 * QRinput_Struct_appendInput() appends a ::QRinput to a ::QRinput_Struct 92 * object. In order to generate structured-appended symbols, it is required to 93 * embed headers to each symbol. You can use 94 * QRinput_Struct_insertStructuredAppendHeaders() to insert appropriate 95 * headers to each symbol. You should call this function just once before 96 * encoding symbols. 97 */ 98 99 #ifndef __QRENCODE_H__ 100 #define __QRENCODE_H__ 101 102 #if defined(__cplusplus) 103 extern "C" { 104 #endif 105 106 /** 107 * Encoding mode. 108 */ 109 typedef enum { 110 QR_MODE_NUL = -1, ///< Terminator (NUL character). Internal use only 111 QR_MODE_NUM = 0, ///< Numeric mode 112 QR_MODE_AN, ///< Alphabet-numeric mode 113 QR_MODE_8, ///< 8-bit data mode 114 QR_MODE_KANJI, ///< Kanji (shift-jis) mode 115 QR_MODE_STRUCTURE, ///< Internal use only 116 QR_MODE_ECI, ///< ECI mode 117 QR_MODE_FNC1FIRST, ///< FNC1, first position 118 QR_MODE_FNC1SECOND, ///< FNC1, second position 119 } QRencodeMode; 120 121 /** 122 * Level of error correction. 123 */ 124 typedef enum { 125 QR_ECLEVEL_L = 0, ///< lowest 126 QR_ECLEVEL_M, 127 QR_ECLEVEL_Q, 128 QR_ECLEVEL_H ///< highest 129 } QRecLevel; 130 131 /** 132 * Maximum version (size) of QR-code symbol. 133 */ 134 #define QRSPEC_VERSION_MAX 40 135 136 /** 137 * Maximum version (size) of QR-code symbol. 138 */ 139 #define MQRSPEC_VERSION_MAX 4 140 141 142 /****************************************************************************** 143 * Input data (qrinput.c) 144 *****************************************************************************/ 145 146 /** 147 * Singly linked list to contain input strings. An instance of this class 148 * contains its version and error correction level too. It is required to 149 * set them by QRinput_setVersion() and QRinput_setErrorCorrectionLevel(), 150 * or use QRinput_new2() to instantiate an object. 151 */ 152 typedef struct _QRinput QRinput; 153 154 /** 155 * Instantiate an input data object. The version is set to 0 (auto-select) 156 * and the error correction level is set to QR_ECLEVEL_L. 157 * @return an input object (initialized). On error, NULL is returned and errno 158 * is set to indicate the error. 159 * @throw ENOMEM unable to allocate memory. 160 */ 161 extern QRinput *QRinput_new(void); 162 163 /** 164 * Instantiate an input data object. 165 * @param version version number. 166 * @param level Error correction level. 167 * @return an input object (initialized). On error, NULL is returned and errno 168 * is set to indicate the error. 169 * @throw ENOMEM unable to allocate memory for input objects. 170 * @throw EINVAL invalid arguments. 171 */ 172 extern QRinput *QRinput_new2(int version, QRecLevel level); 173 174 /** 175 * Instantiate an input data object. Object's Micro QR Code flag is set. 176 * Unlike with full-sized QR Code, version number must be specified (>0). 177 * @param version version number (1--4). 178 * @param level Error correction level. 179 * @return an input object (initialized). On error, NULL is returned and errno 180 * is set to indicate the error. 181 * @throw ENOMEM unable to allocate memory for input objects. 182 * @throw EINVAL invalid arguments. 183 */ 184 extern QRinput *QRinput_newMQR(int version, QRecLevel level); 185 186 /** 187 * Append data to an input object. 188 * The data is copied and appended to the input object. 189 * @param input input object. 190 * @param mode encoding mode. 191 * @param size size of data (byte). 192 * @param data a pointer to the memory area of the input data. 193 * @retval 0 success. 194 * @retval -1 an error occurred and errno is set to indeicate the error. 195 * See Execptions for the details. 196 * @throw ENOMEM unable to allocate memory. 197 * @throw EINVAL input data is invalid. 198 * 199 */ 200 extern int QRinput_append(QRinput *input, QRencodeMode mode, int size, const unsigned char *data); 201 202 /** 203 * Append ECI header. 204 * @param input input object. 205 * @param ecinum ECI indicator number (0 - 999999) 206 * @retval 0 success. 207 * @retval -1 an error occurred and errno is set to indeicate the error. 208 * See Execptions for the details. 209 * @throw ENOMEM unable to allocate memory. 210 * @throw EINVAL input data is invalid. 211 * 212 */ 213 extern int QRinput_appendECIheader(QRinput *input, unsigned int ecinum); 214 215 /** 216 * Get current version. 217 * @param input input object. 218 * @return current version. 219 */ 220 extern int QRinput_getVersion(QRinput *input); 221 222 /** 223 * Set version of the QR code that is to be encoded. 224 * This function cannot be applied to Micro QR Code. 225 * @param input input object. 226 * @param version version number (0 = auto) 227 * @retval 0 success. 228 * @retval -1 invalid argument. 229 */ 230 extern int QRinput_setVersion(QRinput *input, int version); 231 232 /** 233 * Get current error correction level. 234 * @param input input object. 235 * @return Current error correcntion level. 236 */ 237 extern QRecLevel QRinput_getErrorCorrectionLevel(QRinput *input); 238 239 /** 240 * Set error correction level of the QR code that is to be encoded. 241 * This function cannot be applied to Micro QR Code. 242 * @param input input object. 243 * @param level Error correction level. 244 * @retval 0 success. 245 * @retval -1 invalid argument. 246 */ 247 extern int QRinput_setErrorCorrectionLevel(QRinput *input, QRecLevel level); 248 249 /** 250 * Set version and error correction level of the QR code at once. 251 * This function is recommened for Micro QR Code. 252 * @param input input object. 253 * @param version version number (0 = auto) 254 * @param level Error correction level. 255 * @retval 0 success. 256 * @retval -1 invalid argument. 257 */ 258 extern int QRinput_setVersionAndErrorCorrectionLevel(QRinput *input, int version, QRecLevel level); 259 260 /** 261 * Free the input object. 262 * All of data chunks in the input object are freed too. 263 * @param input input object. 264 */ 265 extern void QRinput_free(QRinput *input); 266 267 /** 268 * Validate the input data. 269 * @param mode encoding mode. 270 * @param size size of data (byte). 271 * @param data a pointer to the memory area of the input data. 272 * @retval 0 success. 273 * @retval -1 invalid arguments. 274 */ 275 extern int QRinput_check(QRencodeMode mode, int size, const unsigned char *data); 276 277 /** 278 * Set of QRinput for structured symbols. 279 */ 280 typedef struct _QRinput_Struct QRinput_Struct; 281 282 /** 283 * Instantiate a set of input data object. 284 * @return an instance of QRinput_Struct. On error, NULL is returned and errno 285 * is set to indicate the error. 286 * @throw ENOMEM unable to allocate memory. 287 */ 288 extern QRinput_Struct *QRinput_Struct_new(void); 289 290 /** 291 * Set parity of structured symbols. 292 * @param s structured input object. 293 * @param parity parity of s. 294 */ 295 extern void QRinput_Struct_setParity(QRinput_Struct *s, unsigned char parity); 296 297 /** 298 * Append a QRinput object to the set. QRinput created by QRinput_newMQR() 299 * will be rejected. 300 * @warning never append the same QRinput object twice or more. 301 * @param s structured input object. 302 * @param input an input object. 303 * @retval >0 number of input objects in the structure. 304 * @retval -1 an error occurred. See Exceptions for the details. 305 * @throw ENOMEM unable to allocate memory. 306 * @throw EINVAL invalid arguments. 307 */ 308 extern int QRinput_Struct_appendInput(QRinput_Struct *s, QRinput *input); 309 310 /** 311 * Free all of QRinput in the set. 312 * @param s a structured input object. 313 */ 314 extern void QRinput_Struct_free(QRinput_Struct *s); 315 316 /** 317 * Split a QRinput to QRinput_Struct. It calculates a parity, set it, then 318 * insert structured-append headers. QRinput created by QRinput_newMQR() will 319 * be rejected. 320 * @param input input object. Version number and error correction level must be 321 * set. 322 * @return a set of input data. On error, NULL is returned, and errno is set 323 * to indicate the error. See Exceptions for the details. 324 * @throw ERANGE input data is too large. 325 * @throw EINVAL invalid input data. 326 * @throw ENOMEM unable to allocate memory. 327 */ 328 extern QRinput_Struct *QRinput_splitQRinputToStruct(QRinput *input); 329 330 /** 331 * Insert structured-append headers to the input structure. It calculates 332 * a parity and set it if the parity is not set yet. 333 * @param s input structure 334 * @retval 0 success. 335 * @retval -1 an error occurred and errno is set to indeicate the error. 336 * See Execptions for the details. 337 * @throw EINVAL invalid input object. 338 * @throw ENOMEM unable to allocate memory. 339 */ 340 extern int QRinput_Struct_insertStructuredAppendHeaders(QRinput_Struct *s); 341 342 /** 343 * Set FNC1-1st position flag. 344 */ 345 extern int QRinput_setFNC1First(QRinput *input); 346 347 /** 348 * Set FNC1-2nd position flag and application identifier. 349 */ 350 extern int QRinput_setFNC1Second(QRinput *input, unsigned char appid); 351 352 /****************************************************************************** 353 * QRcode output (qrencode.c) 354 *****************************************************************************/ 355 356 /** 357 * QRcode class. 358 * Symbol data is represented as an array contains width*width uchars. 359 * Each uchar represents a module (dot). If the less significant bit of 360 * the uchar is 1, the corresponding module is black. The other bits are 361 * meaningless for usual applications, but here its specification is described. 362 * 363 * <pre> 364 * MSB 76543210 LSB 365 * |||||||`- 1=black/0=white 366 * ||||||`-- data and ecc code area 367 * |||||`--- format information 368 * ||||`---- version information 369 * |||`----- timing pattern 370 * ||`------ alignment pattern 371 * |`------- finder pattern and separator 372 * `-------- non-data modules (format, timing, etc.) 373 * </pre> 374 */ 375 typedef struct { 376 int version; ///< version of the symbol 377 int width; ///< width of the symbol 378 unsigned char *data; ///< symbol data 379 } QRcode; 380 381 /** 382 * Singly-linked list of QRcode. Used to represent a structured symbols. 383 * A list is terminated with NULL. 384 */ 385 typedef struct _QRcode_List { 386 QRcode *code; 387 struct _QRcode_List *next; 388 } QRcode_List; 389 390 /** 391 * Create a symbol from the input data. 392 * @warning This function is THREAD UNSAFE when pthread is disabled. 393 * @param input input data. 394 * @return an instance of QRcode class. The version of the result QRcode may 395 * be larger than the designated version. On error, NULL is returned, 396 * and errno is set to indicate the error. See Exceptions for the 397 * details. 398 * @throw EINVAL invalid input object. 399 * @throw ENOMEM unable to allocate memory for input objects. 400 */ 401 extern QRcode *QRcode_encodeInput(QRinput *input); 402 403 /** 404 * Create a symbol from the string. The library automatically parses the input 405 * string and encodes in a QR Code symbol. 406 * @warning This function is THREAD UNSAFE when pthread is disabled. 407 * @param string input string. It must be NUL terminated. 408 * @param version version of the symbol. If 0, the library chooses the minimum 409 * version for the given input data. 410 * @param level error correction level. 411 * @param hint tell the library how Japanese Kanji characters should be 412 * encoded. If QR_MODE_KANJI is given, the library assumes that the 413 * given string contains Shift-JIS characters and encodes them in 414 * Kanji-mode. If QR_MODE_8 is given, all of non-alphanumerical 415 * characters will be encoded as is. If you want to embed UTF-8 416 * string, choose this. Other mode will cause EINVAL error. 417 * @param casesensitive case-sensitive(1) or not(0). 418 * @return an instance of QRcode class. The version of the result QRcode may 419 * be larger than the designated version. On error, NULL is returned, 420 * and errno is set to indicate the error. See Exceptions for the 421 * details. 422 * @throw EINVAL invalid input object. 423 * @throw ENOMEM unable to allocate memory for input objects. 424 * @throw ERANGE input data is too large. 425 */ 426 extern QRcode *QRcode_encodeString(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive); 427 428 /** 429 * Same to QRcode_encodeString(), but encode whole data in 8-bit mode. 430 * @warning This function is THREAD UNSAFE when pthread is disabled. 431 */ 432 extern QRcode *QRcode_encodeString8bit(const char *string, int version, QRecLevel level); 433 434 /** 435 * Micro QR Code version of QRcode_encodeString(). 436 * @warning This function is THREAD UNSAFE when pthread is disabled. 437 */ 438 extern QRcode *QRcode_encodeStringMQR(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive); 439 440 /** 441 * Micro QR Code version of QRcode_encodeString8bit(). 442 * @warning This function is THREAD UNSAFE when pthread is disabled. 443 */ 444 extern QRcode *QRcode_encodeString8bitMQR(const char *string, int version, QRecLevel level); 445 446 /** 447 * Encode byte stream (may include '\0') in 8-bit mode. 448 * @warning This function is THREAD UNSAFE when pthread is disabled. 449 * @param size size of the input data. 450 * @param data input data. 451 * @param version version of the symbol. If 0, the library chooses the minimum 452 * version for the given input data. 453 * @param level error correction level. 454 * @throw EINVAL invalid input object. 455 * @throw ENOMEM unable to allocate memory for input objects. 456 * @throw ERANGE input data is too large. 457 */ 458 extern QRcode *QRcode_encodeData(int size, const unsigned char *data, int version, QRecLevel level); 459 460 /** 461 * Micro QR Code version of QRcode_encodeData(). 462 * @warning This function is THREAD UNSAFE when pthread is disabled. 463 */ 464 extern QRcode *QRcode_encodeDataMQR(int size, const unsigned char *data, int version, QRecLevel level); 465 466 /** 467 * Free the instance of QRcode class. 468 * @param qrcode an instance of QRcode class. 469 */ 470 extern void QRcode_free(QRcode *qrcode); 471 472 /** 473 * Create structured symbols from the input data. 474 * @warning This function is THREAD UNSAFE when pthread is disabled. 475 * @param s 476 * @return a singly-linked list of QRcode. 477 */ 478 extern QRcode_List *QRcode_encodeInputStructured(QRinput_Struct *s); 479 480 /** 481 * Create structured symbols from the string. The library automatically parses 482 * the input string and encodes in a QR Code symbol. 483 * @warning This function is THREAD UNSAFE when pthread is disabled. 484 * @param string input string. It must be NUL terminated. 485 * @param version version of the symbol. 486 * @param level error correction level. 487 * @param hint tell the library how Japanese Kanji characters should be 488 * encoded. If QR_MODE_KANJI is given, the library assumes that the 489 * given string contains Shift-JIS characters and encodes them in 490 * Kanji-mode. If QR_MODE_8 is given, all of non-alphanumerical 491 * characters will be encoded as is. If you want to embed UTF-8 492 * string, choose this. Other mode will cause EINVAL error. 493 * @param casesensitive case-sensitive(1) or not(0). 494 * @return a singly-linked list of QRcode. On error, NULL is returned, and 495 * errno is set to indicate the error. See Exceptions for the details. 496 * @throw EINVAL invalid input object. 497 * @throw ENOMEM unable to allocate memory for input objects. 498 */ 499 extern QRcode_List *QRcode_encodeStringStructured(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive); 500 501 /** 502 * Same to QRcode_encodeStringStructured(), but encode whole data in 8-bit mode. 503 * @warning This function is THREAD UNSAFE when pthread is disabled. 504 */ 505 extern QRcode_List *QRcode_encodeString8bitStructured(const char *string, int version, QRecLevel level); 506 507 /** 508 * Create structured symbols from byte stream (may include '\0'). Wholde data 509 * are encoded in 8-bit mode. 510 * @warning This function is THREAD UNSAFE when pthread is disabled. 511 * @param size size of the input data. 512 * @param data input dat. 513 * @param version version of the symbol. 514 * @param level error correction level. 515 * @return a singly-linked list of QRcode. On error, NULL is returned, and 516 * errno is set to indicate the error. See Exceptions for the details. 517 * @throw EINVAL invalid input object. 518 * @throw ENOMEM unable to allocate memory for input objects. 519 */ 520 extern QRcode_List *QRcode_encodeDataStructured(int size, const unsigned char *data, int version, QRecLevel level); 521 522 /** 523 * Return the number of symbols included in a QRcode_List. 524 * @param qrlist a head entry of a QRcode_List. 525 * @return number of symbols in the list. 526 */ 527 extern int QRcode_List_size(QRcode_List *qrlist); 528 529 /** 530 * Free the QRcode_List. 531 * @param qrlist a head entry of a QRcode_List. 532 */ 533 extern void QRcode_List_free(QRcode_List *qrlist); 534 535 536 /****************************************************************************** 537 * System utilities 538 *****************************************************************************/ 539 540 /** 541 * Return a string that identifies the library version. 542 * @param major_version 543 * @param minor_version 544 * @param micro_version 545 */ 546 extern void QRcode_APIVersion(int *major_version, int *minor_version, int *micro_version); 547 548 /** 549 * Return a string that identifies the library version. 550 * @return a string identifies the library version. The string is held by the 551 * library. Do NOT free it. 552 */ 553 extern char *QRcode_APIVersionString(void); 554 555 /** 556 * Clear all caches. This is only for debug purpose. If you are attacking a 557 * complicated memory leak bug, try this to reduce the reachable blocks record. 558 * @warning This function is THREAD UNSAFE when pthread is disabled. 559 */ 560 extern void QRcode_clearCache(void); 561 562 #if defined(__cplusplus) 563 } 564 #endif 565 566 #endif /* __QRENCODE_H__ */ 567