Mares Smart Dive Computer + Bluelink pro

[Jef Driesen]

On 2018-09-26 19:40, Linus Torvalds wrote:
> Jef, what are the semantics for
> 
>         ret = dc_iostream_read(iostream, buf, sizeof(buf), NULL);
> 
> meant to be when there is only a partial read? Right now it returns
> DC_STATUS_SUCCESS and garbage in the end of "buf". Which really does
> seem wrong. The caller has no way to know that it got a just a partial
> reply..

The semantics depends on the transport type, and not whether the actual 
parameter is NULL or not:

For a stream based transport (e.g. serial, irda and rfcomm), the 
implementation should *always* try to read the requested size. Thus if 
the operation is successful (DC_STATUS_SUCCESS), the value of the actual 
parameter is guaranteed to be equal to the requested size, and hence you 
don't really need it. But if the operation fails for some reason, for 
example due to a timeout or some other I/O error, then an error should 
be returned. However, a failure does not necessary mean nothing got 
transferred at all. Therefore, the actual value should contain the 
number of bytes that were transferred successfully. This allows the 
caller to resume the operation after a partially failed transfer. (Note 
that most dive computer backends treat all errors as fatal errors, and 
in that case passing NULL is fine.)

The main reason why the iostream code always passes a non NULL pointer 
to the underlying implementation is because it needs the size for the 
logging.

For a packet based transport (e.g. ble and usbhid), the implementation 
should return a packet and indicate the size of that packet in the 
actual parameter. Thus the actual parameter is mandatory, and passing in 
a NULL pointer is indeed a very bad idea here.

Jef