[sane-devel] Byte ordering

[Ralph Little]

Hi,
So I was looking through the SANE API specification and there *is* some
guidance on byte order. It is just separated from the function definitions.
In the section "The SANE Environment":
https://sane-project.gitlab.io/standard/environment.html#sec-imageformat

"In the latter case, the bytes of each sample value are transmitted in the
machine’s native byte order."

So I guess that settles that.

Cheers,
Ralph

On Wed, Jun 4, 2025 at 9:28 AM Ralph Little <skelband at gmail.com> wrote:

> Hi,
> Thanks, I will check that out.
>
> Cheers,
> Ralph
>
> On Wed, Jun 4, 2025 at 9:25 AM m. allan noah <kitno455 at gmail.com> wrote:
>
>> 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/20250607/65731e71/attachment.htm>