Deprecation warning
Please note that this is outdated documentation for an older release of the Scandit Barcode Scanner SDK.
We are deprecating the 5.x API on all platforms (except Linux). Release 5.19 in April 2021 will be our final. Applications running 5.x will continue to work, and we will continue to release critical bug fixes and security patches only, for one year. We encourage you to migrate to 6.x and take advantage of our latest / advanced features and improved performance.
You'll find the updated documentation at: Data Capture SDK Documentation for Android
Detailed Description
An opaque data structure holding configuration options for the barcode scanner.
The barcode scanner settings influence how 1d and 2d codes are decoded by an ScBarcodeScanner instance.
For the settings to take effect they must be applied to the barcode scanner. This can be done when the barcode scanner is created (sc_barcode_scanner_new_with_settings()), or at a later stage with sc_barcode_scanner_set_settings().
Steps to Configure the Barcode Scanner
- Create a new settings object starting from an empty configuration (sc_barcode_scanner_settings_new()), or using a combination of presets (sc_barcode_scanner_settings_new_with_preset()).
- Enable decoding of the required 1d and 2d symbologies using sc_barcode_scanner_settings_set_symbology_enabled().
- Optional: Set any additional symbology-specific settings on the symbology settings objects obtained by calling sc_barcode_scanner_settings_get_symbology_settings().
- Optional: If desired, configure the scan location (see below).
Scan Location
By default, 1d and 2d codes are searched in the full image. If it is known that codes only appear in certain areas, or part of the camera feed is hidden below a UI element, the localization can be restricted to certain parts of the image by setting the scan area with sc_barcode_scanner_settings_set_search_area(). This setting affects both 1d and 2d codes.
To control scanning areas of 1d and 2d codes separately, set the 1d/2d code location areas (sc_barcode_scanner_settings_set_code_location_area_1d(), sc_barcode_scanner_settings_set_code_location_area_2d()). By default, these areas serve as hints to the barcode scanner as to where codes are expected in the image (the code location constraints are set to SC_CODE_LOCATION_HINT). The scanner uses these areas to give more weight to codes found in the code location areas. It is also possible to completely turn off barcode localization and only use the 1d/2d code location areas. This is done by setting the code location constraint to SC_CODE_LOCATION_RESTRICT.
Use Cases
To illustrate how the scan area, 1d/2d code location areas and constraints work together, we show configurations for common scanning scenarios.
Full Image Localization with preference to horizontal 1d codes: This is the default setting and not further configuration is required. The 1d code location area is set to a centered strip 1/5 of of the image height running from the left to the right. The code location constraint is set to SC_CODE_LOCATION_HINT, and the code direction hint is SC_CODE_DIRECTION_LEFT_TO_RIGHT.
Laser UI Scanning: To scan barcodes in a narrow band, set the 1d code location area and use a 1d code location constraint of SC_CODE_LOCATION_RESTRICT. You also need to set the code direction hint to match the main direction of the narrow band. If at the same time 2d codes are to be scanned, set the 2d code location area to a larger rectangle.
- Since
- 4.6.0
Member Function Documentation
ScBarcodeScannerSettings * sc_barcode_scanner_settings_new | ( | void | ) |
Create a new barcode scanner settings object.
This function is identical to using sc_barcode_scanner_settings_new_with_preset() with SC_PRESET_NONE.
- Returns
- the newly created barcode scanner settings object. The object must be released after use by calling sc_barcode_scanner_settings_release().
- Since
- 4.6.0
- Examples:
- ScanditNativeBarcodeScannerDemo.c.
ScBarcodeScannerSettings * sc_barcode_scanner_settings_new_with_preset | ( | ScBarcodeScannerSettingsPresetFlags | preset | ) |
Create a new barcode scanner settings object.
- Parameters
-
preset an ORed combination of ScBarcodeScannerSettingsPreset
- Returns
- the newly created barcode scanner settings object. The object must be released after use by calling sc_barcode_scanner_settings_release().
- Since
- 4.6.0
- Examples:
- ScanditNativeBarcodeScannerCameraDemo.c.
ScBarcodeScannerSettings * sc_barcode_scanner_settings_new_from_json | ( | const char * | json_data, |
ScError * | error | ||
) |
Create a new barcode scanner settings object from a json description.
- Parameters
-
json_data null-terminated JSON data string. The string is allowed to have comments as well as use single quotes instead of double quotes. error in case the JSON data could not be parsed, error is filled with more details on the failure. In case of error, error
must be freed after use using sc_error_free(). NULL may be used in case no further information on the error is required.
- Returns
- the newly created barcode scanner settings object. NULL is returned in case the json data could not be parsed without errors. Check
error
for details.
For a description of the JSON format undestood by this function, see Barcode Scanner Settings JSON format.
- Since
- 4.11.0
void sc_barcode_scanner_settings_retain | ( | ScBarcodeScannerSettings * | settings | ) |
Increase reference count of barcode scanner settings.
- Parameters
-
settings the barcode scanner settings object. Must not be null
- Since
- 4.6.0
void sc_barcode_scanner_settings_release | ( | ScBarcodeScannerSettings * | settings | ) |
Decrease reference count of barcode scanner settings object by one.
When the reference count of the object drops to zero, it is deallocated.
- Parameters
-
settings the barcode scanner settings object. Must not be null.
- Since
- 4.6.0
ScBarcodeScannerSettings * sc_barcode_scanner_settings_clone | ( | ScBarcodeScannerSettings * | settings | ) |
Creates and returns a deep copy of the barcode scanner settings object.
- Parameters
-
settings The settings object to be copied/cloned. Must not be null.
- Returns
- The cloned barcode scanner settings object with a reference count of one. After use, the barcode scanner settings object must be released with sc_barcode_scanner_settings_release().
- Since
- 4.7.0
int32_t sc_barcode_scanner_settings_get_property | ( | const ScBarcodeScannerSettings * | settings, |
const char * | key | ||
) |
Get custom properties.
Custom properties are used for features of the barcode scanner that are not yet part of the public API. As such they can disappear in one of the next releases or change meaning. Use with caution.
Only properties of previous calls to sc_barcode_scanner_settings_set_property() are returned here. When a property is not set, a default value is assumed.
- Parameters
-
settings the settings object. Must not be null key the name of the property
- Returns
- The value of the property, or -1 if the property does not exist.
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_property | ( | ScBarcodeScannerSettings * | settings, |
const char * | key, | ||
int32_t | value | ||
) |
Set custom properties.
- Parameters
-
settings the settings object. Must not be null key the name of the property value the value to be set
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_symbology_enabled | ( | ScBarcodeScannerSettings * | settings, |
ScSymbology | symbology, | ||
ScBool | enabled | ||
) |
Enable/disable decoding of a certain symbology.
This function provides a convenient shortcut to enabling/disabling decoding of a particular symbology without having to go through ScSymbologySettings.
- Parameters
-
settings the barcode scanner settings object. Must not be null symbology the symbology to be enabled. Must be a valid symbology and equal to SC_SYMBOLOGY_UNKNOWN enabled true when decoding of the symbology should be enabled, false if not.
- Since
- 4.6.0
ScSymbologySettings * sc_barcode_scanner_settings_get_symbology_settings | ( | ScBarcodeScannerSettings * | settings, |
ScSymbology | symbology | ||
) |
Retrieve symbology-specific settings.
- Parameters
-
settings the barcode scanner settings object. Must not be null symbology the symbology for which to retrieve the settings. Must be one of the valid symbology enums and not SC_SYMBOLOGY_UNKNOWN.
- Returns
- the symbology-specific settings object. The object is owned by the barcode scanner settings object and freed automatically when the barcode scanner settings object is freed.
- Since
- 4.6.0
uint32_t sc_barcode_scanner_settings_get_max_number_of_codes_per_frame | ( | const ScBarcodeScannerSettings * | settings | ) |
Get the maximum number of barcode to be decoded every frame.
- Parameters
-
settings the barcode scanner settings object. Must not be null
- Returns
- the maximum number of codes per frame
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_max_number_of_codes_per_frame | ( | ScBarcodeScannerSettings * | settings, |
uint32_t | max_codes | ||
) |
Set the maximum number of barcode to be decoded every frame.
- Parameters
-
settings the barcode scanner settings object. Must not be null max_codes the new maximum number of codes to be decoded every frame. Can not be set to zero.
- Since
- 4.6.0
- Examples:
- ScanditNativeBarcodeScannerCameraDemo.c.
ScRectangleF sc_barcode_scanner_settings_get_search_area | ( | const ScBarcodeScannerSettings * | settings | ) |
Get the area of the image in which barcodes are searched.
By default, barcodes are searched in the whole image. By restricting the search area to smaller areas the barcode scanner performance can be optimized.
- Parameters
-
settings The barcode scanner settings object. Must not be null.
- Returns
- the barcode scan area in relative coordinates. The top-left corner of the image is (0,0), the bottom right corner is (1, 1).
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_search_area | ( | ScBarcodeScannerSettings * | settings, |
ScRectangleF | scan_area | ||
) |
Set the area of the image in which barcodes are searched.
- Parameters
-
settings The barcode scanner settings object. Must not be null. scan_area The new search area in relative coordinates.
- Since
- 4.6.0
ScRectangleF sc_barcode_scanner_settings_get_code_location_area_1d | ( | const ScBarcodeScannerSettings * | settings | ) |
Get 1d code location area.
- Parameters
-
settings the settings object. Must not be null
- Returns
- the code location hint in relative coordinates
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_location_area_1d | ( | ScBarcodeScannerSettings * | settings, |
ScRectangleF | rect | ||
) |
Set code location area for 1d codes.
- Parameters
-
settings the settings object. Must not be null rect the code location hint in relative coordinates
- Since
- 4.6.0
- Examples:
- ScanditNativeBarcodeScannerCameraDemo.c.
ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_1d | ( | const ScBarcodeScannerSettings * | settings | ) |
Get 1d code location constraint.
- Parameters
-
settings the settings object. Must not be null.
- Returns
- The code location constraint
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_location_constraint_1d | ( | ScBarcodeScannerSettings * | settings, |
ScCodeLocationConstraint | constraint | ||
) |
Set the 1d code location constraint.
- Parameters
-
settings The settings object. Must not be null. constraint The code location constraint.
- Since
- 4.6.0
ScRectangleF sc_barcode_scanner_settings_get_code_location_area_2d | ( | const ScBarcodeScannerSettings * | settings | ) |
Get 2d code location area.
- Parameters
-
settings the settings object. Must not be null
- Returns
- the code location hint in relative coordinates
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_location_area_2d | ( | ScBarcodeScannerSettings * | settings, |
ScRectangleF | rect | ||
) |
Set code location area for 2d codes.
- Parameters
-
settings the settings object. Must not be null rect the code location hint in relative coordinates
- Since
- 4.6.0
ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_2d | ( | const ScBarcodeScannerSettings * | settings | ) |
Get 2d code location constraint.
- Parameters
-
settings the settings object. Must not be null
- Returns
- the code location hint in relative coordinates
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_location_constraint_2d | ( | ScBarcodeScannerSettings * | settings, |
ScCodeLocationConstraint | constraint | ||
) |
Set the 2d code location constraint.
- Parameters
-
settings The settings object. Must not be null constraint The code location constraint.
- Since
- 4.6.0
- Examples:
- ScanditNativeBarcodeScannerDemo.c.
ScCameraFocusMode sc_barcode_scanner_settings_get_focus_mode | ( | const ScBarcodeScannerSettings * | settings | ) |
Get the camera's focus type.
- Parameters
-
settings the settings object. Must not be null
- Returns
- the current focus type of the camera
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_focus_mode | ( | ScBarcodeScannerSettings * | settings, |
ScCameraFocusMode | focus_mode | ||
) |
Set the camera's focus type.
- Parameters
-
settings the settings object. Must not be null. focus_mode the focus type of the camera.
- Since
- 4.6.0
- Examples:
- ScanditNativeBarcodeScannerCameraDemo.c.
ScCodeDirection sc_barcode_scanner_settings_get_code_direction_hint | ( | const ScBarcodeScannerSettings * | settings | ) |
Get the code direction hint.
- Parameters
-
settings the barcode scanner settings object. Must not be null.
- Returns
- The current code direction hint. The default is SC_CODE_DIRECTION_LEFT_TO_RIGHT.
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_direction_hint | ( | ScBarcodeScannerSettings * | settings, |
ScCodeDirection | direction | ||
) |
Set the code direction hint.
The code direction hint tells the barcode scanner in what direction 1-dimensional codes are most likely oriented. This hint is only useful for 1d (barcodes), and ignored for 2d codes.
The hint is in image coordinates. If you are scanning barcodes on a mobile device that supports multiple device orientations, you will have to rotate the hint accordingly. For example if you want to scan horizontal codes when the phone/device is in portrait mode, you will have to set the code direction hint to SC_CODE_DIRECTION_BOTTOM_TO_TOP.
- Parameters
-
settings The barcode scanner settings object. Must not be null. direction The new code direction hint.
- Since
- 4.6.0
int32_t sc_barcode_scanner_settings_get_code_duplicate_filter | ( | const ScBarcodeScannerSettings * | settings | ) |
Get the code duplicate filter of the scan session.
Duplicate filtering affects the handling of codes with the same data and symbology. When the filter is set to -1, each unique code is only added once to the session, when set to 0, duplicate filtering is disabled. Otherwise the duplicate filter specifies an interval in milliseconds. When the same code (data/symbology) is scanned within the specified interval is it filtered out as a duplicate.
By default, the code duplicate filter is disabled.
- Parameters
-
settings the settings object. Must no be null
- Returns
- The current code duplicate filter.
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_duplicate_filter | ( | ScBarcodeScannerSettings * | settings, |
int32_t | filter | ||
) |
Specifies the duplicate filter to use for the session.
- Parameters
-
settings the settings object. Must no be null filter the new code duplicate filter
- Since
- 4.6.0
int32_t sc_barcode_scanner_settings_get_code_caching_duration | ( | const ScBarcodeScannerSettings * | settings | ) |
Get the code caching duration of the scan session.
When set to -1, codes are kept until the next call to sc_barcode_scanner_session_clear(). When set to 0, codes are kept until the next frame processing call finishes. For all other values, code_caching_duration specifies a duration in milliseconds for how long the codes are kept.
The default value is -1
- Parameters
-
settings the settings object. Must not be null
- Returns
- The code caching duration.
- Since
- 4.6.0
void sc_barcode_scanner_settings_set_code_caching_duration | ( | ScBarcodeScannerSettings * | settings, |
int32_t | duration | ||
) |
Determines how long codes are kept in the session.
- Parameters
-
settings the settings object. Must not be null duration the code caching duration
- Since
- 4.6.0
char * sc_barcode_scanner_settings_as_json | ( | const ScBarcodeScannerSettings * | settings | ) |
Returns the settings contained in the object as json.
- Parameters
-
settings the settings object. Must not be null
- Returns
- The settings serialized as JSON. After use the string must be freed by the caller using sc_free().
- Since
- 4.6.0
void sc_barcode_scanner_settings_setup_for_ui_image | ( | ScBarcodeScannerSettings * | settings, |
UIImage * | image | ||
) |
Configure barcode scanner settings for recognizing barcodes in the provided UIImage.
Use this function for optimizing the barcode scanner settings for scanning barcodes with ScRecognitionContext::sc_recognition_context_process_image. The settings, e.g. recognition areas, code direction hint etc. are modified in-place. This function does not enable any of the symbologies. You need to explicitly enable the barcode symbologies that you would like to scan.
- Parameters
-
settings The settings object to modify. Must not be null image the image to optimize parameters for.
- Since
- 4.14.0
The documentation for this struct was generated from the following file: