zbar Namespace Reference

"color" of element: bar or space.

decoder configuration options.

Since:

0.4

decoder data handler callback function.

called by decoder when new data has just been decoded

Definition at line 1116 of file zbar.h.

opaque decoder object.

Definition at line 1111 of file zbar.h.

error codes.

cleanup handler callback function.

called to free sample data when an image is destroyed.

Definition at line 376 of file zbar.h.

data handler callback function.

called when decoded symbol results are available for an image

Definition at line 381 of file zbar.h.

opaque image scanner object.

Definition at line 1011 of file zbar.h.

opaque image object.

Definition at line 371 of file zbar.h.

opaque standalone processor object.

Definition at line 584 of file zbar.h.

opaque scanner object.

Definition at line 1228 of file zbar.h.

opaque symbol iterator object.

Since:

0.10

Definition at line 200 of file zbar.h.

opaque decoded symbol object.

Definition at line 197 of file zbar.h.

decoded symbol type.

opaque video object.

Definition at line 794 of file zbar.h.

opaque window object.

Definition at line 914 of file zbar.h.

"color" of element: bar or space.

Enumerator:

ZBAR_SPACE	light area or space between bars
ZBAR_BAR	dark area or colored bar segment

Definition at line 80 of file zbar.h.

decoder configuration options.

Since:

0.4

Enumerator:

ZBAR_CFG_ENABLE	enable symbology/feature
ZBAR_CFG_ADD_CHECK	enable check digit when optional
ZBAR_CFG_EMIT_CHECK	return check digit when present
ZBAR_CFG_ASCII	enable full ASCII character set
ZBAR_CFG_NUM	number of boolean decoder configs
ZBAR_CFG_MIN_LEN	minimum data length for valid decode
ZBAR_CFG_MAX_LEN	maximum data length for valid decode
ZBAR_CFG_POSITION	enable scanner to collect position data
ZBAR_CFG_X_DENSITY	image scanner vertical scan density
ZBAR_CFG_Y_DENSITY	image scanner horizontal scan density

Definition at line 126 of file zbar.h.

error codes.

Enumerator:

ZBAR_OK	no error
ZBAR_ERR_NOMEM	out of memory
ZBAR_ERR_INTERNAL	internal library error
ZBAR_ERR_UNSUPPORTED	unsupported request
ZBAR_ERR_INVALID	invalid request
ZBAR_ERR_SYSTEM	system error
ZBAR_ERR_LOCKING	locking error
ZBAR_ERR_BUSY	all resources busy
ZBAR_ERR_XDISPLAY	X11 display error.
ZBAR_ERR_XPROTO	X11 protocol error.
ZBAR_ERR_CLOSED	output window is closed
ZBAR_ERR_WINAPI	windows system error
ZBAR_ERR_NUM	number of error codes

Definition at line 107 of file zbar.h.

decoded symbol type.

Enumerator:

ZBAR_NONE	no symbol decoded
ZBAR_PARTIAL	intermediate status
ZBAR_EAN8	EAN-8.
ZBAR_UPCE	UPC-E.
ZBAR_ISBN10	ISBN-10 (from EAN-13). Since: 0.4
ZBAR_UPCA	UPC-A.
ZBAR_EAN13	EAN-13.
ZBAR_ISBN13	ISBN-13 (from EAN-13). Since: 0.4
ZBAR_I25	Interleaved 2 of 5. Since: 0.4
ZBAR_CODE39	Code 39. Since: 0.4
ZBAR_PDF417	PDF417. Since: 0.6
ZBAR_QRCODE	QR Code. Since: 0.10
ZBAR_CODE128	Code 128.
ZBAR_SYMBOL	mask for base symbol type
ZBAR_ADDON2	2-digit add-on flag
ZBAR_ADDON5	5-digit add-on flag
ZBAR_ADDON	add-on flag mask

Definition at line 86 of file zbar.h.

process next bar/space width from input stream.

the width is in arbitrary relative units. first value of a scan is ZBAR_SPACE width, alternating from there.

Returns:

appropriate symbol type if width completes decode of a symbol (data is available for retrieval)

ZBAR_PARTIAL as a hint if part of a symbol was decoded

ZBAR_NONE (0) if no new symbol data is available

constructor.

Definition at line 40 of file decoder.c.

destructor.

retrieve color of next element passed to zbar_decode_width().

retrieve last decoded data.

Returns:

the data string or NULL if no new data available. the returned data buffer is owned by library, contents are only valid between non-0 return from zbar_decode_width and next library call

retrieve length of binary data.

Returns:

the length of the decoded data or 0 if no new data available.

retrieve last decoded symbol type.

Returns:

the type or ZBAR_NONE if no new data available

return user specified data value associated with the decoder.

mark start of a new scan pass.

clears any intra-symbol state and resets color to ZBAR_SPACE. any partially decoded symbol state is retained

parse configuration string using zbar_parse_config() and apply to decoder using zbar_decoder_set_config().

Returns:

0 for success, non-0 for failure

See also:

zbar_parse_config()

zbar_decoder_set_config()

Since:

0.4

Definition at line 1141 of file zbar.h.

clear all decoder state.

any partial symbols are flushed

set config for indicated symbology (0 for all) to specified value.

Returns:

0 for success, non-0 for failure (config does not apply to specified symbology, or value out of range)

Since:

0.4

setup data handler callback.

the registered function will be called by the decoder just before zbar_decode_width() returns a non-zero value. pass a NULL value to disable callbacks.

Returns:

the previously registered handler

associate user specified data value with the decoder.

retrieve string name for addon encoding.

Parameters:

sym	symbol type encoding

Returns:

static string name for any addon, or the empty string if no addons were decoded

retrieve string name for symbol encoding.

Parameters:

sym	symbol type encoding

Returns:

the static string name for the specified symbol type, or "UNKNOWN" if the encoding is not recognized

image format conversion.

refer to the documentation for supported image formats

Returns:

a new image with the sample data from the original image converted to the requested format. the original image is unaffected.

Note:

the converted image size may be rounded (up) due to format constraints

image format conversion with crop/pad.

if the requested size is larger than the image, the last row/column are duplicated to cover the difference. if the requested size is smaller than the image, the extra rows/columns are dropped from the right/bottom.

Returns:

a new image with the sample data from the original image converted to the requested format and size.

Note:

the image is not scaled

See also:

zbar_image_convert()

Since:

0.4

new image constructor.

Returns:

a new image object with uninitialized data and format. this image should be destroyed (using zbar_image_destroy()) as soon as the application is finished with it

Definition at line 28 of file image.c.

image destructor.

all images created by or returned to the application should be destroyed using this function. when an image is destroyed, the associated data cleanup handler will be invoked if available

Note:

make no assumptions about the image or the data buffer. they may not be destroyed/cleaned immediately if the library is still using them. if necessary, use the cleanup handler hook to keep track of image data buffers

image_scanner decode result iterator.

Returns:

the first decoded symbol result for an image or NULL if no results are available

built-in cleanup handler.

passes the image data buffer to free()

return the image sample data.

the returned data buffer is only valid until zbar_image_destroy() is called

return the size of image data.

Since:

0.6

retrieve the image format.

Returns:

the fourcc describing the format of the image sample data

retrieve the height of the image.

Returns:

the height in sample rows

retrieve a "sequence" (page/frame) number associated with this image.

Since:

0.6

retrieve the decoded results.

Returns:

the (possibly empty) set of decoded symbols

NULL if the image has not been scanned

Since:

0.10

return user specified data value associated with the image.

Since:

0.5

retrieve the width of the image.

Returns:

the width in sample columns

read back an image in the format written by zbar_image_write()

Note:

TBD

image reference count manipulation.

increment the reference count when you store a new reference to the image. decrement when the reference is no longer used. do not refer to the image any longer once the count is decremented. zbar_image_ref(image, -1) is the same as zbar_image_destroy(image)

Since:

0.5

constructor.

Definition at line 453 of file img_scanner.c.

destructor.

enable or disable the inter-image result cache (default disabled).

mostly useful for scanning video frames, the cache filters duplicate results from consecutive images, while adding some consistency checking and hysteresis to the results. this interface also clears the cache

retrieve decode results for last scanned image.

Returns:

the symbol set result container or NULL if no results are available

Note:

the symbol set does not have its reference count adjusted; ensure that the count is incremented if the results may be kept after the next image is scanned

Since:

0.10

parse configuration string using zbar_parse_config() and apply to image scanner using zbar_image_scanner_set_config().

Returns:

0 for success, non-0 for failure

See also:

zbar_parse_config()

zbar_image_scanner_set_config()

Since:

0.4

Definition at line 1050 of file zbar.h.

remove any previously decoded results from the image scanner and the specified image.

somewhat more efficient version of zbar_image_set_symbols(image, NULL) which may retain memory for subsequent decodes

Since:

0.10

set config for indicated symbology (0 for all) to specified value.

Returns:

0 for success, non-0 for failure (config does not apply to specified symbology, or value out of range)

See also:

zbar_decoder_set_config()

Since:

0.4

setup result handler callback.

the specified function will be called by the scanner whenever new results are available from a decoded image. pass a NULL value to disable callbacks.

Returns:

the previously registered handler

specify image sample data.

when image data is no longer needed by the library the specific data cleanup handler will be called (unless NULL)

Note:

application image data will not be modified by the library

specify the fourcc image format code for image sample data.

refer to the documentation for supported formats.

Note:

this does not convert the data! (see zbar_image_convert() for that)

associate a "sequence" (page/frame) number with this image.

Since:

0.6

specify the pixel size of the image.

Note:

this does not affect the data!

associate the specified symbol set with the image, replacing any existing results.

use NULL to release the current results from the image.

See also:

zbar_image_scanner_recycle_image()

Since:

0.10

associate user specified data value with an image.

Since:

0.5

dump raw image data to a file for debug.

the data will be prefixed with a 16 byte header consisting of:

• 4 bytes uint = 0x676d697a ("zimg")
• 4 bytes format fourcc
• 2 bytes width
• 2 bytes height
• 4 bytes size of following image data in bytes this header can be dumped w/eg:

         od -Ax -tx1z -N16 -w4 [file]
  

  for some formats the image can be displayed/converted using ImageMagick, eg:

         display -size 640x480+16 [-depth ?] [-sampling-factor ?x?] \
             {GRAY,RGB,UYVY,YUV}:[file]
  

Parameters:

image	the image object to dump
filebase	base filename, appended with ".XXXX.zimg" where XXXX is the format fourcc

Returns:

0 on success or a system error code on failure

increase global library debug level.

eg, for -vvvv

Definition at line 71 of file error.c.

select a compatible format between video input and output window.

the selection algorithm attempts to use a format shared by video input and window output which is also most useful for barcode scanning. if a format conversion is necessary, it will heuristically attempt to minimize the cost of the conversion

parse a configuration string of the form "[symbology.]config[=value]".

the config must match one of the recognized names. the symbology, if present, must match one of the recognized names. if symbology is unspecified, it will be set to 0. if value is unspecified it will be set to 1.

Returns:

0 if the config is parsed successfully, 1 otherwise

Since:

0.4

process the provided image for barcodes.

if the library window is visible, the image will be displayed.

Returns:

>0 if symbols were successfully decoded, 0 if no symbols were found or -1 if an error occurs

process from the video stream until a result is available, or the timeout (in milliseconds) expires.

specify a timeout of -1 to scan indefinitely (zbar_processor_set_active() may still be used to abort the scan from another thread). if the library window is visible, video display will be enabled.

Note:

that multiple results may still be returned (despite the name).

Returns:

>0 if symbols were successfully decoded, 0 if no symbols were found (ie, the timeout expired) or -1 if an error occurs

constructor.

if threaded is set and threading is available the processor will spawn threads where appropriate to avoid blocking and improve responsiveness

destructor.

cleans up all resources associated with the processor

display detail for last processor error to stderr.

Returns:

a non-zero value suitable for passing to exit()

Definition at line 761 of file zbar.h.

retrieve the detail string for the last processor error.

Definition at line 769 of file zbar.h.

force specific input and output formats for debug/testing.

Note:

must be called before zbar_processor_init()

retrieve the type code for the last processor error.

Definition at line 777 of file zbar.h.

retrieve decode results for last scanned image/frame.

Returns:

the symbol set result container or NULL if no results are available

Note:

the returned symbol set has its reference count incremented; ensure that the count is decremented after use

Since:

0.10

return user specified data value associated with the processor.

Since:

0.6

(re)initialization.

opens a video input device and/or prepares to display output

retrieve the current state of the ouput window.

Returns:

1 if the output window is currently displayed, 0 if not.

-1 if an error occurs

parse configuration string using zbar_parse_config() and apply to processor using zbar_processor_set_config().

Returns:

0 for success, non-0 for failure

See also:

zbar_parse_config()

zbar_processor_set_config()

Since:

0.4

Definition at line 685 of file zbar.h.

request a preferred video driver interface version for debug/testing.

Note:

must be called before zbar_processor_init()

Since:

0.6

request a preferred video I/O mode for debug/testing.

You will get errors if the driver does not support the specified mode.

    0 = auto-detect
    1 = force I/O using read()
    2 = force memory mapped I/O using mmap()
    3 = force USERPTR I/O (v4l2 only)

Note:

must be called before zbar_processor_init()

Since:

0.7

request a preferred size for the video image from the device.

the request may be adjusted or completely ignored by the driver.

Note:

must be called before zbar_processor_init()

Since:

0.6

control the processor in free running video mode.

only works if video input is initialized. if threading is in use, scanning will occur in the background, otherwise this is only useful wrapping calls to zbar_processor_user_wait(). if the library output window is visible, video display will be enabled.

set config for indicated symbology (0 for all) to specified value.

Returns:

0 for success, non-0 for failure (config does not apply to specified symbology, or value out of range)

See also:

zbar_decoder_set_config()

Since:

0.4

setup result handler callback.

the specified function will be called by the processor whenever new results are available from the video stream or a static image. pass a NULL value to disable callbacks.

Parameters:

processor	the object on which to set the handler.
handler	the function to call when new results are available.
userdata	is set as with zbar_processor_set_userdata().

Returns:

the previously registered handler

associate user specified data value with the processor.

Since:

0.6

show or hide the display window owned by the library.

the size will be adjusted to the input size

wait for input to the display window from the user (via mouse or keyboard).

Returns:

>0 when input is received, 0 if timeout ms expired with no input or -1 in case of an error

scan for symbols in provided image.

The image format must be "Y800" or "GRAY".

Returns:

>0 if symbols were successfully decoded from the image, 0 if no symbols were found or -1 if an error occurs

See also:

zbar_image_convert()

Since:

0.9 - changed to only accept grayscale images

process next sample from RGB (or BGR) triple.

Definition at line 1276 of file zbar.h.

process next sample intensity value.

intensity (y) is in arbitrary relative units.

Returns:

result of zbar_decode_width() if a decoder is attached, otherwise

(ZBAR_PARTIAL) when new edge is detected or 0 (ZBAR_NONE) if no new edge is detected

constructor.

if decoder is non-NULL it will be attached to scanner and called automatically at each new edge current color is initialized to ZBAR_SPACE (so an initial BAR->SPACE transition may be discarded)

destructor.

flush scanner processing pipeline.

forces current scanner position to be a scan boundary. call multiple times (max 3) to completely flush decoder.

Returns:

any decode/scan results flushed from the pipeline

Note:

when not using callback handlers, the return value should be checked the same as zbar_scan_y()

Since:

0.9

retrieve last scanned color.

retrieve sample position of last edge.

Since:

0.10

retrieve last scanned width.

mark start of a new scan pass.

resets color to ZBAR_SPACE. also updates an associated decoder.

Returns:

any decode results flushed from the pipeline

Note:

when not using callback handlers, the return value should be checked the same as zbar_scan_y()

call zbar_scanner_flush() at least twice before calling this method to ensure no decode results are lost

clear all scanner state.

also resets an associated decoder

set global library debug level.

Parameters:

verbosity

desired debug level. higher values create more spew

Definition at line 66 of file error.c.

iterate components of a composite result.

Returns:

the first physical component symbol of a composite result

NULL if the symbol is already a physical symbol

Since:

0.10

retrieve components of a composite result.

Returns:

the symbol set containing the components

NULL if the symbol is already a physical symbol

Since:

0.10

retrieve current cache count.

when the cache is enabled for the image_scanner this provides inter-frame reliability and redundancy information for video streams.

Returns:

< 0 if symbol is still uncertain.

0 if symbol is newly verified.

> 0 for duplicate symbols

retrieve data decoded from symbol.

Returns:

the data string

retrieve length of binary data.

Returns:

the length of the decoded data

retrieve the number of points in the location polygon.

the location polygon defines the image area that the symbol was extracted from.

Returns:

the number of points in the location polygon

Note:

this is currently not a polygon, but the scan locations where the symbol was decoded

retrieve location polygon x-coordinates.

points are specified by 0-based index.

Returns:

the x-coordinate for a point in the location polygon.

-1 if index is out of range

retrieve location polygon y-coordinates.

points are specified by 0-based index.

Returns:

the y-coordinate for a point in the location polygon.

-1 if index is out of range

retrieve a symbol confidence metric.

Returns:

an unscaled, relative quantity: larger values are better than smaller values, where "large" and "small" are application dependent.

Note:

expect the exact definition of this quantity to change as the metric is refined. currently, only the ordered relationship between two values is defined and will remain stable in the future

Since:

0.9

retrieve type of decoded symbol.

Returns:

the symbol type

iterate the set to which this symbol belongs (there can be only one).

Returns:

the next symbol in the set, or

NULL when no more results are available

symbol reference count manipulation.

increment the reference count when you store a new reference to the symbol. decrement when the reference is no longer used. do not refer to the symbol once the count is decremented and the containing image has been recycled or destroyed.

Note:

the containing image holds a reference to the symbol, so you only need to use this if you keep a symbol after the image has been destroyed or reused.

Since:

0.9

set iterator.

Returns:

the first decoded symbol result in a set

NULL if the set is empty

Since:

0.10

retrieve set size.

Returns:

the number of symbols in the set.

Since:

0.10

reference count manipulation.

increment the reference count when you store a new reference. decrement when the reference is no longer used. do not refer to the object any longer once references have been released.

Since:

0.10

print XML symbol element representation to user result buffer.

See also:

http://zbar.sourceforge.net/2008/barcode.xsd for the schema.

Parameters:

symbol	is the symbol to print
buffer	is the inout result pointer, it will be reallocated with a larger size if necessary.
buflen	is inout length of the result buffer.

Returns:

the buffer pointer

Since:

0.6

retrieve runtime library version information.

Parameters:

major	set to the running major version (unless NULL)
minor	set to the running minor version (unless NULL)

Returns:

0

Definition at line 56 of file error.c.

constructor.

destructor.

start/stop video capture.

all buffered images are retired when capture is disabled.

Returns:

0 if successful or -1 if an error occurs

display detail for last video error to stderr.

Returns:

a non-zero value suitable for passing to exit()

Definition at line 882 of file zbar.h.

retrieve the detail string for the last video error.

Definition at line 889 of file zbar.h.

retrieve the type code for the last video error.

Definition at line 897 of file zbar.h.

retrieve file descriptor associated with open *nix video device useful for using select()/poll() to tell when new images are available (NB v4l2 only!!).

Returns:

the file descriptor or -1 if the video device is not open or the driver only supports v4l1

retrieve current output image height.

Returns:

the height or 0 if the video device is not open

retrieve current output image width.

Returns:

the width or 0 if the video device is not open

initialize video using a specific format for debug.

use zbar_negotiate_format() to automatically select and initialize the best available format

retrieve next captured image.

blocks until an image is available.

Returns:

NULL if video is not enabled or an error occurs

open and probe a video device.

the device specified by platform specific unique name (v4l device node path in *nix eg "/dev/video", DirectShow DevicePath property in windows).

Returns:

0 if successful or -1 if an error occurs

request a preferred driver interface version for debug/testing.

Note:

must be called before zbar_video_open()

Since:

0.6

request a preferred I/O mode for debug/testing.

You will get errors if the driver does not support the specified mode.

    0 = auto-detect
    1 = force I/O using read()
    2 = force memory mapped I/O using mmap()
    3 = force USERPTR I/O (v4l2 only)

Note:

must be called before zbar_video_open()

Since:

0.7

request a preferred size for the video image from the device.

the request may be adjusted or completely ignored by the driver.

Returns:

0 if successful or -1 if the video device is already initialized

Since:

0.6

associate reader with an existing platform window.

This can be any "Drawable" for X Windows or a "HWND" for windows. input images will be scaled into the output window. pass NULL to detach from the resource, further input will be ignored

constructor.

destructor.

draw a new image into the output window.

display detail for last window error to stderr.

Returns:

a non-zero value suitable for passing to exit()

Definition at line 968 of file zbar.h.

retrieve the detail string for the last window error.

Definition at line 976 of file zbar.h.

retrieve the type code for the last window error.

Definition at line 984 of file zbar.h.

retrieve current content level of reader overlay.

See also:

zbar_window_set_overlay()

Since:

0.10

redraw the last image (exposure handler).

resize the image window (reconfigure handler).

this does not update the contents of the window

Since:

0.3, changed in 0.4 to not redraw window

control content level of the reader overlay.

the overlay displays graphical data for informational or debug purposes. higher values increase the level of annotation (possibly decreasing performance).

    0 = disable overlay
    1 = outline decoded symbols (default)
    2 = also track and display input frame rate