63f5a4d652
The dc_parser_set_data() function allows to re-use a parser object for multiple dives. The advantages of this feature are actually very limited in practice. The reduction in memory consumption is almost negligible, because the amount of internal state in the parser is typically very small. But the implementation requires some additional complexity because each backend needs code to reset its internal state. Therefore, the function is removed and the data and size needs to be passed directly to the dc_parser_new() and dc_parser_new2() functions instead. Because keeping a reference to the data has also caused issues in the past, especially for applications implemented in a garbage collected language, the data will now also get copied internally.
160 lines
4.6 KiB
Groff
160 lines
4.6 KiB
Groff
.\"
|
|
.\" libdivecomputer
|
|
.\"
|
|
.\" Copyright (C) 2017 Kristaps Dzonsons <kristaps@bsd.lv>
|
|
.\"
|
|
.\" This library is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU Lesser General Public
|
|
.\" License as published by the Free Software Foundation; either
|
|
.\" version 2.1 of the License, or (at your option) any later version.
|
|
.\"
|
|
.\" This library is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
.\" Lesser General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU Lesser General Public
|
|
.\" License along with this library; if not, write to the Free Software
|
|
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
|
|
.\" MA 02110-1301 USA
|
|
.\"
|
|
.Dd January 5, 2017
|
|
.Dt DIVECOMPUTER 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm divecomputer
|
|
.Nd communicate with dive computers
|
|
.Sh LIBRARY
|
|
.Lb libdivecomputer
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm divecomputer
|
|
library is a cross-platform and open source library for communication
|
|
with dive computers from various manufacturers.
|
|
Systems interfacing with
|
|
.Nm divecomputer
|
|
must link with
|
|
.Fl l Ns Ar divecomputer .
|
|
.Pp
|
|
A system wishing to query dives in a dive computer generally follows
|
|
these steps:
|
|
.Bl -enum
|
|
.It
|
|
Create a new context with
|
|
.Xr dc_context_new 3
|
|
to initialize the library. Logging can be controlled with
|
|
.Xr dc_context_set_logfunc 3
|
|
and
|
|
.Xr dc_context_set_loglevel 3 .
|
|
.It
|
|
Find a descriptor for their dive computer by iterating through
|
|
.Xr dc_descriptor_iterator 3
|
|
and searching by name, vendor, or product family.
|
|
.It
|
|
Find the transport to use for the communication. To determine the supported transports use
|
|
.Xr dc_descriptor_get_transports 3 .
|
|
.It
|
|
Find the hardware device corresponding to the connected dive computer by iterating through
|
|
.Xr dc_usbhid_iterator_new 3 ,
|
|
.Xr dc_serial_iterator_new 3 ,
|
|
.Xr dc_irda_iterator_new 3
|
|
or
|
|
.Xr dc_bluetooth_iterator_new 3 .
|
|
.It
|
|
Open the transport communcations with
|
|
.Xr dc_usbhid_open 3 ,
|
|
.Xr dc_serial_open 3 ,
|
|
.Xr dc_irda_open 3
|
|
or
|
|
.Xr dc_bluetooth_open 3 .
|
|
.It
|
|
Open a connection to the dive computer with
|
|
.Xr dc_device_open 3 .
|
|
Optionally use
|
|
.Xr dc_device_set_events 3 ,
|
|
.Xr dc_device_set_fingerprint 3
|
|
and
|
|
.Xr dc_device_set_cancel 3
|
|
to set the logging events, last-seen fingerprint, and cancel routine,
|
|
respectively.
|
|
.It
|
|
Iterate over all dives with
|
|
.Xr dc_device_foreach 3 .
|
|
.It
|
|
For each iterated dive, create a new parser with
|
|
.Xr dc_parser_new 3 .
|
|
.It
|
|
Get attributes of the parsed dive with
|
|
.Xr dc_parser_get_field 3 .
|
|
.It
|
|
Iterate through the dive's samples (recorded data) with
|
|
.Xr dc_parser_samples_foreach 3 .
|
|
.El
|
|
.Sh RETURN VALUES
|
|
Most
|
|
.Nm libdivecomputer
|
|
functions return with a
|
|
.Vt dc_status_t
|
|
type with the following possible values:
|
|
.Bl -tag -width Ds
|
|
.It Dv DC_STATUS_SUCCESS
|
|
Completion with success: not an error.
|
|
.It Dv DC_STATUS_DONE
|
|
End of an iterator: not an error.
|
|
.It Dv DC_STATUS_UNSUPPORTED
|
|
Feature not implemented or not supported by device.
|
|
.Po
|
|
The difference depends on the context.
|
|
Since
|
|
.Nm libdivecomputer
|
|
is largely
|
|
based on reverse engineering, we often can't even tell them apart.
|
|
.Pc
|
|
.It Dv DC_STATUS_INVALIDARGS
|
|
Invalid parameter.
|
|
Usually indicates caller bug.
|
|
.It Dv DC_STATUS_NOMEMORY
|
|
Out of memory.
|
|
.It Dv DC_STATUS_NODEVICE
|
|
Device not found.
|
|
In this context the device refers to the low-level communication device
|
|
(serial, bluetooth, irda, etc), not the dive computer.
|
|
In most cases, and especially with serial communication, we can't detect
|
|
whether the dive computer is present.
|
|
This is always detected indirectly: no response is received, and thus a
|
|
timeout error.
|
|
.It Dv DC_STATUS_NOACCESS
|
|
Access denied (again, to the low-level communication device).
|
|
.It Dv DC_STATUS_TIMEOUT
|
|
See
|
|
.Dv DC_STATUS_NODEVICE .
|
|
.It Dv DC_STATUS_IO
|
|
Any other I/O error.
|
|
.It Dv DC_STATUS_PROTOCOL
|
|
Encountered unexpected data in the communication protocol data packets,
|
|
e.g., while downloading.
|
|
.It Dv DC_STATUS_DATAFORMAT
|
|
Encountered unexpected data in the interpretation of data contents,
|
|
e.g., while parsing.
|
|
.It Dv DC_STATUS_CANCELLED
|
|
Returned when the cancel callback requested to cancel the operation.
|
|
Note that cancellation is only checked at specific (safe) points, so
|
|
it's certainly possible it may not get noticed immediately and still
|
|
return
|
|
.Dv DC_STATUS_SUCCESS .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr dc_context_new 3 ,
|
|
.Xr dc_descriptor_iterator 3
|
|
.Xr dc_device_open 3
|
|
.Xr dc_parser_new 3
|
|
.Sh AUTHORS
|
|
The
|
|
.Lb libdivecomputer
|
|
library was written by
|
|
.An Jef Driesen ,
|
|
.Mt jef@libdivecomputer.org .
|
|
These manpages were written by
|
|
.An Kristaps Dzonsons ,
|
|
.Mt kristaps@bsd.lv .
|