[sane-devel] Byte ordering

[m. allan noah]

A quote from fujitsu.c that seems relevant:

*
 * @@ Section 5 - SANE cleanup functions
 */
/*
 * Cancels a scan.
 *
 * It has been said on the mailing list that sane_cancel is a bit of a
 * misnomer because it is routinely called to signal the end of a
 * batch - quoting David Mosberger-Tang:
 *
 * > In other words, the idea is to have sane_start() be called, and
 * > collect as many images as the frontend wants (which could in turn
 * > consist of multiple frames each as indicated by frame-type) and
 * > when the frontend is done, it should call sane_cancel().
 * > Sometimes it's better to think of sane_cancel() as "sane_stop()"
 * > but that name would have had some misleading connotations as
 * > well, that's why we stuck with "cancel".
 *
 * The current consensus regarding duplex and ADF scans seems to be
 * the following call sequence: sane_start; sane_read (repeat until
 * EOF); sane_start; sane_read...  and then call sane_cancel if the
 * batch is at an end. I.e. do not call sane_cancel during the run but
 * as soon as you get a SANE_STATUS_NO_DOCS.
 *
 * From the SANE spec:
 * This function is used to immediately or as quickly as possible
 * cancel the currently pending operation of the device represented by
 * handle h.  This function can be called at any time (as long as
 * handle h is a valid handle) but usually affects long-running
 * operations only (such as image is acquisition). It is safe to call
 * this function asynchronously (e.g., from within a signal handler).
 * It is important to note that completion of this operaton does not
 * imply that the currently pending operation has been cancelled. It
 * only guarantees that cancellation has been initiated. Cancellation
 * completes only when the cancelled call returns (typically with a
 * status value of SANE_STATUS_CANCELLED).  Since the SANE API does
 * not require any other operations to be re-entrant, this implies
 * that a frontend must not call any other operation until the
 * cancelled operation has returned.
 */


On Wed, Jun 4, 2025 at 12:06 PM Ralph Little <skelband at gmail.com> wrote:

> Hi,
> BTW, just on that note, something that has bothered me is that the SANE
> API specification doesn't make the ADF multi-page scanning process super
> clear in terms of result codes, sequence etc. I will perhaps also review
> that section to see if additional detail could be added to make it more
> concrete.
>
> Any changes I propose, I will offer them up here for review before
> updating the document.
>
> Cheers,
> Ralph
>
> On Wed, Jun 4, 2025 at 9:02 AM Ralph Little <skelband at gmail.com> wrote:
>
>> Hi,
>> OK, I will draft something up for the standard.
>>
>> If there is anything else to update the standard with, perhaps people
>> could let me know.
>> Just to be clear, I am not changing the interface with this update, just
>> adding come clarification, so if anybody feels that there is anything else
>> unclear in the standard, they should possibly raise it now.
>>
>> I will add address this on the weekend.
>>
>> Cheers,
>> Ralph
>>
>> On Wed, Jun 4, 2025 at 8:57 AM m. allan noah <kitno455 at gmail.com> wrote:
>>
>>> Makes sense to me.
>>>
>>> On Wed, Jun 4, 2025 at 10:12 AM Ralph Little <skelband at gmail.com> wrote:
>>>
>>>> Hi,
>>>>
>>>> On Tue, Jun 3, 2025 at 11:36 PM <sane-devel at symme.link> wrote:
>>>>
>>>>> On Tue, Jun 03, 2025 at 10:00:45PM -0700, Ralph Little wrote:
>>>>> > On Tue, Jun 3, 2025 at 9:54 PM James Ring <sjr at jdns.org> wrote:
>>>>> > > On Tue, Jun 3, 2025 at 9:46 PM Ralph Little <skelband at gmail.com>
>>>>> wrote:
>>>>> > >> Someone has asked the question about byte order in multi-byte
>>>>> image data
>>>>> > >> that we might get from a SANE backend.
>>>>>
>>>>> Hi, it's me, I had the question.
>>>>>
>>>>> > >> It is not enough to assume the local machine byte order since we
>>>>> may get
>>>>> > >> data through the net backend from a remote machine with a
>>>>> different byte
>>>>> > >> order.
>>>>>
>>>>> The `net` backend explicitly swaps to local machine byte order:
>>>>>
>>>>> https://gitlab.com/sane-project/backends/-/blob/master/backend/net.c?ref_type=heads#L2356-2362
>>>>>
>>>>> So, it does seem like the de facto standard is that backends produce
>>>>> data in local machine byte order.
>>>>>
>>>>> (The protocol documentation reinforces this as a standard:
>>>>>
>>>>
>>>> Agreed. Perhaps this is something we should add to the SANE API
>>>> specification?
>>>> Allan, do you concur?
>>>>
>>>> Cheers,
>>>> Ralph
>>>>
>>>
>>>
>>> --
>>> "well, I stand up next to a mountain- and I chop it down with the edge
>>> of my hand"
>>>
>>

-- 
"well, I stand up next to a mountain- and I chop it down with the edge of
my hand"
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/sane-devel/attachments/20250604/027b5e84/attachment.htm>