sane-project-website/sane2/sane2-todo.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>