kopia lustrzana https://gitlab.com/sane-project/website
542 wiersze
22 KiB
HTML
542 wiersze
22 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<title>SANE - TODO List for Standard Version 2</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
|
|
<meta name="author" content="Henning Meier-Geinitz">
|
|
<meta name="keywords" content="sane, standard, 2, sane2, documentation">
|
|
<meta name="description" content="Development of the SANE2 standard">
|
|
<link href="mailto:hmg-guest@users.alioth.debian.org" rev="made">
|
|
<link href="favicon.ico" type="image/x-icon" rel="icon">
|
|
<link href="favicon.ico" type="image/x-icon" rel="shortcut icon">
|
|
<link href="todo.css" rel="stylesheet" rev="text/css">
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
<center>
|
|
<a href="http://www.sane-project.org" target="_top"><img
|
|
src="../images/sane.png" alt="SANE" height="117" width="346" border="0"></a>
|
|
</center>
|
|
|
|
<center>
|
|
<h1>SANE - TODO list for standard version 2</h1>
|
|
</center>
|
|
|
|
<p class="noindent">
|
|
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.
|
|
</p>
|
|
<h4 class="accepted">Accepted: The change is in the latest standard</h4>
|
|
<h4 class="discussed">Further discussion: The change is in the standard but
|
|
there are still problems</h4>
|
|
<h4 class="rejected">Rejected: the change won't be included in the
|
|
standard</h4>
|
|
<h4>(no status): neither included nor rejected yet</h4>
|
|
|
|
<h2>Naming and versioning</h2>
|
|
<h4>Archive/CVS name</h4>
|
|
<p>
|
|
"sane-backends2" (-->sane-backends2-2.x.y) or sane2-backends
|
|
(-->sane2backends-2.x.y)?
|
|
</p>
|
|
<h4>Header file</h4>
|
|
<p>
|
|
"sane/sane2.h", "sane/sane-2.h", "sane2/sane.h" or "sane/sane."?
|
|
</p>
|
|
<h4>Libraries</h4>
|
|
<p>
|
|
"libsane2-dll.so" or "libsane-dll2.so"?
|
|
</p>
|
|
<h4>Standard</h4>
|
|
<p>
|
|
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).
|
|
</p>
|
|
<h4>Config file names</h4>
|
|
<p>
|
|
"/etc/sane2.d/dll.conf"? "/etc/sane.d/dll2.conf" doesn't work because
|
|
there are already backends with numbers (microtek2.conf).
|
|
</p>
|
|
<h2>SANE data types</h2>
|
|
<h3>SANE_Char</h3>
|
|
<h4>UTF-8 format</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>SANE_Parameters</h3>
|
|
<h4>Move SANE_Parameters to data type section</h4>
|
|
<p>
|
|
I don't see any reason to keep SANE_Parameters in the "Operations" section
|
|
as all the other data types are in "Data Types".
|
|
</p>
|
|
<h4 class="accepted">Changes to frames (SANE_Parameters.format) (accepted)</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<h4 class="accepted">define bit order of 1 bit modes (accepted)</h4>
|
|
<p>
|
|
Lineart: 1 = black, other modes: 0 = black. Reason: History.
|
|
<p>
|
|
<h4>Remove multi-frame paradigm at all</h4>
|
|
<p>
|
|
More than one frame is used e.g. for 3-pass scanners. Maybe also film
|
|
scanners use a separate frame for IR data?
|
|
</p>
|
|
<h4 class="accepted">Remove multi-channel 1 bit mode (accepted)</h4>
|
|
<p>
|
|
Some old Mustek scanners support this mode (color 1 bit). But it's not
|
|
really useful. So 1 bit color is not allowed anymore.
|
|
</p>
|
|
<h4 class="accepted">Add flags to SANE_Parameters.flags (accepted)</h4>
|
|
<p>
|
|
Make it compatible to SANE 1. Adds more_images, new_page, front/backside
|
|
info, 28 more flags available.
|
|
</p>
|
|
<h4 class="accepted">More informational values (accepted)</h4>
|
|
<p>
|
|
Add dpi_x, dpi_y, proposed_filename, formatdesc, channels_per_image.
|
|
</p>
|
|
<h4 class="discussed">32 bytes for future extension (set to 0) (further discussion)</h4>
|
|
<p>
|
|
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]?
|
|
</p>
|
|
|
|
<h3>SANE_Device</h3>
|
|
<h4 class="accepted">Add informational and reserved members (accepted)</h4>
|
|
<p>
|
|
These members have been added:
|
|
</p>
|
|
<ul>
|
|
<li>email_backend_author (string)
|
|
<li>device_location (string)
|
|
<li>comment (string)
|
|
<li>reserved_string (string)
|
|
<li>version_code (integer)
|
|
<li>backend_capability_flags (integer)
|
|
<li>reserved_int (integer)
|
|
</ul>
|
|
|
|
<h4 class="rejected">Next pointer (rejected)</h4>
|
|
<p>
|
|
Add a pointer "next" to the device handle to make linked lists instead of
|
|
arrays. Is this incompatible change really useful?
|
|
</p>
|
|
|
|
<h3>SANE_Status</h3>
|
|
<h4>Add more errors</h4>
|
|
<p>E.g. out of memory in scanner, file not found, firmware not found, some
|
|
kind of error concerning options, power failure of scanner,...</p>
|
|
<h4>Change SANE_Status to (also) contain textual error messages</h4>
|
|
<p>
|
|
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?
|
|
</p>
|
|
|
|
<p>
|
|
One proposal is:
|
|
</p>
|
|
<pre>
|
|
typedef struct {
|
|
int code;
|
|
char *msg;
|
|
} SANE_Status;
|
|
</pre>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
The 2 LSB will always correspond to a SANE status.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
|
|
<h3>SANE_Option_Descriptor</h3>
|
|
<h4 class="accepted">SANE_CAP_ADVANCED for a group (accepted)</h4>
|
|
<h4 class="accepted">SANE_CAP_ALWAYS_SETTABLE (accepted)</h4>
|
|
<h4 class="accepted">SANE_CAP_HIDDEN (accepted)</h4>
|
|
<h4>SANE_CAP_AUTO_POLL</h4>
|
|
<p>
|
|
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?)
|
|
</p>
|
|
|
|
<h2>SANE API functions</h2>
|
|
<h3>sane_open</h3>
|
|
<h4 class="accepted">New parameter: sane_device (accepted)</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>sane_get_parameters</h3>
|
|
<h4>Define error codes for sane_get_parameters</h4>
|
|
<p>
|
|
Currently there are no error codes.
|
|
</p>
|
|
<h4>Move SANE_Parameters to data type section</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>sane_init</h3>
|
|
<h4>Define return value of sane_init</h4>
|
|
|
|
<h3>sane_get_select_fd</h3>
|
|
<h4>Implementation note for select_fd</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>sane_control_option</h3>
|
|
<h4 class="accepted">Which parts of an option descriptor can be changed at
|
|
run-time?</h4>
|
|
<p>
|
|
Define what parts in a option_descriptor may be changed after it has been
|
|
set up and passed to the frontend.
|
|
<p>
|
|
<h4>More members of option descriptor that should be changeable</h4>
|
|
<p>
|
|
Maybe add size to list of members that can be changed?
|
|
</p>
|
|
|
|
<h4 class="accepted">SANE_INFO_INVALIDATE_PREVIEW (accepted)</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>sane_strstatus</h3>
|
|
<h4 class="accepted">Remove "const" (accepted)</h4>
|
|
|
|
<h3>New SANE API functions</h3>
|
|
|
|
<h4>sane_verbose_error</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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?
|
|
</p>
|
|
<p>
|
|
How to translate individual error messages?
|
|
</p>
|
|
<p>
|
|
See also SANE_Status.
|
|
</p>
|
|
|
|
<h4>sane_download_translation, sane_download_backend_file</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
In the following paragraphs some other approaches to download
|
|
translations/documentation are explained.
|
|
</p>
|
|
<p>
|
|
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!
|
|
</p>
|
|
<p>
|
|
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)?
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<h4 class="rejected">sane_get_device_info (rejected)</h4>
|
|
<p>
|
|
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?
|
|
</p>
|
|
|
|
<h4 class="rejected">sane_extended_call / sane_extended_callback
|
|
(rejected)</h4>
|
|
<p>
|
|
I don`t like this because it makes it too simple to add proprietary
|
|
functions that are not defined in the sane standard.
|
|
</p>
|
|
|
|
<h4>Split sane_cancel and add sane_end</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h2>Well-known options</h2>
|
|
<h4 class="accepted">resolution, x-resolution, y-resolution (accepted)</h4>
|
|
<h4 class="accepted">preview, new frame types (accepted)</h4>
|
|
<h4 class="accepted">geometry, temporarily wrong (accepted)</h4>
|
|
<h4 class="accepted">new: depth (accepted)</h4>
|
|
<h4 class="accepted">new: mode (accepted)</h4>
|
|
<h4 class="accepted">new: source (accepted)</h4>
|
|
<h4 class="accepted">new: threshold (accepted)</h4>
|
|
<h4 class="accepted">new: gamma-table (accepted)</h4>
|
|
<h4 class="accepted">new: analog-gamma (accepted)</h4>
|
|
<h4 class="accepted">new: shadow (accepted)</h4>
|
|
<h4 class="accepted">new: highlight (accepted)</h4>
|
|
<h4 class="accepted">new: lamp-on, lamp-off (accepted)</h4>
|
|
<h4 class="discussed">new: scanner-buttons-* (further discussion)</h4>
|
|
<h4 class="discussed">new: batch-scan (further discussion)</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<h4>focus-position-x, -y</h4>
|
|
<p>
|
|
Set focus position. I don't know what's meant by this. Details please!
|
|
</p>
|
|
|
|
<h4>Manual focussing</h4>
|
|
<p>
|
|
An option to use manual focus on film scanners was proposed. Details?
|
|
</p>
|
|
|
|
<h4>multi-pass</h4>
|
|
<p>
|
|
Multi pass for film scanners. number of passes (either native or
|
|
EMULATED) SANE_TYPE_INT, word_list or range.
|
|
</p>
|
|
|
|
<h4>image-number</h4>
|
|
<p>
|
|
Direct selection of image number, e.g. for film scanners -> SANE_TYPE_INT
|
|
</p>
|
|
|
|
<h4>total-images</h4>
|
|
<p>
|
|
Number of images to be scanned, e.g. for film scanners. Read-only? Do we
|
|
need this option with SANE_PFLAG_MORE_IMAGES?
|
|
</p>
|
|
|
|
<h4>exposure-time</h4>
|
|
|
|
<h4>Image type/compression type</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h2>Miscellaneous</h2>
|
|
<h4">Message callbacks</h4>
|
|
<p>
|
|
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.
|
|
<p>
|
|
<p>
|
|
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.
|
|
<p>
|
|
|
|
<h4 class="rejected">Flag to reload options after scan (rejected)</h4>
|
|
<p>
|
|
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).
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<h4>Implementation notes</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>Internationalization/documentation</h3>
|
|
<h4 class="discussed">Marking of translatable texts (further
|
|
discussion)</h4>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<h4 class="discussed">Recommended file formats for internationalization
|
|
(further discussion)</h4>
|
|
<p>
|
|
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).
|
|
</p>
|
|
|
|
<h3>Network protocol</h3>
|
|
<h4>Update from API changes</h4>
|
|
<p>
|
|
The network protocol must be updated to reflect the changes to the SANE
|
|
standard.
|
|
</p>
|
|
<h4>Use UDP instead of TCP?</h4>
|
|
<h4>port number selection</h4>
|
|
<p>
|
|
Let the server define a port number for the data port to avoid firewall
|
|
problems?
|
|
</p>
|
|
<h4>Avoid data port</h4>
|
|
<p>
|
|
Maybe it's possible to avoid the data port at all?
|
|
</p>
|
|
<h4>Document RPCs</h4>
|
|
<p>
|
|
Add the numbers of the RPCs to the standard, Maybe the standard needs some
|
|
more details of the network interface, too.
|
|
</p>
|
|
<h4>Callbacks</h4>
|
|
<p>
|
|
Check if the callbacks are implemented according to the standard.
|
|
</p>
|
|
|
|
<h4 class="rejected">Lamp shut off (rejected)</h4>
|
|
<p>
|
|
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()...
|
|
<p>
|
|
<p>
|
|
This should be done in the backend.
|
|
</p>
|
|
|
|
<h2>Grammar/spelling/formalities</h2>
|
|
<h4>Update contact information</h4>
|
|
<h4>Add clear preliminary marker</h4>
|
|
<h4>Set change markers of INVALIDATE_PREVIEW</h4>
|
|
<h4>Check grammar & spelling</h4>
|
|
<h4>Check too long lines</h4>
|
|
<h4>Check defective references</h4>
|
|
<h4>Update index</h4>
|
|
<h4>Check that all headlines are in capital letters</h4>
|
|
|
|
|
|
</pre>
|
|
<hr>
|
|
|
|
<p>
|
|
<a href="index.html">SANE 2 standard page</a><br>
|
|
<a href="/docs.html">Documentation page</a><br>
|
|
<a href="/">SANE homepage</a>
|
|
</p>
|
|
<p>
|
|
<font size="-1">$Date$ $Author$</font>
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|