416 lines
16 KiB
C
416 lines
16 KiB
C
/**
|
||
* qrencode - QR Code encoder
|
||
*
|
||
* Copyright (C) 2006-2011 Kentaro Fukuchi <kentaro@fukuchi.org>
|
||
*
|
||
* This library is free software; you can redistribute 重新分配 it and/or
|
||
* modify修改 it under the terms of根据什么什么的条款 the GNU Lesser General Public
|
||
* License (GNU公共授权许可)as published (出版，发布)by the Free Software Foundation(基础); either
|
||
* version 2.1 of the License, or any later version.
|
||
*
|
||
* This library is distributed in the hope that it will be useful,
|
||
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
* Lesser General Public License for more details.
|
||
*
|
||
* You should have received a copy of the GNU Lesser General Public
|
||
* License along with this library; if not, write to the Free Software
|
||
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
||
*/
|
||
|
||
/** \mainpage
|
||
* Libqrencode is a library for encoding data in a QR Code symbol, a kind of 2D
|
||
* symbology. Libqrencode是用于在QR码符号的编码数据，一种2D符号的文库
|
||
*
|
||
* \section encoding Encoding 部分编码的编码
|
||
*
|
||
* There are two ways to encode data:这有两种方式来编码 <b>encoding a string 为字符串进行编码</b> or
|
||
* <b>encoding a structured data为混合数据进行编码</b>.
|
||
*
|
||
* \subsection encoding-string Encoding a string encoding-string这一块为字符串进行编码
|
||
* You can encode a string by calling QRcode_encodeString().你可以通过调用QRcode_encodeString()来为字符串进行编码
|
||
* The given string is parsed automatically and encoded.给定的字符串被自动解析和编码 If you want to encode
|
||
* data that can be represented as代表 a C string style (NUL terminated 结束终止), you can
|
||
* simply use this way.
|
||
*
|
||
* If the input data contains Kanji包含汉字 (Shift-JIS) characters and you want to
|
||
* encode them as Kanji in QR Code, you should give QR_MODE_KANJI as a hint.提示暗示
|
||
* Otherwise, all of non-alphanumeric 非字母数字字符 characters are encoded as 8 bit data.
|
||
* If you want to encode a whole string in 8 bit mode, use
|
||
* QRcode_encodeString8bit() instead.
|
||
*
|
||
* Please note that a C string can not contain NUL character. If your data
|
||
* contains NUL, you should chose the second way. 请注意，C字符串不能包含NULL字符。如果您的数据中包含NUL，你应该选择第二种方式。
|
||
*
|
||
* \subsection encoding-input Encoding a structured data encoding-input这一块为混合数据进行编码
|
||
* You can construct a structured input data manually. 您可以手动构建一个结构化的输入数据。If the structure of the
|
||
* input data is known, you can use this way.
|
||
* At first, create a ::QRinput object by QRinput_new(). Then add input data
|
||
* to the QRinput object by QRinput_append(). Finally call QRcode_encodeInput()
|
||
* to encode the QRinput data.
|
||
* You can reuse 重用 the QRinput data again to encode it in other symbols with
|
||
* different parameters.不同参数的其他符号
|
||
*
|
||
* \section result Result
|
||
* The encoded symbol is resulted as a ::QRcode object. It will contain
|
||
* its version number版本号, width of the symbol符号的宽度 and an array represents the symbol 数组表示符号.
|
||
* See ::QRcode for the details. You can free the object by QRcode_free().
|
||
*
|
||
* Please note that the version of the result may be larger than specified.
|
||
* In such cases, the input data would be too large to be encoded in a
|
||
* symbol of the specified version.输入的数据会因为太大而不被编码在指定版本的符号中
|
||
*
|
||
* \section structured Structured append
|
||
* Libqrencode can generate 产生 "Structured-appended" symbols that enables to split
|
||
* a large data set into mulitple QR codes.把一个很大数据分成多个QRcode。 A QR code reader concatenates
|
||
* multiple QR code symbols into a string.QR码阅读器符连接多个QR码符号转换成字符串。
|
||
* Just like QRcode_encodeString(), you can use QRcode_encodeStringStructured()
|
||
* to generate structured-appended symbols. This functions returns an instance
|
||
* of ::QRcode_List. The returned list is a singly-linked list of QRcode: you
|
||
* can retrieve each QR code in this way:
|
||
*
|
||
* \code
|
||
* QRcode_List *qrcodes;
|
||
* QRcode_List *entry;
|
||
* QRcode *qrcode;
|
||
*
|
||
* qrcodes = QRcode_encodeStringStructured(...);
|
||
* entry = qrcodes;
|
||
* while(entry != NULL) {
|
||
* qrcode = entry->code;
|
||
* // do something
|
||
* entry = entry->next;
|
||
* }
|
||
* QRcode_List_free(entry);
|
||
* \endcode
|
||
*
|
||
* Instead of using auto-parsing functions, you can construct your own
|
||
* structured input. At first, instantiate an object of ::QRinput_Struct
|
||
* by calling QRinput_Struct_new(). This object can hold multiple ::QRinput,
|
||
* and one QR code is generated for a ::QRinput.
|
||
* QRinput_Struct_appendInput() appends a ::QRinput to a ::QRinput_Struct
|
||
* object. In order to generate structured-appended symbols, it is required to
|
||
* embed headers to each symbol. You can use
|
||
* QRinput_Struct_insertStructuredAppendHeaders() to insert appropriate
|
||
* headers to each symbol. You should call this function just once before
|
||
* encoding symbols.
|
||
*可以构建自己的input结构来取代自动分析函数。首先，调用QRinput_Struct_new()函数来实例化一个QRinput_Struct对象。
|
||
*这个对象可以保存多个QRinput。QRinput_Struct_appendInput()添加一个QRinput到QRinput_Struct对象中。
|
||
*为了生成structured-appended符号，需要嵌入头到每个符号中。可以使用QRinput_Struct_insertStructuredAppendHeaders()来插入合适的头到每个符号中。
|
||
*必须在编码符号钱调用这个方法一次。
|
||
*/
|
||
|
||
#ifndef __QRENCODE_H__
|
||
#define __QRENCODE_H__
|
||
|
||
#ifdef __cplusplus
|
||
#if __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
#endif
|
||
|
||
|
||
/**
|
||
* Encoding mode.
|
||
*/
|
||
typedef enum {
|
||
QR_MODE_NUL = -1, ///< Terminator (NUL character). Internal use only
|
||
QR_MODE_NUM = 0, ///< Numeric mode 数字模式
|
||
QR_MODE_AN, ///< Alphabet-numeric mode 字母数字模式
|
||
QR_MODE_8, ///< 8-bit data mode 8位数据模式
|
||
QR_MODE_KANJI, ///< Kanji (shift-jis) mode 汉字模式
|
||
QR_MODE_STRUCTURE, ///< Internal use only
|
||
QR_MODE_ECI, ///< ECI mode
|
||
QR_MODE_FNC1FIRST, ///< FNC1, first position
|
||
QR_MODE_FNC1SECOND, ///< FNC1, second position
|
||
} QRencodeMode;
|
||
|
||
/**
|
||
* Level of error correction.
|
||
*/
|
||
typedef enum {
|
||
QR_ECLEVEL_L = 0, ///< lowest
|
||
QR_ECLEVEL_M,
|
||
QR_ECLEVEL_Q,
|
||
QR_ECLEVEL_H ///< highest
|
||
} QRecLevel;
|
||
|
||
/**
|
||
* Maximum version (size) of QR-code symbol.
|
||
*/
|
||
#define QRSPEC_VERSION_MAX 40
|
||
|
||
/**
|
||
* Maximum version (size) of QR-code symbol.
|
||
*/
|
||
#define MQRSPEC_VERSION_MAX 4
|
||
|
||
|
||
/******************************************************************************
|
||
* Input data (qrinput.c)
|
||
*****************************************************************************/
|
||
|
||
/**
|
||
* Singly linked list to contain input strings. An instance of this class
|
||
* contains its version and error correction level too. It is required to
|
||
* set them by QRinput_setVersion() and QRinput_setErrorCorrectionLevel(),
|
||
* or use QRinput_new2() to instantiate an object.
|
||
*/
|
||
typedef struct _QRinput QRinput;
|
||
|
||
/**
|
||
* Instantiate an input data object.实例化一个输入数据对象 The version is set to 0 (auto-select)
|
||
* and the error correction level is set to QR_ECLEVEL_L.
|
||
* @return an input object (initialized)返回一个实例化后输入对象. On error, NULL is returned and errno
|
||
* is set to indicate the error.
|
||
* @throw ENOMEM unable to allocate memory.
|
||
*/
|
||
extern QRinput *QRinput_new(void);
|
||
|
||
/**
|
||
* Instantiate an input data object.
|
||
* @param version version number.
|
||
* @param level Error correction level.
|
||
* @return an input object (initialized). On error, NULL is returned and errno
|
||
* is set to indicate the error.
|
||
* @throw ENOMEM unable to allocate memory for input objects.
|
||
* @throw EINVAL invalid arguments.
|
||
*/
|
||
extern QRinput *QRinput_new2(int version, QRecLevel level);
|
||
|
||
/**
|
||
* Instantiate an input data object. Object's Micro QR Code (另外一种二维码的名字,他只有一个定位矩形，存储数据量比较小，但适用于打印空间小场合)flag is set.
|
||
* Unlike with full-sized QR Code, version number must be specified (>0).
|
||
* @param version version number (1--4).
|
||
* @param level Error correction level.
|
||
* @return an input object (initialized). On error, NULL is returned and errno
|
||
* is set to indicate the error.
|
||
* @throw ENOMEM unable to allocate memory for input objects.
|
||
* @throw EINVAL invalid arguments.
|
||
*/
|
||
extern QRinput *QRinput_newMQR(int version, QRecLevel level);
|
||
|
||
/**
|
||
* Append data to an input object.
|
||
* The data is copied and appended to the input object.
|
||
* @param input input object.
|
||
* @param mode encoding mode.
|
||
* @param size size of data (byte).
|
||
* @param data a pointer to the memory area of the input data.
|
||
* @retval 0 success.
|
||
* @retval -1 an error occurred and errno is set to indeicate the error.
|
||
* See Execptions for the details.
|
||
* @throw ENOMEM unable to allocate memory.
|
||
* @throw EINVAL input data is invalid.
|
||
*
|
||
*/
|
||
extern int QRinput_append(QRinput *input, QRencodeMode mode, int size, const unsigned char *data);
|
||
|
||
/**
|
||
* Append ECI header.特殊的字符集
|
||
* @param input input object.
|
||
* @param ecinum ECI indicator number (0 - 999999)
|
||
* @retval 0 success.
|
||
* @retval -1 an error occurred and errno is set to indeicate the error.
|
||
* See Execptions for the details.
|
||
* @throw ENOMEM unable to allocate memory.
|
||
* @throw EINVAL input data is invalid.
|
||
*
|
||
*/
|
||
extern int QRinput_appendECIheader(QRinput *input, unsigned int ecinum);
|
||
|
||
/**
|
||
* Get current version.
|
||
* @param input input object.
|
||
* @return current version.
|
||
*/
|
||
extern int QRinput_getVersion(QRinput *input);
|
||
|
||
/**
|
||
* Set version of the QR code that is to be encoded.
|
||
* This function cannot be applied to Micro QR Code.这设置版本号不适用于Micro QR Code
|
||
* @param input input object.
|
||
* @param version version number (0 = auto)
|
||
* @retval 0 success.
|
||
* @retval -1 invalid argument.
|
||
*/
|
||
extern int QRinput_setVersion(QRinput *input, int version);
|
||
|
||
/**
|
||
* Get current error correction level.
|
||
* @param input input object.
|
||
* @return Current error correcntion level.
|
||
*/
|
||
extern QRecLevel QRinput_getErrorCorrectionLevel(QRinput *input);
|
||
|
||
/**
|
||
* Set error correction level of the QR code that is to be encoded.
|
||
* This function cannot be applied to Micro QR Code.
|
||
* @param input input object.
|
||
* @param level Error correction level.
|
||
* @retval 0 success.
|
||
* @retval -1 invalid argument.
|
||
*/
|
||
extern int QRinput_setErrorCorrectionLevel(QRinput *input, QRecLevel level);
|
||
|
||
/**
|
||
*适用于给Micro QR Code 设置版本号和纠错级别
|
||
* Set version and error correction level of the QR code at once.
|
||
* This function is recommened for Micro QR Code.
|
||
* @param input input object.
|
||
* @param version version number (0 = auto)
|
||
* @param level Error correction level.
|
||
* @retval 0 success.
|
||
* @retval -1 invalid argument.
|
||
*/
|
||
extern int QRinput_setVersionAndErrorCorrectionLevel(QRinput *input, int version, QRecLevel level);
|
||
|
||
/**
|
||
* Free the input object.
|
||
* All of data chunks in the input object are freed too.
|
||
* @param input input object.
|
||
*/
|
||
extern void QRinput_free(QRinput *input);
|
||
|
||
/**
|
||
* Validate the input data.检验输入的数据
|
||
* @param mode encoding mode.
|
||
* @param size size of data (byte).
|
||
* @param data a pointer to the memory area of the input data.
|
||
* @retval 0 success.
|
||
* @retval -1 invalid arguments.
|
||
*/
|
||
extern int QRinput_check(QRencodeMode mode, int size, const unsigned char *data);
|
||
|
||
|
||
/**
|
||
* Free all of QRinput in the set.
|
||
* @param s a structured input object.
|
||
*/
|
||
|
||
|
||
/******************************************************************************
|
||
* QRcode output (qrencode.c)
|
||
*****************************************************************************/
|
||
|
||
/**
|
||
* QRcode class.
|
||
* Symbol data is represented as an array contains width*width uchars.
|
||
* Each uchar represents a module (dot). If the less significant bit不显著位 of
|
||
* the uchar is 1, the corresponding module is black. The other bits are
|
||
* meaningless for usual applications, but here its specification is described.
|
||
*
|
||
* <pre>
|
||
* MSB 76543210 LSB
|
||
* |||||||`- 1=black/0=white
|
||
* ||||||`-- data and ecc code area
|
||
* |||||`--- format information
|
||
* ||||`---- version information
|
||
* |||`----- timing pattern
|
||
* ||`------ alignment pattern
|
||
* |`------- finder pattern and separator
|
||
* `-------- non-data modules (format, timing, etc.)
|
||
* </pre>
|
||
*/
|
||
typedef struct {
|
||
int version; ///< version of the symbol
|
||
int width; ///< width of the symbol
|
||
unsigned char *data; ///< symbol data
|
||
} QRcode;
|
||
|
||
/**
|
||
* Singly-linked list of QRcode. Used to represent a structured symbols.
|
||
* A list is terminated with NULL.
|
||
*/
|
||
typedef struct _QRcode_List QRcode_List;
|
||
|
||
struct _QRcode_List {
|
||
QRcode *code;
|
||
QRcode_List *next;
|
||
};
|
||
|
||
/**
|
||
* Create a symbol from the input data.
|
||
* @warning This function is THREAD UNSAFE when pthread is disabled.
|
||
* @param input input data.
|
||
* @return an instance of QRcode class. The version of the result QRcode may
|
||
* be larger than the designated version. On error, NULL is returned,
|
||
* and errno is set to indicate the error. See Exceptions for the
|
||
* details.
|
||
* @throw EINVAL invalid input object.
|
||
* @throw ENOMEM unable to allocate memory for input objects.
|
||
*/
|
||
extern QRcode *QRcode_encodeInput(QRinput *input);
|
||
|
||
/**
|
||
* Create a symbol from the string. The library automatically parses the input
|
||
* string and encodes in a QR Code symbol.通过字符串创建一个符号，字符库会自动分析输入的字符串然后为它进行编码。
|
||
* @warning This function is THREAD UNSAFE when pthread is disabled.
|
||
* @param string input string. It must be NUL terminated.
|
||
* @param version version of the symbol. If 0, the library chooses the minimum
|
||
* version for the given input data.
|
||
* @param level error correction level.
|
||
* @param hint tell the library how non-alphanumerical characters should be
|
||
* encoded. If QR_MODE_KANJI is given, kanji characters will be
|
||
* encoded as Shif-JIS characters. If QR_MODE_8 is given, all of
|
||
* non-alphanumerical characters will be encoded as is. If you want
|
||
* to embed UTF-8 string, choose this.
|
||
* @param casesensitive case-sensitive(1) or not(0).
|
||
* @return an instance of QRcode class. The version of the result QRcode may
|
||
* be larger than the designated version. On error, NULL is returned,
|
||
* and errno is set to indicate the error. See Exceptions for the
|
||
* details.
|
||
* @throw EINVAL invalid input object.
|
||
* @throw ENOMEM unable to allocate memory for input objects.
|
||
* @throw ERANGE input data is too large.
|
||
*/
|
||
extern QRcode *QRcode_encodeString(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive);
|
||
|
||
/**
|
||
* Same to QRcode_encodeString(), but encode whole data in 8-bit mode.
|
||
* @warning This function is THREAD UNSAFE when pthread is disabled.
|
||
*/
|
||
|
||
|
||
/**
|
||
* Micro QR Code version of QRcode_encodeString().
|
||
* @warning This function is THREAD UNSAFE when pthread is disabled.
|
||
*/
|
||
extern QRcode *QRcode_encodeStringMQR(const char *string, int version, QRecLevel level, QRencodeMode hint, int casesensitive);
|
||
|
||
/**
|
||
* Encode byte stream (may include '\0') in 8-bit mode.在8位模式下对字节流进行编码
|
||
* @warning This function is THREAD UNSAFE when pthread is disabled.
|
||
* @param size size of the input data.
|
||
* @param data input data.
|
||
* @param version version of the symbol. If 0, the library chooses the minimum
|
||
* version for the given input data.
|
||
* @param level error correction level.
|
||
* @throw EINVAL invalid input object.
|
||
* @throw ENOMEM unable to allocate memory for input objects.
|
||
* @throw ERANGE input data is too large.
|
||
*/
|
||
extern QRcode *QRcode_encodeData(int size, const unsigned char *data, int version, QRecLevel level);
|
||
|
||
/**
|
||
* Micro QR Code version of QRcode_encodeData().
|
||
* @warning This function is THREAD UNSAFE when pthread is disabled.
|
||
*/
|
||
extern QRcode *QRcode_encodeDataMQR(int size, const unsigned char *data, int version, QRecLevel level);
|
||
|
||
/**
|
||
* Free the instance of QRcode class.
|
||
* @param qrcode an instance of QRcode class.
|
||
*/
|
||
extern void QRcode_free(QRcode *qrcode);
|
||
|
||
|
||
#ifdef __cplusplus
|
||
#if __cplusplus
|
||
}
|
||
#endif
|
||
#endif
|
||
|
||
|
||
#endif /* __QRENCODE_H__ */
|