SANE

SANE - TODO list for standard version 2

This list intends to show the items which need to be finished before the SANE2 standard can be published. It's based on Oliver Rauch's sane2-api-todo.txt document. The headlines show the status of the change as shown below. Keep in mind that this status is just the opinion of the author of this page (hmg). If you think that anything is wrong or missing, contact sane-standard.

Accepted: The change is in the latest standard

Further discussion: The change is in the standard but there are still problems

Rejected: the change won't be included in the standard

(no status): neither included nor rejected yet

Naming and versioning

Archive/CVS name

"sane-backends2" (-->sane-backends2-2.x.y) or sane2-backends (-->sane2backends-2.x.y)?

Header file

"sane/sane2.h", "sane/sane-2.h", "sane2/sane.h" or "sane/sane."?

Libraries

"libsane2-dll.so" or "libsane-dll2.so"?

Standard

Use 3 versions for the standard (major, minor, revision)? The major number would be 2 and means "binary incompatible changes". The minor number means: additions to the standard (e.g. using of reserved values). The revision is for changes that don't change the interface at all (clarifications, more return values for a function).

Config file names

"/etc/sane2.d/dll.conf"? "/etc/sane.d/dll2.conf" doesn't work because there are already backends with numbers (microtek2.conf).

SANE data types

SANE_Char

UTF-8 format

All texts and translations: UTF-8 format (this is used in KDE and gtk+-2.x) may be UTF-8 should be forced as SANE_Char format. Currently ISO-8859-1 is used as encoding.

SANE_Parameters

Move SANE_Parameters to data type section

I don't see any reason to keep SANE_Parameters in the "Operations" section as all the other data types are in "Data Types".

Changes to frames (SANE_Parameters.format) (accepted)

Use SANE_FRAME_RAW, formatdesc="red:8,green:8,blue:8" instead of old SANE_FRAME_* types. Add SANE_FRAME_MIME, formatdesc=MIME-descriptor, only one frame/image, arbitrary data. This allows transmission of e.g. jpeg, tiff and any other data format. SANE_FRAME_GRAY/RGB/RED/GREEN/BLUE are obsolete.

define bit order of 1 bit modes (accepted)

Lineart: 1 = black, other modes: 0 = black. Reason: History.

Remove multi-frame paradigm at all

More than one frame is used e.g. for 3-pass scanners. Maybe also film scanners use a separate frame for IR data?

Remove multi-channel 1 bit mode (accepted)

Some old Mustek scanners support this mode (color 1 bit). But it's not really useful. So 1 bit color is not allowed anymore.

Add flags to SANE_Parameters.flags (accepted)

Make it compatible to SANE 1. Adds more_images, new_page, front/backside info, 28 more flags available.

More informational values (accepted)

Add dpi_x, dpi_y, proposed_filename, formatdesc, channels_per_image.

32 bytes for future extension (set to 0) (further discussion)

Check how to do this without creating portability nightmares. The current implementation just won't work as sizeof(SANE_Int) = 4 is not true everywhere. Keep in mind that the size of SANE_Int is unknown, same is true for SANE_String and even char. maybe just use SANE_Int reserved[10]?

SANE_Device

Add informational and reserved members (accepted)

These members have been added:

Next pointer (rejected)

Add a pointer "next" to the device handle to make linked lists instead of arrays. Is this incompatible change really useful?

SANE_Status

Add more errors

E.g. out of memory in scanner, file not found, firmware not found, some kind of error concerning options, power failure of scanner,...

Change SANE_Status to (also) contain textual error messages

The fixed error messages are sometimes not enough to find out what's wrong exactly. E.g. which file is not found exactly or which option can't be set?

One proposal is:

typedef struct {
  int code;
  char *msg;
} SANE_Status;
    

SANE_Status.code is always a standard SANE status code. If SANE_Status.msg is NULL, then the standard SANE status message is printed, end of the story. Otherwise, the custom SANE_Status.msg is printed, and the caller must free SANE_Status.msg.

The good thing about that proposal is that the error message comes with the error code. That way we don't need a new API function to get the verbose error message. The bad thing is that the caller has to care about freeing msg. Also check if this works with saned.

Another proposal: Slightly redefine SANE_Status, as a 32bit integer where the 2 MSB are a backend-specific error code and the 2 LSB are a standard SANE status code.

The 2 LSB will always correspond to a SANE status.

If the 2 MSB are non-zero, they are passed to a sane_backend_status() routine inside the backend that returns a proper status message that is then echoed to the user. (depending on what we want to achieve, we'd require the caller to free the message after use, think sprintf(), etc...). Otherwise, the standard SANE status message is echoed.

Problems with this proposal: How does the dll backend know which backend to ask for the error code? The usual problems: thread safety, who frees the message.

SANE_Option_Descriptor

SANE_CAP_ADVANCED for a group (accepted)

SANE_CAP_ALWAYS_SETTABLE (accepted)

SANE_CAP_HIDDEN (accepted)

SANE_CAP_AUTO_POLL

One of the problems with the options system in SANE is that a backend can't tell the frontend that something has changed. Such a feature would be useful if a button is pressed on the scanner or some other status in the scanner changes. As callbacks are not available over the network, polling of options can be used a a workaround. An option with the capability SANE_CAP_AUTO_POLL should be read by the frontend each [interval] milliseconds. The interval should be defined. (e.g. min 100 msecs, max 1 sec?)

SANE API functions

sane_open

New parameter: sane_device (accepted)

sane_open does return sane_device: A frontend may decide not to call sane_get_devices because it already knows which device shall be opened. In this case it does not get any information about the device (vendor, model, ...). So it makes sense to return the SANE_Device in sane_open.

sane_get_parameters

Define error codes for sane_get_parameters

Currently there are no error codes.

Move SANE_Parameters to data type section

All the other structs are defined in the data type sections. I don't see any reason to not move SANE_Parameters to that section.

sane_init

Define return value of sane_init

sane_get_select_fd

Implementation note for select_fd

If the select_fd is a pipe, it's not enough to close "the other side" of that pipe. The select_fd must be closed itself. The frontend shouldn't assume that the fd is a pipe.

sane_control_option

Which parts of an option descriptor can be changed at run-time?

Define what parts in a option_descriptor may be changed after it has been set up and passed to the frontend.

More members of option descriptor that should be changeable

Maybe add size to list of members that can be changed?

SANE_INFO_INVALIDATE_PREVIEW (accepted)

When an option is set with sane_control_option that changes the image significantly (e.g. exposure) invalidate the preview by setting SANE_INFO_INVALIDATE_PREVIEW.

sane_strstatus

Remove "const" (accepted)

New SANE API functions

sane_verbose_error

Add SANE_String sane_verbose_error(Sane_Handle h), to show backend-specific error messages. The error string always refers to the last error reported by the backend. So the frontend would call this when a SANE API call returned with an error status. E.g. out-of-memory in scanner hardware or "Couldn't open file foo". Check for thread-safety problems. If the handle parameter is used, no errors can be printed before sane_open has succeeded.

If we use SANE_String sane_verbose_error() (no handle parameter), we could ask for error messages even in sane_open. However, SANE allows to open several scanners at the same time so this could lead to confusion. Also, how does the dll backend know which backend to ask for the error message if no handle is given?

How to translate individual error messages?

See also SANE_Status.

sane_download_translation, sane_download_backend_file

The idea of using a SANE API function to download backend translations and backend documentation is that the frontend doesn't need to care about paths to these files. Also it works over the network. So the client only has the net backend (and no documentation/translation for other backends) and all the data is on the server. On the other hand the current implementation works quite well (translations are installed by sane-backends). 95 % of the backends don't have HTML documentation so we had to move from man page to HTML if we wanted to use that approach.

My proposal is to keep the current situation concerning translations (and only define formats and filenames in the standard). Concerning documentation, maybe just add a member "doc_path" to SANE_Device so the frontend can use any browser it likes? However, this means that we have to place the docs and translations on the client as it's the case now.

In the following paragraphs some other approaches to download translations/documentation are explained.

Download backend translation and documentation: The Download function does not care about the file format, this probably also has to be defined in the sane standard. E.g.: sane_download_backend_file(filename). The backend has to load the file from a fixed directory. The path to the directory has to contain the backend name, e.g: /usr/local/share/sane/sane-umax/ The frontend can not change the directory due to security! That may cause trouble with network scanning!

Rethink the whole idea of downloading. Maybe there should just be a function to get the .gmo file for a specific language. E.g. sane_read_gmo (SANE_String language, SANE_Byte * buffer, SANE_Int * size) or even SANE_Byte * sane_get_translation (SANE_String language). Does the latter work over the net (local copy needed)?

Or use a more general approach: SANE_Status sane_get_aux_info (SANE_String * aux_info, SANE_String_Const lang, SANE_Int info_type). info_type defines if a translation or backend documentation is selected. Format for documentation is HTML without images? However, this way only one html file per backend can be transmitted.

sane_get_device_info (rejected)

Add sane_get_device_info function that allows the frontend to ask for information about all involved backends and meta backends that are used. Is this still needed with version_code in sane_device and the new parameter in sane_open?

sane_extended_call / sane_extended_callback (rejected)

I don`t like this because it makes it too simple to add proprietary functions that are not defined in the sane standard.

Split sane_cancel and add sane_end

Currently sane_cancel has two meanings: "The scan is now finished" and "Stop the scan immediately". It would be much cleaner if these functions were separate.

Well-known options

resolution, x-resolution, y-resolution (accepted)

preview, new frame types (accepted)

geometry, temporarily wrong (accepted)

new: depth (accepted)

new: mode (accepted)

new: source (accepted)

new: threshold (accepted)

new: gamma-table (accepted)

new: analog-gamma (accepted)

new: shadow (accepted)

new: highlight (accepted)

new: lamp-on, lamp-off (accepted)

new: scanner-buttons-* (further discussion)

new: batch-scan (further discussion)

Option "batch-scan" should be of type SANE_Int. Define SANE_BATCH_* values in sane_opt.h: 0 = no batch, 1 = ... . Strings shouldn't be used for such switches.

focus-position-x, -y

Set focus position. I don't know what's meant by this. Details please!

Manual focussing

An option to use manual focus on film scanners was proposed. Details?

multi-pass

Multi pass for film scanners. number of passes (either native or EMULATED) SANE_TYPE_INT, word_list or range.

image-number

Direct selection of image number, e.g. for film scanners -> SANE_TYPE_INT

total-images

Number of images to be scanned, e.g. for film scanners. Read-only? Do we need this option with SANE_PFLAG_MORE_IMAGES?

exposure-time

Image type/compression type

Many scanners are able to generate scan data in different formats, e.g. raw and jpeg. There should be a well-known option to select which kind of image data is used. E.g. a string list with well known values for "Raw", "JPEG", "TIFF", whatever.

Miscellaneous

Message callbacks

Let backend display a frontend-info or -selection (ok/cancel) dialog-box (e.g. "Calibration in progress: wait 10/9/8/... seconds") this has to be done with a callback, e.g.: sane_frontend_dialog_display(**window, text, ok_text, cancel_text, backend_dialog_callback_function) sane_frontend_dialog_close(window) the frontend function has to be implemented in a way that the backend can change the text. A good place to define the callback functions could be sane_init, where already the authorization_callback is defined.

Callbacks don't work with the SANE network protocol. At least you can't call the callback if no SANE function is currently running. An exception is the authorization callback as that's only needed before calling some specific functions. So those functions return "authorization needed" over the net. It's not clear yet if it's possible to implement message callbacks over the net at all. Even if it is, the code will be complicated and bloated because we need to return an error for the RPC and then restart the currently running code at the same position where the callback occurred.

Flag to reload options after scan (rejected)

Give backend the chance to tell the frontend while/after scan that the options have changed (e.g. film scanner reduces number of available images): may be a flag (comparable to int *i in sane_control_option).

If such a feature is really necessary and SANE_CAP_AUTO_POLL is not enough, we could force the frontend to reload the descriptors after every scan. Otherwise we had to add a flag to sane_cancel which I think is really unclean.

Implementation notes

The idea is to add a section with implementation notes like the text that is currently in backend-writing.txt. My personal view is that everything a backend programmer needs to know should go into the standard. Everything that concerns the sane-backends distribution, coding style, general coding tips etc. should go int backend-writing.txt.

Internationalization/documentation

Marking of translatable texts (further discussion)

See section 4.2.10 ff for details. I don't think that the details of the marking should be mentioned in the standard as they are backend-dependant and not part of the API. Only mention that options are in English and that option names must not be translated.

Recommended file formats for internationalization (further discussion)

In sane_i18n definition files: *.po, default translation tables: *.(g)mo. (section 4.2.10.3). It's ok to define the formats but the way how to use these files needn't be defined (maybe a gettext to something else converter is used).

Network protocol

Update from API changes

The network protocol must be updated to reflect the changes to the SANE standard.

Use UDP instead of TCP?

port number selection

Let the server define a port number for the data port to avoid firewall problems?

Avoid data port

Maybe it's possible to avoid the data port at all?

Document RPCs

Add the numbers of the RPCs to the standard, Maybe the standard needs some more details of the network interface, too.

Callbacks

Check if the callbacks are implemented according to the standard.

Lamp shut off (rejected)

Saned or a stand alone "turn lamp off daemon" should get an internal timer to turn off the lamp of some scanners. This has to be defined closer. May be it is necessary to find out how long a scanner has not been used. For this saned needs a function like sane_get_offline_time()...

This should be done in the backend.

Grammar/spelling/formalities

Update contact information

Add clear preliminary marker

Set change markers of INVALIDATE_PREVIEW

Check grammar & spelling

Check too long lines

Check defective references

Update index

Check that all headlines are in capital letters


SANE 2 standard page
Documentation page
SANE homepage

$Date$ $Author$