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)
103extern "C" {
104#endif
105
106/**
107 * Encoding mode.
108 */
109typedef 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 */
124typedef 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 */
152typedef 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 */
161extern 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 */
172extern 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 */
184extern 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 */
200extern 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 */
213extern int QRinput_appendECIheader(QRinput *input, unsigned int ecinum);
214
215/**
216 * Get current version.
217 * @param input input object.
218 * @return current version.
219 */
220extern 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 */
230extern 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 */
237extern 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 */
247extern 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 */
258extern 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 */
265extern 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 */
275extern int QRinput_check(QRencodeMode mode, int size, const unsigned char *data);
276
277/**
278 * Set of QRinput for structured symbols.
279 */
280typedef 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 */
288extern 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 */
295extern 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 */
308extern 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 */
314extern 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 */
328extern 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 */
340extern int QRinput_Struct_insertStructuredAppendHeaders(QRinput_Struct *s);
341
342/**
343 * Set FNC1-1st position flag.
344 */
345extern int QRinput_setFNC1First(QRinput *input);
346
347/**
348 * Set FNC1-2nd position flag and application identifier.
349 */
350extern 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 */
375typedef 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 */
385typedef 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 */
401extern 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 */
426extern 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 */
432extern 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 */
438extern 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 */
444extern 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 */
458extern 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 */
464extern 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 */
470extern 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 */
478extern 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 */
499extern 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 */
505extern 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 */
520extern 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 */
527extern 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 */
533extern 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 */
546extern 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 */
553extern 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 */
560extern void QRcode_clearCache(void);
561
562#if defined(__cplusplus)
563}
564#endif
565
566#endif /* __QRENCODE_H__ */
567