1DIVECOMPUTER(3)          BSD Library Functions Manual          DIVECOMPUTER(3)
2

NAME

4     divecomputer — communicate with dive computers
5

LIBRARY

7     library “libdivecomputer”
8

DESCRIPTION

10     The divecomputer library is a cross-platform and open source library for
11     communication with dive computers from various manufacturers.  Systems
12     interfacing with divecomputer must link with -ldivecomputer.
13
14     A system wishing to query dives in a dive computer generally follows
15     these steps:
16
17     1.   Create a new context with dc_context_new(3).  This supplies a parse
18          context: logging, error handling, etc.  Override the values with
19          dc_context_set_logfunc(3) and dc_context_set_loglevel(3).
20
21     2.   Find a descriptor for their dive computer by iterating through
22          dc_descriptor_iterator(3) and searching by name, vendor, or product
23          family.
24
25     3.   Open the hardware device to which the dive computer is connected
26          with dc_device_open(3), then invoke dc_device_set_events(3),
27          dc_device_set_fingerprint(3), and dc_device_set_cancel(3) to set the
28          logging events, last-seen fingerprint, and cancel routine, respec‐
29          tively.
30
31     4.   Iterate over all dives with dc_device_foreach(3).
32
33     5.   For each iterated dive, create a new parser with dc_parser_new(3)
34          and set the parsed data with dc_parser_set_data(3).
35
36     6.   Get attributes of the parsed dive with dc_parser_get_field(3), then
37          iterate through the dive's samples (recorded data) with
38          dc_parser_samples_foreach(3).
39

RETURN VALUES

41     Most libdivecomputer functions return with a dc_status_t type with the
42     following possible values:
43
44     DC_STATUS_SUCCESS
45             Completion with success: not an error.
46
47     DC_STATUS_DONE
48             End of an iterator: not an error.
49
50     DC_STATUS_UNSUPPORTED
51             Feature not implemented or not supported by device.  (The
52             difference depends on the context.  Since libdivecomputer is
53             largely based on reverse engineering, we often can't even tell
54             them apart.)
55
56     DC_STATUS_INVALIDARGS
57             Invalid parameter.  Usually indicates caller bug.
58
59     DC_STATUS_NOMEMORY
60             Out of memory.
61
62     DC_STATUS_NODEVICE
63             Device not found.  In this context the device refers to the low-
64             level communication device (serial, bluetooth, irda, etc), not
65             the dive computer.  In most cases, and especially with serial
66             communication, we can't detect whether the dive computer is
67             present.  This is always detected indirectly: no response is
68             received, and thus a timeout error.
69
70     DC_STATUS_NOACCESS
71             Access denied (again, to the low-level communication device).
72
73     DC_STATUS_TIMEOUT
74             See DC_STATUS_NODEVICE.
75
76     DC_STATUS_IO
77             Any other I/O error.
78
79     DC_STATUS_PROTOCOL
80             Encountered unexpected data in the communication protocol data
81             packets, e.g., while downloading.
82
83     DC_STATUS_DATAFORMAT
84             Encountered unexpected data in the interpretation of data con‐
85             tents, e.g., while parsing.
86
87     DC_STATUS_CANCELLED
88             Returned when the cancel callback requested to cancel the opera‐
89             tion.  Note that cancellation is only checked at specific (safe)
90             points, so it's certainly possible it may not get noticed immedi‐
91             ately and still return DC_STATUS_SUCCESS.
92

SEE ALSO

94     dc_buffer_new(3)
95

AUTHORS

97     The library “libdivecomputer” library was written by Jef Driesen,
98     jef@libdivecomputer.org.  These manpages were written by
99     Kristaps Dzonsons, kristaps@bsd.lv.
100
101BSD                             January 5, 2017                            BSD