1 /*------------------------------------------------------------------------
2 * Copyright 2007-2010 (c) Jeff Brown <spadix@users.sourceforge.net>
3 *
4 * This file is part of the ZBar Bar Code Reader.
5 *
6 * The ZBar Bar Code Reader is free software; you can redistribute it
7 * and/or modify it under the terms of the GNU Lesser Public License as
8 * published by the Free Software Foundation; either version 2.1 of
9 * the License, or (at your option) any later version.
10 *
11 * The ZBar Bar Code Reader is distributed in the hope that it will be
12 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty
13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser Public License
17 * along with the ZBar Bar Code Reader; if not, write to the Free
18 * Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301 USA
20 *
21 * http://sourceforge.net/projects/zbar
22 *------------------------------------------------------------------------*/
23 #ifndef _ZBAR_H_
24 #define _ZBAR_H_
25
26 #include <stdint.h>
27
28 /** @file
29 * ZBar Barcode Reader C API definition
30 */
31
32 /** @mainpage
33 *
34 * interface to the barcode reader is available at several levels.
35 * most applications will want to use the high-level interfaces:
36 *
37 * @section high-level High-Level Interfaces
38 *
39 * these interfaces wrap all library functionality into an easy-to-use
40 * package for a specific toolkit:
41 * - the "GTK+ 2.x widget" may be used with GTK GUI applications. a
42 * Python wrapper is included for PyGtk
43 * - the @ref zbar::QZBar "Qt4 widget" may be used with Qt GUI
44 * applications
45 * - the Processor interface (in @ref c-processor "C" or @ref
46 * zbar::Processor "C++") adds a scanning window to an application
47 * with no GUI.
48 *
49 * @section mid-level Intermediate Interfaces
50 *
51 * building blocks used to construct high-level interfaces:
52 * - the ImageScanner (in @ref c-imagescanner "C" or @ref
53 * zbar::ImageScanner "C++") looks for barcodes in a library defined
54 * image object
55 * - the Window abstraction (in @ref c-window "C" or @ref
56 * zbar::Window "C++") sinks library images, displaying them on the
57 * platform display
58 * - the Video abstraction (in @ref c-video "C" or @ref zbar::Video
59 * "C++") sources library images from a video device
60 *
61 * @section low-level Low-Level Interfaces
62 *
63 * direct interaction with barcode scanning and decoding:
64 * - the Scanner (in @ref c-scanner "C" or @ref zbar::Scanner "C++")
65 * looks for barcodes in a linear intensity sample stream
66 * - the Decoder (in @ref c-decoder "C" or @ref zbar::Decoder "C++")
67 * extracts barcodes from a stream of bar and space widths
68 */
69
70 #ifdef __cplusplus
71
72 /** C++ namespace for library interfaces */
73 namespace zbar {
74 extern "C" {
75 #endif
76
77
78 /** @name Global library interfaces */
79 /*@{*/
80
81 /** "color" of element: bar or space. */
82 typedef enum zbar_color_e {
83 ZBAR_SPACE = 0, /**< light area or space between bars */
84 ZBAR_BAR = 1, /**< dark area or colored bar segment */
85 } zbar_color_t;
86
87 /** decoded symbol type. */
88 typedef enum zbar_symbol_type_e {
89 ZBAR_NONE = 0, /**< no symbol decoded */
90 ZBAR_PARTIAL = 1, /**< intermediate status */
91 ZBAR_EAN2 = 2, /**< GS1 2-digit add-on */
92 ZBAR_EAN5 = 5, /**< GS1 5-digit add-on */
93 ZBAR_EAN8 = 8, /**< EAN-8 */
94 ZBAR_UPCE = 9, /**< UPC-E */
95 ZBAR_ISBN10 = 10, /**< ISBN-10 (from EAN-13). @since 0.4 */
96 ZBAR_UPCA = 12, /**< UPC-A */
97 ZBAR_EAN13 = 13, /**< EAN-13 */
98 ZBAR_ISBN13 = 14, /**< ISBN-13 (from EAN-13). @since 0.4 */
99 ZBAR_COMPOSITE = 15, /**< EAN/UPC composite */
100 ZBAR_I25 = 25, /**< Interleaved 2 of 5. @since 0.4 */
101 ZBAR_DATABAR = 34, /**< GS1 DataBar (RSS). @since 0.11 */
102 ZBAR_DATABAR_EXP = 35, /**< GS1 DataBar Expanded. @since 0.11 */
103 ZBAR_CODABAR = 38, /**< Codabar. @since 0.11 */
104 ZBAR_CODE39 = 39, /**< Code 39. @since 0.4 */
105 ZBAR_PDF417 = 57, /**< PDF417. @since 0.6 */
106 ZBAR_QRCODE = 64, /**< QR Code. @since 0.10 */
107 ZBAR_SQCODE = 80, /**< SQ Code. @since 0.20.1 */
108 ZBAR_CODE93 = 93, /**< Code 93. @since 0.11 */
109 ZBAR_CODE128 = 128, /**< Code 128 */
110
111 /*
112 * Please see _zbar_get_symbol_hash() if adding
113 * anything after 128
114 */
115
116 /** mask for base symbol type.
117 * @deprecated in 0.11, remove this from existing code
118 */
119 ZBAR_SYMBOL = 0x00ff,
120 /** 2-digit add-on flag.
121 * @deprecated in 0.11, a ::ZBAR_EAN2 component is used for
122 * 2-digit GS1 add-ons
123 */
124 ZBAR_ADDON2 = 0x0200,
125 /** 5-digit add-on flag.
126 * @deprecated in 0.11, a ::ZBAR_EAN5 component is used for
127 * 5-digit GS1 add-ons
128 */
129 ZBAR_ADDON5 = 0x0500,
130 /** add-on flag mask.
131 * @deprecated in 0.11, GS1 add-ons are represented using composite
132 * symbols of type ::ZBAR_COMPOSITE; add-on components use ::ZBAR_EAN2
133 * or ::ZBAR_EAN5
134 */
135 ZBAR_ADDON = 0x0700,
136 } zbar_symbol_type_t;
137
138 /** decoded symbol coarse orientation.
139 * @since 0.11
140 */
141 typedef enum zbar_orientation_e {
142 ZBAR_ORIENT_UNKNOWN = -1, /**< unable to determine orientation */
143 ZBAR_ORIENT_UP, /**< upright, read left to right */
144 ZBAR_ORIENT_RIGHT, /**< sideways, read top to bottom */
145 ZBAR_ORIENT_DOWN, /**< upside-down, read right to left */
146 ZBAR_ORIENT_LEFT, /**< sideways, read bottom to top */
147 } zbar_orientation_t;
148
149 /** error codes. */
150 typedef enum zbar_error_e {
151 ZBAR_OK = 0, /**< no error */
152 ZBAR_ERR_NOMEM, /**< out of memory */
153 ZBAR_ERR_INTERNAL, /**< internal library error */
154 ZBAR_ERR_UNSUPPORTED, /**< unsupported request */
155 ZBAR_ERR_INVALID, /**< invalid request */
156 ZBAR_ERR_SYSTEM, /**< system error */
157 ZBAR_ERR_LOCKING, /**< locking error */
158 ZBAR_ERR_BUSY, /**< all resources busy */
159 ZBAR_ERR_XDISPLAY, /**< X11 display error */
160 ZBAR_ERR_XPROTO, /**< X11 protocol error */
161 ZBAR_ERR_CLOSED, /**< output window is closed */
162 ZBAR_ERR_WINAPI, /**< windows system error */
163 ZBAR_ERR_NUM /**< number of error codes */
164 } zbar_error_t;
165
166 /** decoder configuration options.
167 * @since 0.4
168 */
169 typedef enum zbar_config_e {
170 ZBAR_CFG_ENABLE = 0, /**< enable symbology/feature */
171 ZBAR_CFG_ADD_CHECK, /**< enable check digit when optional */
172 ZBAR_CFG_EMIT_CHECK, /**< return check digit when present */
173 ZBAR_CFG_ASCII, /**< enable full ASCII character set */
174 ZBAR_CFG_BINARY, /**< don't convert binary data to text */
175 ZBAR_CFG_NUM, /**< number of boolean decoder configs */
176
177 ZBAR_CFG_MIN_LEN = 0x20, /**< minimum data length for valid decode */
178 ZBAR_CFG_MAX_LEN, /**< maximum data length for valid decode */
179
180 ZBAR_CFG_UNCERTAINTY = 0x40,/**< required video consistency frames */
181
182 ZBAR_CFG_POSITION = 0x80, /**< enable scanner to collect position data */
183 ZBAR_CFG_TEST_INVERTED, /**< if fails to decode, test inverted */
184
185 ZBAR_CFG_X_DENSITY = 0x100, /**< image scanner vertical scan density */
186 ZBAR_CFG_Y_DENSITY, /**< image scanner horizontal scan density */
187 } zbar_config_t;
188
189 /** decoder symbology modifier flags.
190 * @since 0.11
191 */
192 typedef enum zbar_modifier_e {
193 /** barcode tagged as GS1 (EAN.UCC) reserved
194 * (eg, FNC1 before first data character).
195 * data may be parsed as a sequence of GS1 AIs
196 */
197 ZBAR_MOD_GS1 = 0,
198
199 /** barcode tagged as AIM reserved
200 * (eg, FNC1 after first character or digit pair)
201 */
202 ZBAR_MOD_AIM,
203
204 /** number of modifiers */
205 ZBAR_MOD_NUM,
206 } zbar_modifier_t;
207
208 typedef enum video_control_type_e {
209 VIDEO_CNTL_INTEGER = 1,
210 VIDEO_CNTL_MENU,
211 VIDEO_CNTL_BUTTON,
212 VIDEO_CNTL_INTEGER64,
213 VIDEO_CNTL_STRING,
214 VIDEO_CNTL_BOOLEAN,
215 } video_control_type_t;
216
217 /** store video control menu
218 * @param name name of the menu item
219 * @param val integer value associated with the item
220 */
221 typedef struct video_control_menu_s {
222 char *name;
223 int64_t value;
224 } video_control_menu_t;
225
226 /** store video controls
227 * @param name name of the control
228 * @param group name of the control group/class
229 * @param type type of the control
230 * @param min minimum value of control (if control is integer)
231 * @param max maximum value of control (if control is integer)
232 * @param def default value of control (if control is integer)
233 * @param step increment steps (if control is integer)
234 * @param menu menu array
235 * @param menu_size menu size
236 * @since 0.20
237 */
238 typedef struct video_controls_s {
239 char *name;
240 char *group;
241 video_control_type_t type;
242
243 int64_t min, max, def;
244 uint64_t step;
245
246 unsigned int menu_size;
247 video_control_menu_t *menu;
248
249 void *next;
250
251 // video drivers may add extra private data in the end of this struct
252 } video_controls_t;
253
254 /** store a video resolution
255 * @param width width of the video window
256 * @param height length of the video window
257 * @param max_fps maximum streaming speed, in frames per second
258 * @since 0.22
259 */
260 struct video_resolution_s {
261 unsigned int width, height;
262 float max_fps;
263 };
264
265 /** retrieve runtime library version information.
266 * @param major set to the running major version (unless NULL)
267 * @param minor set to the running minor version (unless NULL)
268 * @returns 0
269 */
270 extern int zbar_version(unsigned *major,
271 unsigned *minor,
272 unsigned *patch);
273
274 /** set global library debug level.
275 * @param verbosity desired debug level. higher values create more spew
276 */
277 extern void zbar_set_verbosity(int verbosity);
278
279 /** increase global library debug level.
280 * eg, for -vvvv
281 */
282 extern void zbar_increase_verbosity(void);
283
284 /** retrieve string name for symbol encoding.
285 * @param sym symbol type encoding
286 * @returns the static string name for the specified symbol type,
287 * or "UNKNOWN" if the encoding is not recognized
288 */
289 extern const char *zbar_get_symbol_name(zbar_symbol_type_t sym);
290
291 /** retrieve string name for addon encoding.
292 * @param sym symbol type encoding
293 * @returns static string name for any addon, or the empty string
294 * if no addons were decoded
295 * @deprecated in 0.11
296 */
297 extern const char *zbar_get_addon_name(zbar_symbol_type_t sym);
298
299 /** retrieve string name for configuration setting.
300 * @param config setting to name
301 * @returns static string name for config,
302 * or the empty string if value is not a known config
303 */
304 extern const char *zbar_get_config_name(zbar_config_t config);
305
306 /** retrieve string name for modifier.
307 * @param modifier flag to name
308 * @returns static string name for modifier,
309 * or the empty string if the value is not a known flag
310 */
311 extern const char *zbar_get_modifier_name(zbar_modifier_t modifier);
312
313 /** retrieve string name for orientation.
314 * @param orientation orientation encoding
315 * @returns the static string name for the specified orientation,
316 * or "UNKNOWN" if the orientation is not recognized
317 * @since 0.11
318 */
319 extern const char *zbar_get_orientation_name(zbar_orientation_t orientation);
320
321 /** parse a configuration string of the form "[symbology.]config[=value]".
322 * the config must match one of the recognized names.
323 * the symbology, if present, must match one of the recognized names.
324 * if symbology is unspecified, it will be set to 0.
325 * if value is unspecified it will be set to 1.
326 * @returns 0 if the config is parsed successfully, 1 otherwise
327 * @since 0.4
328 */
329 extern int zbar_parse_config(const char *config_string,
330 zbar_symbol_type_t *symbology,
331 zbar_config_t *config,
332 int *value);
333
334 /** consistently compute fourcc values across architectures
335 * (adapted from v4l2 specification)
336 * @since 0.11
337 */
338 #define zbar_fourcc(a, b, c, d) \
339 ((unsigned long)(a) | \
340 ((unsigned long)(b) << 8) | \
341 ((unsigned long)(c) << 16) | \
342 ((unsigned long)(d) << 24))
343
344 /** parse a fourcc string into its encoded integer value.
345 * @since 0.11
346 */
zbar_fourcc_parse(const char * format)347 static inline unsigned long zbar_fourcc_parse (const char *format)
348 {
349 unsigned long fourcc = 0;
350 if(format) {
351 int i;
352 for(i = 0; i < 4 && format[i]; i++)
353 fourcc |= ((unsigned long)format[i]) << (i * 8);
354 }
355 return(fourcc);
356 }
357
358 /** @internal type unsafe error API (don't use) */
359 extern int _zbar_error_spew(const void *object,
360 int verbosity);
361 extern const char *_zbar_error_string(const void *object,
362 int verbosity);
363 extern zbar_error_t _zbar_get_error_code(const void *object);
364
365 /*@}*/
366
367 struct zbar_symbol_s;
368 typedef struct zbar_symbol_s zbar_symbol_t;
369
370 struct zbar_symbol_set_s;
371 typedef struct zbar_symbol_set_s zbar_symbol_set_t;
372
373
374 /*------------------------------------------------------------*/
375 /** @name Symbol interface
376 * decoded barcode symbol result object. stores type, data, and image
377 * location of decoded symbol. all memory is owned by the library
378 */
379 /*@{*/
380
381 /** @typedef zbar_symbol_t
382 * opaque decoded symbol object.
383 */
384
385 /** symbol reference count manipulation.
386 * increment the reference count when you store a new reference to the
387 * symbol. decrement when the reference is no longer used. do not
388 * refer to the symbol once the count is decremented and the
389 * containing image has been recycled or destroyed.
390 * @note the containing image holds a reference to the symbol, so you
391 * only need to use this if you keep a symbol after the image has been
392 * destroyed or reused.
393 * @since 0.9
394 */
395 extern void zbar_symbol_ref(const zbar_symbol_t *symbol,
396 int refs);
397
398 /** retrieve type of decoded symbol.
399 * @returns the symbol type
400 */
401 extern zbar_symbol_type_t zbar_symbol_get_type(const zbar_symbol_t *symbol);
402
403 /** retrieve symbology boolean config settings.
404 * @returns a bitmask indicating which configs were set for the detected
405 * symbology during decoding.
406 * @since 0.11
407 */
408 extern unsigned int zbar_symbol_get_configs(const zbar_symbol_t *symbol);
409
410 /** retrieve symbology modifier flag settings.
411 * @returns a bitmask indicating which characteristics were detected
412 * during decoding.
413 * @since 0.11
414 */
415 extern unsigned int zbar_symbol_get_modifiers(const zbar_symbol_t *symbol);
416
417 /** retrieve data decoded from symbol.
418 * @returns the data string
419 */
420 extern const char *zbar_symbol_get_data(const zbar_symbol_t *symbol);
421
422 /** retrieve length of binary data.
423 * @returns the length of the decoded data
424 */
425 extern unsigned int zbar_symbol_get_data_length(const zbar_symbol_t *symbol);
426
427 /** retrieve a symbol confidence metric.
428 * @returns an unscaled, relative quantity: larger values are better
429 * than smaller values, where "large" and "small" are application
430 * dependent.
431 * @note expect the exact definition of this quantity to change as the
432 * metric is refined. currently, only the ordered relationship
433 * between two values is defined and will remain stable in the future
434 * @since 0.9
435 */
436 extern int zbar_symbol_get_quality(const zbar_symbol_t *symbol);
437
438 /** retrieve current cache count. when the cache is enabled for the
439 * image_scanner this provides inter-frame reliability and redundancy
440 * information for video streams.
441 * @returns < 0 if symbol is still uncertain.
442 * @returns 0 if symbol is newly verified.
443 * @returns > 0 for duplicate symbols
444 */
445 extern int zbar_symbol_get_count(const zbar_symbol_t *symbol);
446
447 /** retrieve the number of points in the location polygon. the
448 * location polygon defines the image area that the symbol was
449 * extracted from.
450 * @returns the number of points in the location polygon
451 * @note this is currently not a polygon, but the scan locations
452 * where the symbol was decoded
453 */
454 extern unsigned zbar_symbol_get_loc_size(const zbar_symbol_t *symbol);
455
456 /** retrieve location polygon x-coordinates.
457 * points are specified by 0-based index.
458 * @returns the x-coordinate for a point in the location polygon.
459 * @returns -1 if index is out of range
460 */
461 extern int zbar_symbol_get_loc_x(const zbar_symbol_t *symbol,
462 unsigned index);
463
464 /** retrieve location polygon y-coordinates.
465 * points are specified by 0-based index.
466 * @returns the y-coordinate for a point in the location polygon.
467 * @returns -1 if index is out of range
468 */
469 extern int zbar_symbol_get_loc_y(const zbar_symbol_t *symbol,
470 unsigned index);
471
472 /** retrieve general orientation of decoded symbol.
473 * @returns a coarse, axis-aligned indication of symbol orientation or
474 * ::ZBAR_ORIENT_UNKNOWN if unknown
475 * @since 0.11
476 */
477 extern zbar_orientation_t
478 zbar_symbol_get_orientation(const zbar_symbol_t *symbol);
479
480 /** iterate the set to which this symbol belongs (there can be only one).
481 * @returns the next symbol in the set, or
482 * @returns NULL when no more results are available
483 */
484 extern const zbar_symbol_t *zbar_symbol_next(const zbar_symbol_t *symbol);
485
486 /** retrieve components of a composite result.
487 * @returns the symbol set containing the components
488 * @returns NULL if the symbol is already a physical symbol
489 * @since 0.10
490 */
491 extern const zbar_symbol_set_t*
492 zbar_symbol_get_components(const zbar_symbol_t *symbol);
493
494 /** iterate components of a composite result.
495 * @returns the first physical component symbol of a composite result
496 * @returns NULL if the symbol is already a physical symbol
497 * @since 0.10
498 */
499 extern const zbar_symbol_t*
500 zbar_symbol_first_component(const zbar_symbol_t *symbol);
501
502 /** print XML symbol element representation to user result buffer.
503 * @see http://zbar.sourceforge.net/2008/barcode.xsd for the schema.
504 * @param symbol is the symbol to print
505 * @param buffer is the inout result pointer, it will be reallocated
506 * with a larger size if necessary.
507 * @param buflen is inout length of the result buffer.
508 * @returns the buffer pointer
509 * @since 0.6
510 */
511 extern char *zbar_symbol_xml(const zbar_symbol_t *symbol,
512 char **buffer,
513 unsigned *buflen);
514
515 /*@}*/
516
517 /*------------------------------------------------------------*/
518 /** @name Symbol Set interface
519 * container for decoded result symbols associated with an image
520 * or a composite symbol.
521 * @since 0.10
522 */
523 /*@{*/
524
525 /** @typedef zbar_symbol_set_t
526 * opaque symbol iterator object.
527 * @since 0.10
528 */
529
530 /** reference count manipulation.
531 * increment the reference count when you store a new reference.
532 * decrement when the reference is no longer used. do not refer to
533 * the object any longer once references have been released.
534 * @since 0.10
535 */
536 extern void zbar_symbol_set_ref(const zbar_symbol_set_t *symbols,
537 int refs);
538
539 /** retrieve set size.
540 * @returns the number of symbols in the set.
541 * @since 0.10
542 */
543 extern int zbar_symbol_set_get_size(const zbar_symbol_set_t *symbols);
544
545 /** set iterator.
546 * @returns the first decoded symbol result in a set
547 * @returns NULL if the set is empty
548 * @since 0.10
549 */
550 extern const zbar_symbol_t*
551 zbar_symbol_set_first_symbol(const zbar_symbol_set_t *symbols);
552
553 /** raw result iterator.
554 * @returns the first decoded symbol result in a set, *before* filtering
555 * @returns NULL if the set is empty
556 * @since 0.11
557 */
558 extern const zbar_symbol_t*
559 zbar_symbol_set_first_unfiltered(const zbar_symbol_set_t *symbols);
560
561 /*@}*/
562
563 /*------------------------------------------------------------*/
564 /** @name Image interface
565 * stores image data samples along with associated format and size
566 * metadata
567 */
568 /*@{*/
569
570 struct zbar_image_s;
571 /**
572 * zbar_image_t: opaque image object.
573 */
574 typedef struct zbar_image_s zbar_image_t;
575
576 /** cleanup handler callback function.
577 * called to free sample data when an image is destroyed.
578 */
579 typedef void (zbar_image_cleanup_handler_t)(zbar_image_t *image);
580
581 /** data handler callback function.
582 * called when decoded symbol results are available for an image
583 */
584 typedef void (zbar_image_data_handler_t)(zbar_image_t *image,
585 const void *userdata);
586
587 /** new image constructor.
588 * @returns a new image object with uninitialized data and format.
589 * this image should be destroyed (using zbar_image_destroy()) as
590 * soon as the application is finished with it
591 */
592 extern zbar_image_t *zbar_image_create(void);
593
594 /** image destructor. all images created by or returned to the
595 * application should be destroyed using this function. when an image
596 * is destroyed, the associated data cleanup handler will be invoked
597 * if available
598 * @note make no assumptions about the image or the data buffer.
599 * they may not be destroyed/cleaned immediately if the library
600 * is still using them. if necessary, use the cleanup handler hook
601 * to keep track of image data buffers
602 */
603 extern void zbar_image_destroy(zbar_image_t *image);
604
605 /** image reference count manipulation.
606 * increment the reference count when you store a new reference to the
607 * image. decrement when the reference is no longer used. do not
608 * refer to the image any longer once the count is decremented.
609 * zbar_image_ref(image, -1) is the same as zbar_image_destroy(image)
610 * @since 0.5
611 */
612 extern void zbar_image_ref(zbar_image_t *image,
613 int refs);
614
615 /** image format conversion. refer to the documentation for supported
616 * image formats
617 * @returns a @em new image with the sample data from the original image
618 * converted to the requested format. the original image is
619 * unaffected.
620 * @note the converted image size may be rounded (up) due to format
621 * constraints
622 */
623 extern zbar_image_t *zbar_image_convert(const zbar_image_t *image,
624 unsigned long format);
625
626 /** image format conversion with crop/pad.
627 * if the requested size is larger than the image, the last row/column
628 * are duplicated to cover the difference. if the requested size is
629 * smaller than the image, the extra rows/columns are dropped from the
630 * right/bottom.
631 * @returns a @em new image with the sample data from the original
632 * image converted to the requested format and size.
633 * @note the image is @em not scaled
634 * @see zbar_image_convert()
635 * @since 0.4
636 */
637 extern zbar_image_t *zbar_image_convert_resize(const zbar_image_t *image,
638 unsigned long format,
639 unsigned width,
640 unsigned height);
641
642 /** retrieve the image format.
643 * @returns the fourcc describing the format of the image sample data
644 */
645 extern unsigned long zbar_image_get_format(const zbar_image_t *image);
646
647 /** retrieve a "sequence" (page/frame) number associated with this image.
648 * @since 0.6
649 */
650 extern unsigned zbar_image_get_sequence(const zbar_image_t *image);
651
652 /** retrieve the width of the image.
653 * @returns the width in sample columns
654 */
655 extern unsigned zbar_image_get_width(const zbar_image_t *image);
656
657 /** retrieve the height of the image.
658 * @returns the height in sample rows
659 */
660 extern unsigned zbar_image_get_height(const zbar_image_t *image);
661
662 /** retrieve both dimensions of the image.
663 * fills in the width and height in samples
664 */
665 extern void zbar_image_get_size(const zbar_image_t *image,
666 unsigned *width,
667 unsigned *height);
668
669 /** retrieve the crop rectangle.
670 * fills in the image coordinates of the upper left corner and size
671 * of an axis-aligned rectangular area of the image that will be scanned.
672 * defaults to the full image
673 * @since 0.11
674 */
675 extern void zbar_image_get_crop(const zbar_image_t *image,
676 unsigned *x,
677 unsigned *y,
678 unsigned *width,
679 unsigned *height);
680
681 /** return the image sample data. the returned data buffer is only
682 * valid until zbar_image_destroy() is called
683 */
684 extern const void *zbar_image_get_data(const zbar_image_t *image);
685
686 /** return the size of image data.
687 * @since 0.6
688 */
689 extern unsigned long zbar_image_get_data_length(const zbar_image_t *img);
690
691 /** retrieve the decoded results.
692 * @returns the (possibly empty) set of decoded symbols
693 * @returns NULL if the image has not been scanned
694 * @since 0.10
695 */
696 extern const zbar_symbol_set_t*
697 zbar_image_get_symbols(const zbar_image_t *image);
698
699 /** associate the specified symbol set with the image, replacing any
700 * existing results. use NULL to release the current results from the
701 * image.
702 * @see zbar_image_scanner_recycle_image()
703 * @since 0.10
704 */
705 extern void zbar_image_set_symbols(zbar_image_t *image,
706 const zbar_symbol_set_t *symbols);
707
708 /** image_scanner decode result iterator.
709 * @returns the first decoded symbol result for an image
710 * or NULL if no results are available
711 */
712 extern const zbar_symbol_t*
713 zbar_image_first_symbol(const zbar_image_t *image);
714
715 /** specify the fourcc image format code for image sample data.
716 * refer to the documentation for supported formats.
717 * @note this does not convert the data!
718 * (see zbar_image_convert() for that)
719 */
720 extern void zbar_image_set_format(zbar_image_t *image,
721 unsigned long format);
722
723 /** associate a "sequence" (page/frame) number with this image.
724 * @since 0.6
725 */
726 extern void zbar_image_set_sequence(zbar_image_t *image,
727 unsigned sequence_num);
728
729 /** specify the pixel size of the image.
730 * @note this also resets the crop rectangle to the full image
731 * (0, 0, width, height)
732 * @note this does not affect the data!
733 */
734 extern void zbar_image_set_size(zbar_image_t *image,
735 unsigned width,
736 unsigned height);
737
738 /** specify a rectangular region of the image to scan.
739 * the rectangle will be clipped to the image boundaries.
740 * defaults to the full image specified by zbar_image_set_size()
741 */
742 extern void zbar_image_set_crop(zbar_image_t *image,
743 unsigned x,
744 unsigned y,
745 unsigned width,
746 unsigned height);
747
748 /** specify image sample data. when image data is no longer needed by
749 * the library the specific data cleanup handler will be called
750 * (unless NULL)
751 * @note application image data will not be modified by the library
752 */
753 extern void zbar_image_set_data(zbar_image_t *image,
754 const void *data,
755 unsigned long data_byte_length,
756 zbar_image_cleanup_handler_t *cleanup_hndlr);
757
758 /** built-in cleanup handler.
759 * passes the image data buffer to free()
760 */
761 extern void zbar_image_free_data(zbar_image_t *image);
762
763 /** associate user specified data value with an image.
764 * @since 0.5
765 */
766 extern void zbar_image_set_userdata(zbar_image_t *image,
767 void *userdata);
768
769 /** return user specified data value associated with the image.
770 * @since 0.5
771 */
772 extern void *zbar_image_get_userdata(const zbar_image_t *image);
773
774 /** dump raw image data to a file for debug.
775 * the data will be prefixed with a 16 byte header consisting of:
776 * - 4 bytes uint = 0x676d697a ("zimg")
777 * - 4 bytes format fourcc
778 * - 2 bytes width
779 * - 2 bytes height
780 * - 4 bytes size of following image data in bytes
781 * this header can be dumped w/eg:
782 * @verbatim
783 od -Ax -tx1z -N16 -w4 [file]
784 @endverbatim
785 * for some formats the image can be displayed/converted using
786 * ImageMagick, eg:
787 * @verbatim
788 display -size 640x480+16 [-depth ?] [-sampling-factor ?x?] \
789 {GRAY,RGB,UYVY,YUV}:[file]
790 @endverbatim
791 *
792 * @param image the image object to dump
793 * @param filebase base filename, appended with ".XXXX.zimg" where
794 * XXXX is the format fourcc
795 * @returns 0 on success or a system error code on failure
796 */
797 extern int zbar_image_write(const zbar_image_t *image,
798 const char *filebase);
799
800 /** read back an image in the format written by zbar_image_write()
801 * @note TBD
802 */
803 extern zbar_image_t *zbar_image_read(char *filename);
804
805 /*@}*/
806
807 /*------------------------------------------------------------*/
808 /** @name Processor interface
809 * @anchor c-processor
810 * high-level self-contained image processor.
811 * processes video and images for barcodes, optionally displaying
812 * images to a library owned output window
813 */
814 /*@{*/
815
816 struct zbar_processor_s;
817 /** opaque standalone processor object. */
818 typedef struct zbar_processor_s zbar_processor_t;
819
820 /** constructor.
821 * if threaded is set and threading is available the processor
822 * will spawn threads where appropriate to avoid blocking and
823 * improve responsiveness
824 */
825 extern zbar_processor_t *zbar_processor_create(int threaded);
826
827 /** destructor. cleans up all resources associated with the processor
828 */
829 extern void zbar_processor_destroy(zbar_processor_t *processor);
830
831 /** (re)initialization.
832 * opens a video input device and/or prepares to display output
833 */
834 extern int zbar_processor_init(zbar_processor_t *processor,
835 const char *video_device,
836 int enable_display);
837
838 /** request a preferred size for the video image from the device.
839 * the request may be adjusted or completely ignored by the driver.
840 * @note must be called before zbar_processor_init()
841 * @since 0.6
842 */
843 extern int zbar_processor_request_size(zbar_processor_t *processor,
844 unsigned width,
845 unsigned height);
846
847 /** request a preferred video driver interface version for
848 * debug/testing.
849 * @note must be called before zbar_processor_init()
850 * @since 0.6
851 */
852 extern int zbar_processor_request_interface(zbar_processor_t *processor,
853 int version);
854
855 /** request a preferred video I/O mode for debug/testing. You will
856 * get errors if the driver does not support the specified mode.
857 * @verbatim
858 0 = auto-detect
859 1 = force I/O using read()
860 2 = force memory mapped I/O using mmap()
861 3 = force USERPTR I/O (v4l2 only)
862 @endverbatim
863 * @note must be called before zbar_processor_init()
864 * @since 0.7
865 */
866 extern int zbar_processor_request_iomode(zbar_processor_t *video,
867 int iomode);
868
869 /** force specific input and output formats for debug/testing.
870 * @note must be called before zbar_processor_init()
871 */
872 extern int zbar_processor_force_format(zbar_processor_t *processor,
873 unsigned long input_format,
874 unsigned long output_format);
875
876 /** setup result handler callback.
877 * the specified function will be called by the processor whenever
878 * new results are available from the video stream or a static image.
879 * pass a NULL value to disable callbacks.
880 * @param processor the object on which to set the handler.
881 * @param handler the function to call when new results are available.
882 * @param userdata is set as with zbar_processor_set_userdata().
883 * @returns the previously registered handler
884 */
885 extern zbar_image_data_handler_t*
886 zbar_processor_set_data_handler(zbar_processor_t *processor,
887 zbar_image_data_handler_t *handler,
888 const void *userdata);
889
890 /** associate user specified data value with the processor.
891 * @since 0.6
892 */
893 extern void zbar_processor_set_userdata(zbar_processor_t *processor,
894 void *userdata);
895
896 /** return user specified data value associated with the processor.
897 * @since 0.6
898 */
899 extern void *zbar_processor_get_userdata(const zbar_processor_t *processor);
900
901 /** set config for indicated symbology (0 for all) to specified value.
902 * @returns 0 for success, non-0 for failure (config does not apply to
903 * specified symbology, or value out of range)
904 * @see zbar_decoder_set_config()
905 * @since 0.4
906 */
907 extern int zbar_processor_set_config(zbar_processor_t *processor,
908 zbar_symbol_type_t symbology,
909 zbar_config_t config,
910 int value);
911
912 /** set video control value
913 * @returns 0 for success, non-0 for failure
914 * @since 0.20
915 * @see zbar_video_set_control()
916 */
917 extern int zbar_processor_set_control (zbar_processor_t *processor,
918 const char *control_name,
919 int value);
920
921 /** get video control value
922 * @returns 0 for success, non-0 for failure
923 * @since 0.20
924 * @see zbar_video_get_control()
925 */
926 extern int zbar_processor_get_control (zbar_processor_t *processor,
927 const char *control_name,
928 int *value);
929
930 /** parse configuration string using zbar_parse_config()
931 * and apply to processor using zbar_processor_set_config().
932 * @returns 0 for success, non-0 for failure
933 * @see zbar_parse_config()
934 * @see zbar_processor_set_config()
935 * @since 0.4
936 */
zbar_processor_parse_config(zbar_processor_t * processor,const char * config_string)937 static inline int zbar_processor_parse_config (zbar_processor_t *processor,
938 const char *config_string)
939 {
940 zbar_symbol_type_t sym;
941 zbar_config_t cfg;
942 int val;
943 return(zbar_parse_config(config_string, &sym, &cfg, &val) ||
944 zbar_processor_set_config(processor, sym, cfg, val));
945 }
946
947 /** retrieve the current state of the output window.
948 * @returns 1 if the output window is currently displayed, 0 if not.
949 * @returns -1 if an error occurs
950 */
951 extern int zbar_processor_is_visible(zbar_processor_t *processor);
952
953 /** show or hide the display window owned by the library.
954 * the size will be adjusted to the input size
955 */
956 extern int zbar_processor_set_visible(zbar_processor_t *processor,
957 int visible);
958
959 /** control the processor in free running video mode.
960 * only works if video input is initialized. if threading is in use,
961 * scanning will occur in the background, otherwise this is only
962 * useful wrapping calls to zbar_processor_user_wait(). if the
963 * library output window is visible, video display will be enabled.
964 */
965 extern int zbar_processor_set_active(zbar_processor_t *processor,
966 int active);
967
968 /** retrieve decode results for last scanned image/frame.
969 * @returns the symbol set result container or NULL if no results are
970 * available
971 * @note the returned symbol set has its reference count incremented;
972 * ensure that the count is decremented after use
973 * @since 0.10
974 */
975 extern const zbar_symbol_set_t*
976 zbar_processor_get_results(const zbar_processor_t *processor);
977
978 /** wait for input to the display window from the user
979 * (via mouse or keyboard).
980 * @returns >0 when input is received, 0 if timeout ms expired
981 * with no input or -1 in case of an error
982 */
983 extern int zbar_processor_user_wait(zbar_processor_t *processor,
984 int timeout);
985
986 /** process from the video stream until a result is available,
987 * or the timeout (in milliseconds) expires.
988 * specify a timeout of -1 to scan indefinitely
989 * (zbar_processor_set_active() may still be used to abort the scan
990 * from another thread).
991 * if the library window is visible, video display will be enabled.
992 * @note that multiple results may still be returned (despite the
993 * name).
994 * @returns >0 if symbols were successfully decoded,
995 * 0 if no symbols were found (ie, the timeout expired)
996 * or -1 if an error occurs
997 */
998 extern int zbar_process_one(zbar_processor_t *processor,
999 int timeout);
1000
1001 /** process the provided image for barcodes.
1002 * if the library window is visible, the image will be displayed.
1003 * @returns >0 if symbols were successfully decoded,
1004 * 0 if no symbols were found or -1 if an error occurs
1005 */
1006 extern int zbar_process_image(zbar_processor_t *processor,
1007 zbar_image_t *image);
1008
1009 /** enable dbus IPC API.
1010 * @returns 0 successful
1011 */
1012 int zbar_processor_request_dbus(zbar_processor_t *proc,
1013 int req_dbus_enabled);
1014
1015 /** display detail for last processor error to stderr.
1016 * @returns a non-zero value suitable for passing to exit()
1017 */
1018 static inline int
zbar_processor_error_spew(const zbar_processor_t * processor,int verbosity)1019 zbar_processor_error_spew (const zbar_processor_t *processor,
1020 int verbosity)
1021 {
1022 return(_zbar_error_spew(processor, verbosity));
1023 }
1024
1025 /** retrieve the detail string for the last processor error. */
1026 static inline const char*
zbar_processor_error_string(const zbar_processor_t * processor,int verbosity)1027 zbar_processor_error_string (const zbar_processor_t *processor,
1028 int verbosity)
1029 {
1030 return(_zbar_error_string(processor, verbosity));
1031 }
1032
1033 /** retrieve the type code for the last processor error. */
1034 static inline zbar_error_t
zbar_processor_get_error_code(const zbar_processor_t * processor)1035 zbar_processor_get_error_code (const zbar_processor_t *processor)
1036 {
1037 return(_zbar_get_error_code(processor));
1038 }
1039
1040 /*@}*/
1041
1042 /*------------------------------------------------------------*/
1043 /** @name Video interface
1044 * @anchor c-video
1045 * mid-level video source abstraction.
1046 * captures images from a video device
1047 */
1048 /*@{*/
1049
1050 struct zbar_video_s;
1051 /** opaque video object. */
1052 typedef struct zbar_video_s zbar_video_t;
1053
1054 /** constructor. */
1055 extern zbar_video_t *zbar_video_create(void);
1056
1057 /** destructor. */
1058 extern void zbar_video_destroy(zbar_video_t *video);
1059
1060 /** open and probe a video device.
1061 * the device specified by platform specific unique name
1062 * (v4l device node path in *nix eg "/dev/video",
1063 * DirectShow DevicePath property in windows).
1064 * @returns 0 if successful or -1 if an error occurs
1065 */
1066 extern int zbar_video_open(zbar_video_t *video,
1067 const char *device);
1068
1069 /** retrieve file descriptor associated with open *nix video device
1070 * useful for using select()/poll() to tell when new images are
1071 * available (NB v4l2 only!!).
1072 * @returns the file descriptor or -1 if the video device is not open
1073 * or the driver only supports v4l1
1074 */
1075 extern int zbar_video_get_fd(const zbar_video_t *video);
1076
1077 /** request a preferred size for the video image from the device.
1078 * the request may be adjusted or completely ignored by the driver.
1079 * @returns 0 if successful or -1 if the video device is already
1080 * initialized
1081 * @since 0.6
1082 */
1083 extern int zbar_video_request_size(zbar_video_t *video,
1084 unsigned width,
1085 unsigned height);
1086
1087 /** request a preferred driver interface version for debug/testing.
1088 * @note must be called before zbar_video_open()
1089 * @since 0.6
1090 */
1091 extern int zbar_video_request_interface(zbar_video_t *video,
1092 int version);
1093
1094 /** request a preferred I/O mode for debug/testing. You will get
1095 * errors if the driver does not support the specified mode.
1096 * @verbatim
1097 0 = auto-detect
1098 1 = force I/O using read()
1099 2 = force memory mapped I/O using mmap()
1100 3 = force USERPTR I/O (v4l2 only)
1101 @endverbatim
1102 * @note must be called before zbar_video_open()
1103 * @since 0.7
1104 */
1105 extern int zbar_video_request_iomode(zbar_video_t *video,
1106 int iomode);
1107
1108 /** retrieve current output image width.
1109 * @returns the width or 0 if the video device is not open
1110 */
1111 extern int zbar_video_get_width(const zbar_video_t *video);
1112
1113 /** retrieve current output image height.
1114 * @returns the height or 0 if the video device is not open
1115 */
1116 extern int zbar_video_get_height(const zbar_video_t *video);
1117
1118 /** initialize video using a specific format for debug.
1119 * use zbar_negotiate_format() to automatically select and initialize
1120 * the best available format
1121 */
1122 extern int zbar_video_init(zbar_video_t *video,
1123 unsigned long format);
1124
1125 /** start/stop video capture.
1126 * all buffered images are retired when capture is disabled.
1127 * @returns 0 if successful or -1 if an error occurs
1128 */
1129 extern int zbar_video_enable(zbar_video_t *video,
1130 int enable);
1131
1132 /** retrieve next captured image. blocks until an image is available.
1133 * @returns NULL if video is not enabled or an error occurs
1134 */
1135 extern zbar_image_t *zbar_video_next_image(zbar_video_t *video);
1136
1137 /** set video control value (integer).
1138 * @returns 0 for success, non-0 for failure
1139 * @since 0.20
1140 * @see zbar_processor_set_control()
1141 */
1142 extern int zbar_video_set_control (zbar_video_t *video,
1143 const char *control_name,
1144 int value);
1145
1146
1147 /** get video control value (integer).
1148 * @returns 0 for success, non-0 for failure
1149 * @since 0.20
1150 * @see zbar_processor_get_control()
1151 */
1152 extern int zbar_video_get_control (zbar_video_t *video,
1153 const char *control_name,
1154 int *value);
1155
1156 /** get available controls from video source
1157 * @returns 0 for success, non-0 for failure
1158 * @since 0.20
1159 */
1160 extern struct video_controls_s
1161 *zbar_video_get_controls (const zbar_video_t *video,
1162 int index);
1163
1164 /** get available video resolutions from video source
1165 * @returns 0 for success, non-0 for failure
1166 * @since 0.22
1167 */
1168 extern struct video_resolution_s
1169 *zbar_video_get_resolutions (const zbar_video_t *vdo,
1170 int index);
1171
1172 /** display detail for last video error to stderr.
1173 * @returns a non-zero value suitable for passing to exit()
1174 */
zbar_video_error_spew(const zbar_video_t * video,int verbosity)1175 static inline int zbar_video_error_spew (const zbar_video_t *video,
1176 int verbosity)
1177 {
1178 return(_zbar_error_spew(video, verbosity));
1179 }
1180
1181 /** retrieve the detail string for the last video error. */
zbar_video_error_string(const zbar_video_t * video,int verbosity)1182 static inline const char *zbar_video_error_string (const zbar_video_t *video,
1183 int verbosity)
1184 {
1185 return(_zbar_error_string(video, verbosity));
1186 }
1187
1188 /** retrieve the type code for the last video error. */
1189 static inline zbar_error_t
zbar_video_get_error_code(const zbar_video_t * video)1190 zbar_video_get_error_code (const zbar_video_t *video)
1191 {
1192 return(_zbar_get_error_code(video));
1193 }
1194
1195 /*@}*/
1196
1197 /*------------------------------------------------------------*/
1198 /** @name Window interface
1199 * @anchor c-window
1200 * mid-level output window abstraction.
1201 * displays images to user-specified platform specific output window
1202 */
1203 /*@{*/
1204
1205 struct zbar_window_s;
1206 /** opaque window object. */
1207 typedef struct zbar_window_s zbar_window_t;
1208
1209 /** constructor. */
1210 extern zbar_window_t *zbar_window_create(void);
1211
1212 /** destructor. */
1213 extern void zbar_window_destroy(zbar_window_t *window);
1214
1215 /** associate reader with an existing platform window.
1216 * This can be any "Drawable" for X Windows or a "HWND" for windows.
1217 * input images will be scaled into the output window.
1218 * pass NULL to detach from the resource, further input will be
1219 * ignored
1220 */
1221 extern int zbar_window_attach(zbar_window_t *window,
1222 void *x11_display_w32_hwnd,
1223 unsigned long x11_drawable);
1224
1225 /** control content level of the reader overlay.
1226 * the overlay displays graphical data for informational or debug
1227 * purposes. higher values increase the level of annotation (possibly
1228 * decreasing performance). @verbatim
1229 0 = disable overlay
1230 1 = outline decoded symbols (default)
1231 2 = also track and display input frame rate
1232 @endverbatim
1233 */
1234 extern void zbar_window_set_overlay(zbar_window_t *window,
1235 int level);
1236
1237 /** retrieve current content level of reader overlay.
1238 * @see zbar_window_set_overlay()
1239 * @since 0.10
1240 */
1241 extern int zbar_window_get_overlay(const zbar_window_t *window);
1242
1243 /** draw a new image into the output window. */
1244 extern int zbar_window_draw(zbar_window_t *window,
1245 zbar_image_t *image);
1246
1247 /** redraw the last image (exposure handler). */
1248 extern int zbar_window_redraw(zbar_window_t *window);
1249
1250 /** resize the image window (reconfigure handler).
1251 * this does @em not update the contents of the window
1252 * @since 0.3, changed in 0.4 to not redraw window
1253 */
1254 extern int zbar_window_resize(zbar_window_t *window,
1255 unsigned width,
1256 unsigned height);
1257
1258 /** display detail for last window error to stderr.
1259 * @returns a non-zero value suitable for passing to exit()
1260 */
zbar_window_error_spew(const zbar_window_t * window,int verbosity)1261 static inline int zbar_window_error_spew (const zbar_window_t *window,
1262 int verbosity)
1263 {
1264 return(_zbar_error_spew(window, verbosity));
1265 }
1266
1267 /** retrieve the detail string for the last window error. */
1268 static inline const char*
zbar_window_error_string(const zbar_window_t * window,int verbosity)1269 zbar_window_error_string (const zbar_window_t *window,
1270 int verbosity)
1271 {
1272 return(_zbar_error_string(window, verbosity));
1273 }
1274
1275 /** retrieve the type code for the last window error. */
1276 static inline zbar_error_t
zbar_window_get_error_code(const zbar_window_t * window)1277 zbar_window_get_error_code (const zbar_window_t *window)
1278 {
1279 return(_zbar_get_error_code(window));
1280 }
1281
1282
1283 /** select a compatible format between video input and output window.
1284 * the selection algorithm attempts to use a format shared by
1285 * video input and window output which is also most useful for
1286 * barcode scanning. if a format conversion is necessary, it will
1287 * heuristically attempt to minimize the cost of the conversion
1288 */
1289 extern int zbar_negotiate_format(zbar_video_t *video,
1290 zbar_window_t *window);
1291
1292 /*@}*/
1293
1294 /*------------------------------------------------------------*/
1295 /** @name Image Scanner interface
1296 * @anchor c-imagescanner
1297 * mid-level image scanner interface.
1298 * reads barcodes from 2-D images
1299 */
1300 /*@{*/
1301
1302 struct zbar_image_scanner_s;
1303 /** opaque image scanner object. */
1304 typedef struct zbar_image_scanner_s zbar_image_scanner_t;
1305
1306 /** constructor. */
1307 extern zbar_image_scanner_t *zbar_image_scanner_create(void);
1308
1309 /** destructor. */
1310 extern void zbar_image_scanner_destroy(zbar_image_scanner_t *scanner);
1311
1312 /** setup result handler callback.
1313 * the specified function will be called by the scanner whenever
1314 * new results are available from a decoded image.
1315 * pass a NULL value to disable callbacks.
1316 * @returns the previously registered handler
1317 */
1318 extern zbar_image_data_handler_t*
1319 zbar_image_scanner_set_data_handler(zbar_image_scanner_t *scanner,
1320 zbar_image_data_handler_t *handler,
1321 const void *userdata);
1322
1323
1324 /** request sending decoded codes via D-Bus
1325 * @see zbar_processor_parse_config()
1326 * @since 0.21
1327 */
1328 extern int zbar_image_scanner_request_dbus(zbar_image_scanner_t *scanner,
1329 int req_dbus_enabled);
1330
1331 /** set config for indicated symbology (0 for all) to specified value.
1332 * @returns 0 for success, non-0 for failure (config does not apply to
1333 * specified symbology, or value out of range)
1334 * @see zbar_decoder_set_config()
1335 * @since 0.4
1336 */
1337 extern int zbar_image_scanner_set_config(zbar_image_scanner_t *scanner,
1338 zbar_symbol_type_t symbology,
1339 zbar_config_t config,
1340 int value);
1341
1342 /** get config for indicated symbology
1343 * @returns 0 for success, non-0 for failure (config does not apply to
1344 * specified symbology, or value out of range). On success, *value is filled.
1345 * @since 0.22
1346 */
1347 extern int zbar_image_scanner_get_config(zbar_image_scanner_t *scanner,
1348 zbar_symbol_type_t symbology,
1349 zbar_config_t config,
1350 int *value);
1351
1352 /** parse configuration string using zbar_parse_config()
1353 * and apply to image scanner using zbar_image_scanner_set_config().
1354 * @returns 0 for success, non-0 for failure
1355 * @see zbar_parse_config()
1356 * @see zbar_image_scanner_set_config()
1357 * @since 0.4
1358 */
1359 static inline int
zbar_image_scanner_parse_config(zbar_image_scanner_t * scanner,const char * config_string)1360 zbar_image_scanner_parse_config (zbar_image_scanner_t *scanner,
1361 const char *config_string)
1362 {
1363 zbar_symbol_type_t sym;
1364 zbar_config_t cfg;
1365 int val;
1366 return(zbar_parse_config(config_string, &sym, &cfg, &val) ||
1367 zbar_image_scanner_set_config(scanner, sym, cfg, val));
1368 }
1369
1370 /** enable or disable the inter-image result cache (default disabled).
1371 * mostly useful for scanning video frames, the cache filters
1372 * duplicate results from consecutive images, while adding some
1373 * consistency checking and hysteresis to the results.
1374 * this interface also clears the cache
1375 */
1376 extern void zbar_image_scanner_enable_cache(zbar_image_scanner_t *scanner,
1377 int enable);
1378
1379 /** remove any previously decoded results from the image scanner and the
1380 * specified image. somewhat more efficient version of
1381 * zbar_image_set_symbols(image, NULL) which may retain memory for
1382 * subsequent decodes
1383 * @since 0.10
1384 */
1385 extern void zbar_image_scanner_recycle_image(zbar_image_scanner_t *scanner,
1386 zbar_image_t *image);
1387
1388 /** retrieve decode results for last scanned image.
1389 * @returns the symbol set result container or NULL if no results are
1390 * available
1391 * @note the symbol set does not have its reference count adjusted;
1392 * ensure that the count is incremented if the results may be kept
1393 * after the next image is scanned
1394 * @since 0.10
1395 */
1396 extern const zbar_symbol_set_t*
1397 zbar_image_scanner_get_results(const zbar_image_scanner_t *scanner);
1398
1399 /** scan for symbols in provided image. The image format must be
1400 * "Y800" or "GRAY".
1401 * @returns >0 if symbols were successfully decoded from the image,
1402 * 0 if no symbols were found or -1 if an error occurs
1403 * @see zbar_image_convert()
1404 * @since 0.9 - changed to only accept grayscale images
1405 */
1406 extern int zbar_scan_image(zbar_image_scanner_t *scanner,
1407 zbar_image_t *image);
1408
1409 /*@}*/
1410
1411 /*------------------------------------------------------------*/
1412 /** @name Decoder interface
1413 * @anchor c-decoder
1414 * low-level bar width stream decoder interface.
1415 * identifies symbols and extracts encoded data
1416 */
1417 /*@{*/
1418
1419 struct zbar_decoder_s;
1420 /** opaque decoder object. */
1421 typedef struct zbar_decoder_s zbar_decoder_t;
1422
1423 /** decoder data handler callback function.
1424 * called by decoder when new data has just been decoded
1425 */
1426 typedef void (zbar_decoder_handler_t)(zbar_decoder_t *decoder);
1427
1428 /** constructor. */
1429 extern zbar_decoder_t *zbar_decoder_create(void);
1430
1431 /** destructor. */
1432 extern void zbar_decoder_destroy(zbar_decoder_t *decoder);
1433
1434 /** set config for indicated symbology (0 for all) to specified value.
1435 * @returns 0 for success, non-0 for failure (config does not apply to
1436 * specified symbology, or value out of range)
1437 * @since 0.4
1438 */
1439 extern int zbar_decoder_set_config(zbar_decoder_t *decoder,
1440 zbar_symbol_type_t symbology,
1441 zbar_config_t config,
1442 int value);
1443
1444
1445 /** get config for indicated symbology
1446 * @returns 0 for success, non-0 for failure (config does not apply to
1447 * specified symbology, or value out of range). On success, *value is filled.
1448 * @since 0.22
1449 */
1450 extern int zbar_decoder_get_config(zbar_decoder_t *decoder,
1451 zbar_symbol_type_t symbology,
1452 zbar_config_t config,
1453 int *value);
1454
1455 /** parse configuration string using zbar_parse_config()
1456 * and apply to decoder using zbar_decoder_set_config().
1457 * @returns 0 for success, non-0 for failure
1458 * @see zbar_parse_config()
1459 * @see zbar_decoder_set_config()
1460 * @since 0.4
1461 */
zbar_decoder_parse_config(zbar_decoder_t * decoder,const char * config_string)1462 static inline int zbar_decoder_parse_config (zbar_decoder_t *decoder,
1463 const char *config_string)
1464 {
1465 zbar_symbol_type_t sym;
1466 zbar_config_t cfg;
1467 int val;
1468 return(zbar_parse_config(config_string, &sym, &cfg, &val) ||
1469 zbar_decoder_set_config(decoder, sym, cfg, val));
1470 }
1471
1472 /** retrieve symbology boolean config settings.
1473 * @returns a bitmask indicating which configs are currently set for the
1474 * specified symbology.
1475 * @since 0.11
1476 */
1477 extern unsigned int zbar_decoder_get_configs(const zbar_decoder_t *decoder,
1478 zbar_symbol_type_t symbology);
1479
1480 /** clear all decoder state.
1481 * any partial symbols are flushed
1482 */
1483 extern void zbar_decoder_reset(zbar_decoder_t *decoder);
1484
1485 /** mark start of a new scan pass.
1486 * clears any intra-symbol state and resets color to ::ZBAR_SPACE.
1487 * any partially decoded symbol state is retained
1488 */
1489 extern void zbar_decoder_new_scan(zbar_decoder_t *decoder);
1490
1491 /** process next bar/space width from input stream.
1492 * the width is in arbitrary relative units. first value of a scan
1493 * is ::ZBAR_SPACE width, alternating from there.
1494 * @returns appropriate symbol type if width completes
1495 * decode of a symbol (data is available for retrieval)
1496 * @returns ::ZBAR_PARTIAL as a hint if part of a symbol was decoded
1497 * @returns ::ZBAR_NONE (0) if no new symbol data is available
1498 */
1499 extern zbar_symbol_type_t zbar_decode_width(zbar_decoder_t *decoder,
1500 unsigned width);
1501
1502 /** retrieve color of @em next element passed to
1503 * zbar_decode_width(). */
1504 extern zbar_color_t zbar_decoder_get_color(const zbar_decoder_t *decoder);
1505
1506 /** retrieve last decoded data.
1507 * @returns the data string or NULL if no new data available.
1508 * the returned data buffer is owned by library, contents are only
1509 * valid between non-0 return from zbar_decode_width and next library
1510 * call
1511 */
1512 extern const char *zbar_decoder_get_data(const zbar_decoder_t *decoder);
1513
1514 /** retrieve length of binary data.
1515 * @returns the length of the decoded data or 0 if no new data
1516 * available.
1517 */
1518 extern unsigned int
1519 zbar_decoder_get_data_length(const zbar_decoder_t *decoder);
1520
1521 /** retrieve last decoded symbol type.
1522 * @returns the type or ::ZBAR_NONE if no new data available
1523 */
1524 extern zbar_symbol_type_t
1525 zbar_decoder_get_type(const zbar_decoder_t *decoder);
1526
1527 /** retrieve modifier flags for the last decoded symbol.
1528 * @returns a bitmask indicating which characteristics were detected
1529 * during decoding.
1530 * @since 0.11
1531 */
1532 extern unsigned int zbar_decoder_get_modifiers(const zbar_decoder_t *decoder);
1533
1534 /** retrieve last decode direction.
1535 * @returns 1 for forward and -1 for reverse
1536 * @returns 0 if the decode direction is unknown or does not apply
1537 * @since 0.11
1538 */
1539 extern int zbar_decoder_get_direction(const zbar_decoder_t *decoder);
1540
1541 /** setup data handler callback.
1542 * the registered function will be called by the decoder
1543 * just before zbar_decode_width() returns a non-zero value.
1544 * pass a NULL value to disable callbacks.
1545 * @returns the previously registered handler
1546 */
1547 extern zbar_decoder_handler_t*
1548 zbar_decoder_set_handler(zbar_decoder_t *decoder,
1549 zbar_decoder_handler_t *handler);
1550
1551 /** associate user specified data value with the decoder. */
1552 extern void zbar_decoder_set_userdata(zbar_decoder_t *decoder,
1553 void *userdata);
1554
1555 /** return user specified data value associated with the decoder. */
1556 extern void *zbar_decoder_get_userdata(const zbar_decoder_t *decoder);
1557
1558 /*@}*/
1559
1560 /*------------------------------------------------------------*/
1561 /** @name Scanner interface
1562 * @anchor c-scanner
1563 * low-level linear intensity sample stream scanner interface.
1564 * identifies "bar" edges and measures width between them.
1565 * optionally passes to bar width decoder
1566 */
1567 /*@{*/
1568
1569 struct zbar_scanner_s;
1570 /** opaque scanner object. */
1571 typedef struct zbar_scanner_s zbar_scanner_t;
1572
1573 /** constructor.
1574 * if decoder is non-NULL it will be attached to scanner
1575 * and called automatically at each new edge
1576 * current color is initialized to ::ZBAR_SPACE
1577 * (so an initial BAR->SPACE transition may be discarded)
1578 */
1579 extern zbar_scanner_t *zbar_scanner_create(zbar_decoder_t *decoder);
1580
1581 /** destructor. */
1582 extern void zbar_scanner_destroy(zbar_scanner_t *scanner);
1583
1584 /** clear all scanner state.
1585 * also resets an associated decoder
1586 */
1587 extern zbar_symbol_type_t zbar_scanner_reset(zbar_scanner_t *scanner);
1588
1589 /** mark start of a new scan pass. resets color to ::ZBAR_SPACE.
1590 * also updates an associated decoder.
1591 * @returns any decode results flushed from the pipeline
1592 * @note when not using callback handlers, the return value should
1593 * be checked the same as zbar_scan_y()
1594 * @note call zbar_scanner_flush() at least twice before calling this
1595 * method to ensure no decode results are lost
1596 */
1597 extern zbar_symbol_type_t zbar_scanner_new_scan(zbar_scanner_t *scanner);
1598
1599 /** flush scanner processing pipeline.
1600 * forces current scanner position to be a scan boundary.
1601 * call multiple times (max 3) to completely flush decoder.
1602 * @returns any decode/scan results flushed from the pipeline
1603 * @note when not using callback handlers, the return value should
1604 * be checked the same as zbar_scan_y()
1605 * @since 0.9
1606 */
1607 extern zbar_symbol_type_t zbar_scanner_flush(zbar_scanner_t *scanner);
1608
1609 /** process next sample intensity value.
1610 * intensity (y) is in arbitrary relative units.
1611 * @returns result of zbar_decode_width() if a decoder is attached,
1612 * otherwise @returns (::ZBAR_PARTIAL) when new edge is detected
1613 * or 0 (::ZBAR_NONE) if no new edge is detected
1614 */
1615 extern zbar_symbol_type_t zbar_scan_y(zbar_scanner_t *scanner,
1616 int y);
1617
1618 /** process next sample from RGB (or BGR) triple. */
zbar_scan_rgb24(zbar_scanner_t * scanner,unsigned char * rgb)1619 static inline zbar_symbol_type_t zbar_scan_rgb24 (zbar_scanner_t *scanner,
1620 unsigned char *rgb)
1621 {
1622 return(zbar_scan_y(scanner, rgb[0] + rgb[1] + rgb[2]));
1623 }
1624
1625 /** retrieve last scanned width. */
1626 extern unsigned zbar_scanner_get_width(const zbar_scanner_t *scanner);
1627
1628 /** retrieve sample position of last edge.
1629 * @since 0.10
1630 */
1631 extern unsigned zbar_scanner_get_edge(const zbar_scanner_t *scn,
1632 unsigned offset,
1633 int prec);
1634
1635 /** retrieve last scanned color. */
1636 extern zbar_color_t zbar_scanner_get_color(const zbar_scanner_t *scanner);
1637
1638 /*@}*/
1639
1640 #ifdef __cplusplus
1641 }
1642 }
1643
1644 # include "zbar/Exception.h"
1645 # include "zbar/Decoder.h"
1646 # include "zbar/Scanner.h"
1647 # include "zbar/Symbol.h"
1648 # include "zbar/Image.h"
1649 # include "zbar/ImageScanner.h"
1650 # include "zbar/Video.h"
1651 # include "zbar/Window.h"
1652 # include "zbar/Processor.h"
1653 #endif
1654
1655 #endif
1656