[sane-devel] Byte ordering

Sat Jun 7 19:58:28 BST 2025

I would recommend referencing said document in the relevant API documents.
Something along the lines of "Bytes in each sample value are transmitted in
the machine's native byte order per the 'SANE Environment' document."  That
way if someone skips that document initially, they'll go back to it.

On Sat, Jun 7, 2025 at 2:54 PM Ralph Little <skelband at gmail.com> wrote:

> 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"
>>>
>>

-- 
Kelly "STrRedWolf" Price
http://redwolf.ws
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/sane-devel/attachments/20250607/1eae97e0/attachment.htm>