File: modules/Scanner.ycp Package: Configuration of scanner Summary: Scanner settings, input and output functions Authors: Johannes Meixner

$Id: Scanner.ycp 63392 2011-02-10 13:47:27Z jsmeix $

Something was committed to the system? True if system may have been modified.

Write only, used during autoinstallation. Don't run services and SuSEconfig, it's all done at one place.

Something was committed to the system?

Return value:

true if system may have been modified

Abort function

Return value:

true if not modified and user requested abort

Explicite listing of all alphanumeric ASCII characters. The reason is that in certain special locales for example [a-z] is not equivalent to "abcdefghijklmnopqrstuvwxyz" because in certain special languages the 'z' is not the last character in the alphabet, e.g. the Estonian alphabet ends with ... s ... z ... t u v w ... x y (non-ASCII characters omitted here) so that [a-z] would exclude t u v w x y in an Estonian locale. Therefore uppercase and lowercase characters are both explicitly listed to avoid any unexpected result e.g. of "tolower(uppercase_characters)".

Scanner database: When package version of sane-backends/hplip/iscan/iscan-free changes the database is created anew in Scanner::Read() which calls the bash script "/usr/lib/YaST2/bin/create_scanner_database YCP" which outputs on stdout a YCP list of scanner_model_map where the last list entry is an emtpy map.

Structure scanner_model_map

 $[ "package":"The package which provides the backend: sane-backends/hplip/iscan/iscan-free (required)",
    "backend":"The name of the backend (required)",
    "version":"The backend's arbitrary version string or 'unmaintained' (may be the empty string)",
    "manufacturer":"The manufacturer name of the scanner (required)",
    "model":"The model name of the scanner (required)",
    "firmware":"Whether or not firmware upload is required (value is 'required' or the empty string)",
    "interface":"None or one or more scanner interfaces (may be the empty string)",
    "usbid":"USBvendorID:USBproductID" e.g. "0x0a1b:0x2c3d" (may be the empty string)",
    "status":"The support status: basic/complete/good/minimal/unsupported/untested (required)",
    "comment":"An optional comment (may be the empty string)"
  ]

Manufacturer list: List of unique manufacturer names. Derived during startup from the scanner database (in the Read function stage "Read or create the scanner database").

Known USB scanner USB IDs list: List of known USB scanner USB vendor and product IDs. Derived during startup from the scanner database (in the Read function stage "Read or create the scanner database").

Active scanners: Determined at runtime via Scanner::DetermineActiveScanners() which calls the bash script "/usr/lib/YaST2/bin/determine_active_scanners YCP" which outputs on stdout a YCP list of active_scanner_map where the last list entry is an emtpy map.

Structure active_scanner_map

 $[ "backend":"The name of the backend (required)",
    "sane_device":"The SANE device (required)",
    "manufacturer":"The manufacturer name of the scanner (required)",
    "model":"The model name of the scanner (required)",
  ]

Active backends: Determined at runtime via Scanner::DetermineActiveBackends() which calls the bash script "/usr/lib/YaST2/bin/determine_active_scanner_backends YCP" which outputs on stdout a YCP list of backends [ "The name of the backend", ... "" ] where the last list entry is an empty string.

Autodetected scanners: Determined at runtime via Scanner::AutodetectScanners() which calls the bash script /usr/lib/YaST2/bin/autodetect_scanners YCP which calls "sane-find-scanner" and (if available) "hp-probe" which may result for example the description strings in the example below. Only in case of USB an automated extraction of manufacturer is possible. If there are two '[...]' substrings then the first one is the manufacturer and the second one is the model (but there may be only one or none substring). The result is a YCP list of autodetected_scanner_map where the last list entry is an emtpy map.

Structure autodetected_scanner_map

 $[ "connection":"Either USB or SCSI or NETWORK (required)",
    "device":"The device, e.g. '/dev/sg0' or 'libusb:001:002' (may be the empty string)"
    "manufacturer":"The manufacturer name of the scanner (may be the empty string)",
    "usb_vendor_id":"The vendor ID (e.g. 0x04b8) of a USB scanner (may be the empty string)",
    "model":"The model name of the scanner (may be the empty string)",
    "usb_product_id":"The product ID (e.g. 0x010b) of a USB scanner (may be the empty string)",
    "description":"The sane-find-scanner output description string (required)"
  ]

Example

SCSI processor 'HP C6270A 3846' at /dev/sg0 USB scanner (vendor=0x05da, product=0x20b0) at libusb:002:005 USB scanner (vendor=0x03f0 [Hewlett-Packard], product=0x0201 [HP ScanJet 6200C]) at libusb:002:006 USB scanner (vendor=0x04a9 [Canon], product=0x220e [CanoScan], chip=LM9832/3) at libusb:001:005 USB scanner (vendor=0x04b8 [EPSON], product=0x010b [Perfection1240]) at libusb:001:004 USB scanner (vendor=0x03f0 [HP], product=0x0000 [HP LaserJet 1220]) NETWORK scanner (vendor [HP], product [Officejet 7200 series])

Network scanning configuration: Determined at runtime via Scanner::DetermineNetworkScanningConfig() which calls the bash script "/usr/lib/YaST2/bin/determine_network_scanner_config YCP" which outputs on stdout a YCP map network_scanner_config

Structure network_scanner_config

 $[ "net_backend_hosts":"Comma seperated list of hosts in /etc/sane.d/net.conf",
    "saned_hosts":"Comma seperated list of hosts or subnets in /etc/sane.d/saned.conf"
  ]

Environment values: It is a map of environment_values

Structure environment_values

 $[ "sane-backends_version":"What 'rpm -q sane-backends' returns (required)",
    "hplip_version":"What 'rpm -q hplip' returns (required)",
    "iscan_version":"What 'rpm -q iscan' returns (required)"
    "iscan-free_version":"What 'rpm -q iscan-free' returns (required)"
  ]

Selected model database index: The index in the scanner database list (of model maps) for the model which was selected by the user in the SelectModelDialog. Preset to -1 which indicates that no model is selected.

Selected autodetected scanners index: The index in the autodetected scanners list (of autodetected scanner maps) for the model which was selected by the user in the OverviewDialog. Preset to -1 which indicates that no model is selected.

Ignore unknown USB scanners: Whether or not unknown USB scanners should be ignored during AutodetectScanners. As there is no USB device class for scanners (they have the unspecific USB device class 255), sane-find-scanner can only do some best guess to determine if a USB device is a scanner or not. Therefore also other USB devices with the device class 255 are reported as possible USB scanners. Preset to true so that initially only scanners for which the USB IDs are known by SANE are shown. It changes to false (i.e. show all USB devices with the device class 255 as possible USB scanners) when the user explicitly requests a "Restart Detection" in the OverviewDialog. A second "Restart Detection" changes it back to true so that "Restart Detection" toggles it. The idea behind is that the user can simply "Restart Detection" as often as he likes until the result is o.k. for him because "Restart Detection" does not cause harm and it avoids a separated button or check-box to determine the autodetection behaviour which would require additional explanatory (complicated) help text about the whole stuff. Examples: Assume there is a known powered-off USB scanner and another USB device with class 255: Initially nothing is shown. After the first "Restart Detection" only the other USB device with class 255 is shown. This unexpected result makes the user think about what is wrong and he powers-on the scanner. After the second "Restart Detection" only the USB scanner is shown. Assume there is an unknown powered-off USB scanner and another USB device with class 255. Initially nothing is shown. After the first "Restart Detection" only the other USB device with class 255 is shown. This unexpected result makes the user think about what is wrong and he powers-on the scanner. After the second "Restart Detection" nothing is shown. A third "Restart Detection" shows both the USB scanner and the other USB device with class 255. This is the best possible result because it is not possible to show only the unknown USB scanner.

Unify various kind of a hexadecimal string like "0x01a2", "0x1A2", "0x01A2" to one kind "0x1a2" so that string comparison is possible:

Parameters:

hexstring

Wrapper for SCR::Execute to execute a bash command to increase verbosity via y2milestone. It reports the command via y2milestone in any case and it reports exit code, stdout and stderr via y2milestone in case of non-zero exit code.

Parameters:

bash_commandline

string of the bash command to be executed

Return value:

true on success

Test whether an error message is meaningful (i.e. when it contains at least one letter character). If yes, add a preceding "The error message is:" otherwise return the empty string.

Parameters:

error_message

string of the error message

Return value:

of a meaningful error message with preceding "The error message is:" or "" otherwise

Determine the version of an installed package by calling a bash command (rpm).

Parameters:

package_name

string of the package name

Return value:

of the version of an installed package or "failed to determine" otherwise

Test whether the package is installed (Package::Installed) and if not then test whether the package is available to be installed (Package::Available) and if yes then install it (Package::Install).

Parameters:

package_name

string of the package name

Return value:

true on success

Determine the active scanners by calling a bash script which calls "scanimage -L" and processes its output and stores the results as YCP list in a temporary file and then read the temporary file (SCR::Read) to get the YCP list of active_scanner_map

Return value:

true on success

Determine the active backends by calling a bash script which calls "grep ... /etc/sane.d/dll.conf" and processes its output and stores the results as YCP list in a temporary file and then read the temporary file (SCR::Read) to get the YCP list of active backends.

Return value:

true on success

Try to autodetect USB and SCSI scanners and HP all-in-one USB and NETWORK scanners by calling a bash script which calls "sane-find-scanner" and (if available) "hp-probe" and processes its output and stores the results as YCP list in a temporary file and then read the temporary file (SCR::Read) to get the YCP list of autodetected_scanner_map

Return value:

true on success

Test whether there exist a print queue which depends on the specified SANE backend. Examples: hpaio (package hplip): Setting up the hpaio backend activates also the hplip service. It may happen that the conflicting service ptal is in use by the CUPS printing system. I.e. there may be a print queue which uses the ptal CUPS backend. hpoj (package hp-officeJet): Setting up the hpoj backend requires to initialize/activate/start the ptal service. It may happen that the conflicting service hplip is in use. I.e. there may be a print queue which uses the hp CUPS backend. Note: The test is only implememnted for the CUPS printing system. A dependant print queue can exists only for the SANE backends hpaio and hpoj. For all other backends no dependant print queue can exists.

Parameters:

backend_name

string of the SANE backend name

Return value:

true if a dependant CUPS print queue exists for the backends hpaio or hpoj

Read all scanner settings: - Check installed packages - Read or create the scanner database - Determine active scanners - Determine active backends - Try to autodetect USB and SCSI scanners and HP all-in-one USB and NETWORK scanners

Return value:

true on success

Write scanner settings: - Save the actual environment

Return value:

true on success

Restart the whole autodetection by calling all autodetection functions in the same order as during the initial Read(): DetermineActiveScanners results a new active_scanners map which is empty if nothing was detected or if DetermineActiveScanners fails. DetermineActiveBackends results a new active_backends list which is empty if nothing was detected or if DetermineActiveBackends fails. AutodetectScanners results a new autodetected_scanners map which is empty if nothing was detected or if AutodetectScanners fails. RestartDetection is called when the user restarts the detection in the OverviewDialog and if testing of an active scanner failed (see the TestBackend function). The result is that all information in the OverviewDialog is recreated.

Return value:

true in any case (errors result only empty maps or list).

Run hp-setup:

Return value:

false if hp-setup cannot be run and return true in any other case because there is no usable exit code of hp-setup (always zero even in case of error).

Create the content for WizardHW::SetContents

Return value:

a list of maps with keys "id" : string = the identification of the device, "rich_descr" : string = RichText description of the device "table_descr" : list = fields of the table

Create a list of items from the database entries which is used for the SelectionBox in the SelectModelDialog

Parameters:

filter_string

string of a search string to return only matching models (retunr all models if filter_string is the empty string)

Return value:

of model strings (manufacturer, model, backend, comment)

Activate the backend in /etc/sane.d/dll.conf according to the specified backend_name or if the specified backend_name is the empty string then set the backend_name according to a specified database_index.

Parameters:

backend_name	string of a backend which should be activated (if backend_name is the empty string then database_index must be >= 0)
database_index	integer which points to an entry in the model database (if backend_name is the empty string then the backend according to the database_index is used)
user_confirmation	boolean true if user confirmation popup in case of problems is requested

Return value:

true on success

Deactivate the backend in /etc/sane.d/dll.conf according to the specified backend_name or if the specified backend_name is the empty string then set the backend_name according to a specified database_index.

Parameters:

backend_name	string of a backend which should be deactivated (if backend_name is the empty string then database_index must be >= 0)
database_index	integer which points to an entry in the model database (if backend_name is the empty string then the backend according to the database_index is used)
user_confirmation	boolean true if user confirmation popup in case of problems is requested

Return value:

true on success

Test the backend according to the specified backend_name.

Parameters:

backend_name

string of a backend which should be tested

Return value:

true on success

Determine the network scanning config by calling a bash script which calls "grep ... /etc/sane.d/net.conf" and "grep ... /etc/sane.d/saned.conf" and processes its output and stores the results as YCP map in a temporary file and then read the temporary file (SCR::Read) to get the YCP map.

Return value:

true on success

Setup the network scanning config by calling a bash script which activates or deactivates the "net" backend and which writes into /etc/sane.d/net.conf, /etc/sane.d/saned.conf, and /etc/xinetd.d/sane-port and reloads or starts the xinetd dependig on whether it is running or not.

Return value:

true on success

Determine if any kind of firewall seems to be active by calling "iptables -n -L | egrep -q 'DROP|REJECT'" to find out if there are currently dropping or rejecting packet filter rules. One might use a more specific test via "iptables -n -L | grep -v '^LOG' | egrep -q '^DROP|^REJECT'" to match only for DROP and REJECT targets and exclude LOG targets but it does not cause real problems when there is a false positive result here because all what happens it that then a needless firewall info popup would be shown. If any kind of firewall seems to be active, show a popup message regarding scanning via network and firewall.

Return value:

true if any kind of firewall seems to be active

Get all scanner settings from the first parameter. For use by autoinstallation.

Parameters:

settings

The YCP structure to be imported.

Return value:

true on success

Dump the scanner settings to a single map. For use by autoinstallation.

Return value:

Dumped settings (later acceptable by Import ())

Return packages needed to be installed and removed during autoinstallation to insure module has all needed software installed.

Return value:

with 2 lists.