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 *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 *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 | |