git.sur5r.net Git - glabels/blob - qrencode-3.1.0/qrencode.h

   1 /**
   2  * qrencode - QR Code encoder
   3  *
   4  * Copyright (C) 2006, 2007, 2008, 2009 Kentaro Fukuchi <fukuchi@megaui.net>
   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 ways to encode data: <b>encoding a string</b> or
  28  * <b>encoding a structured data</b>.
  29  *
  30  * \subsection encoding-string Encoding a string
  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, use
  40  * QRcode_encodeString8bit() instead.
  41  *
  42  * Please note that a C string can not contain NUL character. If your data
  43  * contains NUL, you should chose the second way.
  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 } QRencodeMode;
 117
 118 /**
 119  * Level of error correction.
 120  */
 121 typedef enum {
 122         QR_ECLEVEL_L = 0, ///< lowest
 123         QR_ECLEVEL_M,
 124         QR_ECLEVEL_Q,
 125         QR_ECLEVEL_H      ///< highest
 126 } QRecLevel;
 127
 128 /******************************************************************************
 129  * Input data (qrinput.c)
 130  *****************************************************************************/
 131
 132 /**
 133  * Singly linked list to contain input strings. An instance of this class
 134  * contains its version and error correction level too. It is required to
 135  * set them by QRinput_setVersion() and QRinput_setErrorCorrectionLevel(),
 136  * or use QRinput_new2() to instantiate an object.
 137  */
 138 typedef struct _QRinput QRinput;
 139
 140 /**
 141  * Instantiate an input data object. The version is set to 0 (auto-select)
 142  * and the error correction level is set to QR_ECLEVEL_L.
 143  * @return an input object (initialized). On error, NULL is returned and errno
 144  *         is set to indicate the error.
 145  * @throw ENOMEM unable to allocate memory.
 146  */
 147 extern QRinput *QRinput_new(void);
 148
 149 /**
 150  * Instantiate an input data object.
 151  * @param version version number.
 152  * @param level Error correction level.
 153  * @return an input object (initialized). On error, NULL is returned and errno
 154  *         is set to indicate the error.
 155  * @throw ENOMEM unable to allocate memory for input objects.
 156  * @throw EINVAL invalid arguments.
 157  */
 158 extern QRinput *QRinput_new2(int version, QRecLevel level);
 159
 160 /**
 161  * Append data to an input object.
 162  * The data is copied and appended to the input object.
 163  * @param input input object.
 164  * @param mode encoding mode.
 165  * @param size size of data (byte).
 166  * @param data a pointer to the memory area of the input data.
 167  * @retval 0 success.
 168  * @retval -1 an error occurred and errno is set to indeicate the error.
 169  *            See Execptions for the details.
 170  * @throw ENOMEM unable to allocate memory.
 171  * @throw EINVAL input data is invalid.
 172  *
 173  */
 174 extern int QRinput_append(QRinput *input, QRencodeMode mode, int size, const unsigned char *data);
 175
 176 /**
 177  * Get current version.
 178  * @param input input object.
 179  * @return current version.
 180  */
 181 extern int QRinput_getVersion(QRinput *input);
 182
 183 /**
 184  * Set version of the QR-code that is to be encoded.
 185  * @param input input object.
 186  * @param version version number (0 = auto)
 187  * @retval 0 success.
 188  * @retval -1 invalid argument.
 189  */
 190 extern int QRinput_setVersion(QRinput *input, int version);
 191
 192 /**
 193  * Get current error correction level.
 194  * @param input input object.
 195  * @return Current error correcntion level.
 196  */
 197 extern QRecLevel QRinput_getErrorCorrectionLevel(QRinput *input);
 198
 199 /**
 200  * Set error correction level of the QR-code that is to be encoded.
 201  * @param input input object.
 202  * @param level Error correction level.
 203  * @retval 0 success.
 204  * @retval -1 invalid argument.
 205  */
 206 extern int QRinput_setErrorCorrectionLevel(QRinput *input, QRecLevel level);
 207
 208 /**
 209  * Free the input object.
 210  * All of data chunks in the input object are freed too.
 211  * @param input input object.
 212  */
 213 extern void QRinput_free(QRinput *input);
 214
 215 /**
 216  * Validate the input data.
 217  * @param mode encoding mode.
 218  * @param size size of data (byte).
 219  * @param data a pointer to the memory area of the input data.
 220  * @retval 0 success.
 221  * @retval -1 invalid arguments.
 222  */
 223 extern int QRinput_check(QRencodeMode mode, int size, const unsigned char *data);
 224
 225 /**
 226  * Set of QRinput for structured symbols.
 227  */
 228 typedef struct _QRinput_Struct QRinput_Struct;
 229
 230 /**
 231  * Instantiate a set of input data object.
 232  * @return an instance of QRinput_Struct. On error, NULL is returned and errno
 233  *         is set to indicate the error.
 234  * @throw ENOMEM unable to allocate memory.
 235  */
 236 extern QRinput_Struct *QRinput_Struct_new(void);
 237
 238 /**
 239  * Set parity of structured symbols.
 240  * @param s structured input object.
 241  * @param parity parity of s.
 242  */
 243 extern void QRinput_Struct_setParity(QRinput_Struct *s, unsigned char parity);
 244
 245 /**
 246  * Append a QRinput object to the set.
 247  * @warning never append the same QRinput object twice or more.
 248  * @param s structured input object.
 249  * @param input an input object.
 250  * @retval >0 number of input objects in the structure.
 251  * @retval -1 an error occurred. See Exceptions for the details.
 252  * @throw ENOMEM unable to allocate memory.
 253  */
 254 extern int QRinput_Struct_appendInput(QRinput_Struct *s, QRinput *input);
 255
 256 /**
 257  * Free all of QRinput in the set.
 258  * @param s a structured input object.
 259  */
 260 extern void QRinput_Struct_free(QRinput_Struct *s);
 261
 262 /**
 263  * Split a QRinput to QRinput_Struct. It calculates a parity, set it, then
 264  * insert structured-append headers.
 265  * @param input input object. Version number and error correction level must be
 266  *        set.
 267  * @return a set of input data. On error, NULL is returned, and errno is set
 268  *         to indicate the error. See Exceptions for the details.
 269  * @throw ERANGE input data is too large.
 270  * @throw EINVAL invalid input data.
 271  * @throw ENOMEM unable to allocate memory.
 272  */
 273 extern QRinput_Struct *QRinput_splitQRinputToStruct(QRinput *input);
 274
 275 /**
 276  * Insert structured-append headers to the input structure. It calculates
 277  * a parity and set it if the parity is not set yet.
 278  * @param s input structure
 279  * @retval 0 success.
 280  * @retval -1 an error occurred and errno is set to indeicate the error.
 281  *            See Execptions for the details.
 282  * @throw EINVAL invalid input object.
 283  * @throw ENOMEM unable to allocate memory.
 284  */
 285 extern int QRinput_Struct_insertStructuredAppendHeaders(QRinput_Struct *s);
 286
 287 /******************************************************************************
 288  * QRcode output (qrencode.c)
 289  *****************************************************************************/
 290
 291 /**
 292  * QRcode class.
 293  * Symbol data is represented as an array contains width*width uchars.
 294  * Each uchar represents a module (dot). If the less significant bit of
 295  * the uchar is 1, the corresponding module is black. The other bits are
 296  * meaningless for usual applications, but here its specification is described.
 297  *
 298  * <pre>
 299  * MSB 76543210 LSB
 300  *     |||||||`- 1=black/0=white
 301  *     ||||||`-- data and ecc code area
 302  *     |||||`--- format information
 303  *     ||||`---- version information
 304  *     |||`----- timing pattern
 305  *     ||`------ alignment pattern
 306  *     |`------- finder pattern and separator
 307  *     `-------- non-data modules (format, timing, etc.)
 308  * </pre>
 309  */
 310 typedef struct {
 311         int version;         ///< version of the symbol
 312         int width;           ///< width of the symbol
 313         unsigned char *data; ///< symbol data
 314 } QRcode;
 315
 316 /**
 317  * Singly-linked list of QRcode. Used to represent a structured symbols.
 318  * A list is terminated with NULL.
 319  */
 320 typedef struct _QRcode_List QRcode_List;
 321
 322 struct _QRcode_List {
 323         QRcode *code;
 324         QRcode_List *next;
 325 };
 326
 327 /**
 328  * Create a symbol from the input data.
 329  * @warning This function is THREAD UNSAFE.
 330  * @param input input data.
 331  * @return an instance of QRcode class. The version of the result QRcode may
 332  *         be larger than the designated version. On error, NULL is returned,
 333  *         and errno is set to indicate the error. See Exceptions for the
 334  *         details.
 335  * @throw EINVAL invalid input object.
 336  * @throw ENOMEM unable to allocate memory for input objects.
 337  */
 338 extern QRcode *QRcode_encodeInput(QRinput *input);
 339
 340 /**
 341  * Create a symbol from the string. The library automatically parses the input
 342  * string and encodes in a QR Code symbol.
 343  * @warning This function is THREAD UNSAFE.
 344  * @param string input string. It must be NULL terminated.
 345  * @param version version of the symbol. If 0, the library chooses the minimum
 346  *                version for the given input data.
 347  * @param level error correction level.
 348  * @param hint tell the library how non-alphanumerical characters should be
 349  *             encoded. If QR_MODE_KANJI is given, kanji characters will be
 350  *             encoded as Shif-JIS characters. If QR_MODE_8 is given, all of
 351  *             non-alphanumerical characters will be encoded as is. If you want
 352  *             to embed UTF-8 string, choose this.
 353  * @param casesensitive case-sensitive(1) or not(0).
 354  * @return an instance of QRcode class. The version of the result QRcode may
 355  *         be larger than the designated version. On error, NULL is returned,
 356  *         and errno is set to indicate the error. See Exceptions for the
 357  *         details.
 358  * @throw EINVAL invalid input object.
 359  * @throw ENOMEM unable to allocate memory for input objects.
 360  */
 361 extern QRcode *QRcode_encodeString(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive);
 362
 363 /**
 364  * Same to QRcode_encodeString(), but encode whole data in 8-bit mode.
 365  * @warning This function is THREAD UNSAFE.
 366  */
 367 extern QRcode *QRcode_encodeString8bit(const char *string, int version, QRecLevel level);
 368
 369 /**
 370  * Free the instance of QRcode class.
 371  * @param qrcode an instance of QRcode class.
 372  */
 373 extern void QRcode_free(QRcode *qrcode);
 374
 375 /**
 376  * Create structured symbols from the input data.
 377  * @warning This function is THREAD UNSAFE.
 378  * @param s
 379  * @return a singly-linked list of QRcode.
 380  */
 381 extern QRcode_List *QRcode_encodeInputStructured(QRinput_Struct *s);
 382
 383 /**
 384  * Create structured symbols from the string. The library automatically parses
 385  * the input string and encodes in a QR Code symbol.
 386  * @warning This function is THREAD UNSAFE.
 387  * @param string input string. It should be NULL terminated.
 388  * @param version version of the symbol.
 389  * @param level error correction level.
 390  * @param hint tell the library how non-alphanumerical characters should be
 391  *             encoded. If QR_MODE_KANJI is given, kanji characters will be
 392  *             encoded as Shif-JIS characters. If QR_MODE_8 is given, all of
 393  *             non-alphanumerical characters will be encoded as is. If you want
 394  *             to embed UTF-8 string, choose this.
 395  * @param casesensitive case-sensitive(1) or not(0).
 396  * @return a singly-linked list of QRcode. On error, NULL is returned, and
 397  *         errno is set to indicate the error. See Exceptions for the details.
 398  * @throw EINVAL invalid input object.
 399  * @throw ENOMEM unable to allocate memory for input objects.
 400  */
 401 extern QRcode_List *QRcode_encodeStringStructured(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive);
 402
 403 /**
 404  * Same to QRcode_encodeStringStructured(), but encode whole data in 8-bit mode.
 405  * @warning This function is THREAD UNSAFE.
 406  */
 407 extern QRcode_List *QRcode_encodeString8bitStructured(const char *string, int version, QRecLevel level);
 408
 409 /**
 410  * Return the number of symbols included in a QRcode_List.
 411  * @param qrlist a head entry of a QRcode_List.
 412  * @return number of symbols in the list.
 413  */
 414 extern int QRcode_List_size(QRcode_List *qrlist);
 415
 416 /**
 417  * Free the QRcode_List.
 418  * @param qrlist a head entry of a QRcode_List.
 419  */
 420 extern void QRcode_List_free(QRcode_List *qrlist);
 421
 422 #if defined(__cplusplus)
 423 }
 424 #endif
 425
 426 #endif /* __QRENCODE_H__ */