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.
"sane-backends2" (-->sane-backends2-2.x.y) or sane2-backends (-->sane2backends-2.x.y)?
"sane/sane2.h", "sane/sane-2.h", "sane2/sane.h" or "sane/sane."?
"libsane2-dll.so" or "libsane-dll2.so"?
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).
"/etc/sane2.d/dll.conf"? "/etc/sane.d/dll2.conf" doesn't work because there are already backends with numbers (microtek2.conf).
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.
I don't see any reason to keep SANE_Parameters in the "Operations" section as all the other data types are in "Data Types".
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.
Lineart: 1 = black, other modes: 0 = black. Reason: History.
More than one frame is used e.g. for 3-pass scanners. Maybe also film scanners use a separate frame for IR data?
Some old Mustek scanners support this mode (color 1 bit). But it's not really useful. So 1 bit color is not allowed anymore.
Make it compatible to SANE 1. Adds more_images, new_page, front/backside info, 28 more flags available.
Add dpi_x, dpi_y, proposed_filename, formatdesc, channels_per_image.
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]?
These members have been added:
Add a pointer "next" to the device handle to make linked lists instead of arrays. Is this incompatible change really useful?
E.g. out of memory in scanner, file not found, firmware not found, some kind of error concerning options, power failure of scanner,...
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.
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_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.
Currently there are no error codes.
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.
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.
Define what parts in a option_descriptor may be changed after it has been set up and passed to the frontend.
Maybe add size to list of members that can be changed?
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.
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.
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.
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?
I don`t like this because it makes it too simple to add proprietary functions that are not defined in the sane standard.
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.
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.
Set focus position. I don't know what's meant by this. Details please!
An option to use manual focus on film scanners was proposed. Details?
Multi pass for film scanners. number of passes (either native or EMULATED) SANE_TYPE_INT, word_list or range.
Direct selection of image number, e.g. for film scanners -> SANE_TYPE_INT
Number of images to be scanned, e.g. for film scanners. Read-only? Do we need this option with SANE_PFLAG_MORE_IMAGES?
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.
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.
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.
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.
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.
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).
The network protocol must be updated to reflect the changes to the SANE standard.
Let the server define a port number for the data port to avoid firewall problems?
Maybe it's possible to avoid the data port at all?
Add the numbers of the RPCs to the standard, Maybe the standard needs some more details of the network interface, too.
Check if the callbacks are implemented according to the standard.
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.