From 77b0cebb351835dd6c525c6bb37ef5472a822752 Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Thu, 5 Jan 2017 11:22:10 +0100 Subject: [PATCH] Document the public api with man pages --- configure.ac | 1 + doc/Makefile.am | 2 + doc/man/Makefile.am | 30 +++++ doc/man/dc_buffer_append.3 | 61 +++++++++ doc/man/dc_buffer_free.3 | 51 +++++++ doc/man/dc_buffer_get_data.3 | 64 +++++++++ doc/man/dc_buffer_get_size.3 | 59 +++++++++ doc/man/dc_buffer_new.3 | 57 ++++++++ doc/man/dc_buffer_prepend.3 | 61 +++++++++ doc/man/dc_context_free.3 | 54 ++++++++ doc/man/dc_context_new.3 | 73 +++++++++++ doc/man/dc_context_set_logfunc.3 | 98 ++++++++++++++ doc/man/dc_context_set_loglevel.3 | 90 +++++++++++++ doc/man/dc_descriptor_free.3 | 54 ++++++++ doc/man/dc_descriptor_get_product.3 | 59 +++++++++ doc/man/dc_descriptor_get_vendor.3 | 59 +++++++++ doc/man/dc_descriptor_iterator.3 | 78 +++++++++++ doc/man/dc_device_close.3 | 58 ++++++++ doc/man/dc_device_foreach.3 | 84 ++++++++++++ doc/man/dc_device_open.3 | 88 +++++++++++++ doc/man/dc_device_set_cancel.3 | 79 +++++++++++ doc/man/dc_device_set_events.3 | 125 ++++++++++++++++++ doc/man/dc_device_set_fingerprint.3 | 70 ++++++++++ doc/man/dc_iterator_free.3 | 56 ++++++++ doc/man/dc_iterator_next.3 | 55 ++++++++ doc/man/dc_parser_destroy.3 | 57 ++++++++ doc/man/dc_parser_get_datetime.3 | 60 +++++++++ doc/man/dc_parser_get_field.3 | 197 ++++++++++++++++++++++++++++ doc/man/dc_parser_new.3 | 82 ++++++++++++ doc/man/dc_parser_samples_foreach.3 | 196 +++++++++++++++++++++++++++ doc/man/dc_parser_set_data.3 | 65 +++++++++ doc/man/libdivecomputer.3 | 141 ++++++++++++++++++++ 32 files changed, 2364 insertions(+) create mode 100644 doc/man/Makefile.am create mode 100644 doc/man/dc_buffer_append.3 create mode 100644 doc/man/dc_buffer_free.3 create mode 100644 doc/man/dc_buffer_get_data.3 create mode 100644 doc/man/dc_buffer_get_size.3 create mode 100644 doc/man/dc_buffer_new.3 create mode 100644 doc/man/dc_buffer_prepend.3 create mode 100644 doc/man/dc_context_free.3 create mode 100644 doc/man/dc_context_new.3 create mode 100644 doc/man/dc_context_set_logfunc.3 create mode 100644 doc/man/dc_context_set_loglevel.3 create mode 100644 doc/man/dc_descriptor_free.3 create mode 100644 doc/man/dc_descriptor_get_product.3 create mode 100644 doc/man/dc_descriptor_get_vendor.3 create mode 100644 doc/man/dc_descriptor_iterator.3 create mode 100644 doc/man/dc_device_close.3 create mode 100644 doc/man/dc_device_foreach.3 create mode 100644 doc/man/dc_device_open.3 create mode 100644 doc/man/dc_device_set_cancel.3 create mode 100644 doc/man/dc_device_set_events.3 create mode 100644 doc/man/dc_device_set_fingerprint.3 create mode 100644 doc/man/dc_iterator_free.3 create mode 100644 doc/man/dc_iterator_next.3 create mode 100644 doc/man/dc_parser_destroy.3 create mode 100644 doc/man/dc_parser_get_datetime.3 create mode 100644 doc/man/dc_parser_get_field.3 create mode 100644 doc/man/dc_parser_new.3 create mode 100644 doc/man/dc_parser_samples_foreach.3 create mode 100644 doc/man/dc_parser_set_data.3 create mode 100644 doc/man/libdivecomputer.3 diff --git a/configure.ac b/configure.ac index 4120d7a..0164677 100644 --- a/configure.ac +++ b/configure.ac @@ -171,6 +171,7 @@ AC_CONFIG_FILES([ src/libdivecomputer.rc doc/Makefile doc/doxygen.cfg + doc/man/Makefile examples/Makefile ]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am index cd1aa3d..b917444 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1,5 @@ +SUBDIRS = man + doxygen: doxygen.cfg if HAVE_DOXYGEN $(DOXYGEN) $(DOXYFLAGS) $< diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 0000000..4b52a2f --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,30 @@ +dist_man_MANS = \ + dc_buffer_append.3 \ + dc_buffer_free.3 \ + dc_buffer_get_data.3 \ + dc_buffer_get_size.3 \ + dc_buffer_new.3 \ + dc_buffer_prepend.3 \ + dc_context_free.3 \ + dc_context_new.3 \ + dc_context_set_logfunc.3 \ + dc_context_set_loglevel.3 \ + dc_descriptor_free.3 \ + dc_descriptor_get_product.3 \ + dc_descriptor_get_vendor.3 \ + dc_descriptor_iterator.3 \ + dc_device_close.3 \ + dc_device_foreach.3 \ + dc_device_open.3 \ + dc_device_set_cancel.3 \ + dc_device_set_events.3 \ + dc_device_set_fingerprint.3 \ + dc_iterator_free.3 \ + dc_iterator_next.3 \ + dc_parser_destroy.3 \ + dc_parser_get_datetime.3 \ + dc_parser_get_field.3 \ + dc_parser_new.3 \ + dc_parser_samples_foreach.3 \ + dc_parser_set_data.3 \ + libdivecomputer.3 diff --git a/doc/man/dc_buffer_append.3 b/doc/man/dc_buffer_append.3 new file mode 100644 index 0000000..95efa44 --- /dev/null +++ b/doc/man/dc_buffer_append.3 @@ -0,0 +1,61 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_BUFFER_APPEND 3 +.Os +.Sh NAME +.Nm dc_buffer_append +.Nd append to a binary buffer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/buffer.h +.Ft int +.Fo dc_buffer_append +.Fa "dc_buffer_t *buffer" +.Fa "const unsigned char data[]" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +Append +.Fa size +bytes of +.Fa data +into the +.Fa buffer +previously allocated with +.Xr dc_buffer_new 3 . +.Sh RETURN VALUES +Returns non-zero on success or zero on memory exhaustion or if +.Fa buffer +is +.Dv NULL . +.Sh SEE ALSO +.Xr dc_buffer_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_buffer_free.3 b/doc/man/dc_buffer_free.3 new file mode 100644 index 0000000..f19ee7b --- /dev/null +++ b/doc/man/dc_buffer_free.3 @@ -0,0 +1,51 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_BUFFER_FREE 3 +.Os +.Sh NAME +.Nm dc_buffer_free +.Nd free an resizable binary buffer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/buffer.h +.Ft void +.Fo dc_buffer_free +.Fa "dc_buffer_t *buffer" +.Fc +.Sh DESCRIPTION +Frees a resizable binary buffer created with +.Xr dc_buffer_new 3 . +It's safe to pass +.Dv NULL +to this function. +.Sh SEE ALSO +.Xr dc_buffer_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_buffer_get_data.3 b/doc/man/dc_buffer_get_data.3 new file mode 100644 index 0000000..4595dc7 --- /dev/null +++ b/doc/man/dc_buffer_get_data.3 @@ -0,0 +1,64 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_BUFFER_GET_DATA 3 +.Os +.Sh NAME +.Nm dc_buffer_get_data +.Nd get the data of a buffer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/buffer.h +.Ft "unsigned char *" +.Fo dc_buffer_get_data +.Fa "dc_buffer_t *buffer" +.Fc +.Sh DESCRIPTION +Get the data used by +.Fa buffer , +previously allocated with +.Xr dc_buffer_new 3 . +For the buffer size, use +.Xr dc_buffer_get_size 3 . +.Pp +The returned pointer is not valid after subsequent calls to change the +buffer. +.Sh RETURN VALUES +Returns the data or +.Dv NULL +if +.Fa buffer +is +.Dv NULL +or no data has been allocated to the buffer. +.Sh SEE ALSO +.Xr dc_buffer_get_size 3 , +.Xr dc_buffer_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_buffer_get_size.3 b/doc/man/dc_buffer_get_size.3 new file mode 100644 index 0000000..85f933c --- /dev/null +++ b/doc/man/dc_buffer_get_size.3 @@ -0,0 +1,59 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_BUFFER_GET_SIZE 3 +.Os +.Sh NAME +.Nm dc_buffer_get_size +.Nd get the size used by a buffer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/buffer.h +.Ft size_t +.Fo dc_buffer_get_size +.Fa "dc_buffer_t *buffer" +.Fc +.Sh DESCRIPTION +Get the number of bytes currently used by +.Fa buffer , +previously allocated with +.Xr dc_buffer_new 3 . +This shouldn't be confused with the capacity, which may be larger. +.Pp +The returned value is not valid after subsequent calls to change the +buffer. +.Sh RETURN VALUES +Returns the number of bytes used, which may be zero, or zero if +.Fa buffer +is +.Dv NULL . +.Sh SEE ALSO +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . +.Xr dc_buffer_new 3 diff --git a/doc/man/dc_buffer_new.3 b/doc/man/dc_buffer_new.3 new file mode 100644 index 0000000..372c09c --- /dev/null +++ b/doc/man/dc_buffer_new.3 @@ -0,0 +1,57 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_BUFFER_NEW 3 +.Os +.Sh NAME +.Nm dc_buffer_new +.Nd create an resizable binary buffer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/buffer.h +.Ft "dc_buffer_t *" +.Fo dc_buffer_new +.Fa "size_t capacity" +.Fc +.Sh DESCRIPTION +Create a resizable binary buffer of initial size +.Fa capacity , +which may be zero. +The created buffer must be freed with +.Xr dc_buffer_free 3 . +.Sh RETURN VALUES +Returns a pointer to a +.Vt dc_buffer_t +or +.Dv NULL +on memory exhaustion. +.Sh SEE ALSO +.Xr dc_buffer_free 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_buffer_prepend.3 b/doc/man/dc_buffer_prepend.3 new file mode 100644 index 0000000..8bec1e2 --- /dev/null +++ b/doc/man/dc_buffer_prepend.3 @@ -0,0 +1,61 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_BUFFER_PREPEND 3 +.Os +.Sh NAME +.Nm dc_buffer_prepend +.Nd prepend to a binary buffer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/buffer.h +.Ft int +.Fo dc_buffer_prepend +.Fa "dc_buffer_t *buffer" +.Fa "const unsigned char data[]" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +Prepend +.Fa size +bytes of +.Fa data +to the beginning of +.Fa buffer +previously allocated with +.Xr dc_buffer_new 3 . +.Sh RETURN VALUES +Returns non-zero on success or zero on memory exhaustion or if +.Fa buffer +is +.Dv NULL . +.Sh SEE ALSO +.Xr dc_buffer_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_context_free.3 b/doc/man/dc_context_free.3 new file mode 100644 index 0000000..dbe9869 --- /dev/null +++ b/doc/man/dc_context_free.3 @@ -0,0 +1,54 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_CONTEXT_FREE 3 +.Os +.Sh NAME +.Nm dc_context_free +.Nd free a device-handling context +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/context.h +.Ft dc_status_t +.Fo dc_context_free +.Fa "dc_context_t *context" +.Fc +.Sh DESCRIPTION +Free a context created by +.Xr dc_context_new 3 . +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_OK +on success or if the pointer is +.Dv NULL . +Otherwise, it returns an error code. +.Sh SEE ALSO +.Xr dc_context_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_context_new.3 b/doc/man/dc_context_new.3 new file mode 100644 index 0000000..ee57843 --- /dev/null +++ b/doc/man/dc_context_new.3 @@ -0,0 +1,73 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_CONTEXT_NEW 3 +.Os +.Sh NAME +.Nm dc_context_new +.Nd create a new device-handling context +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/context.h +.Ft dc_status_t +.Fo dc_context_new +.Fa "dc_context_t **context" +.Fc +.Sh DESCRIPTION +Create a context in which dive computers may be queried. +The +.Dq context +supplies logging messages and so on, and may be re-used for multiple +dive computer query sessions. +It is usually passed to +.Xr dc_device_open 3 +to query a specific dive computer device. +.Pp +On success, the context must be freed with +.Xr dc_context_free 3 . +You may configure the context with +.Xr dc_context_set_loglevel 3 +and +.Xr dc_context_set_logfunc 3 . +This is highly recommended as the default logging behaviour of +.Nm +depends upon compile-time values. +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_OK +on success, in which case +.Fa context +is filled in, or an error code on failure. +.Sh SEE ALSO +.Xr dc_context_free 3 , +.Xr dc_context_set_logfunc 3 , +.Xr dc_context_set_loglevel 3 , +.Xr dc_device_open 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_context_set_logfunc.3 b/doc/man/dc_context_set_logfunc.3 new file mode 100644 index 0000000..68517ee --- /dev/null +++ b/doc/man/dc_context_set_logfunc.3 @@ -0,0 +1,98 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_CONTEXT_SET_LOGFUNC 3 +.Os +.Sh NAME +.Nm dc_context_set_logfunc +.Nd set the logging function for a dive computer context +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/context.h +.Ft typedef void +.Fo (*dc_logfunc_t) +.Fa "dc_context_t *context" +.Fa "dc_loglevel_t loglevel" +.Fa "const char *file" +.Fa "unsigned int line" +.Fa "const char *function" +.Fa "const char *message" +.Fa "void *userdata" +.Fc +.Ft dc_status_t +.Fo dc_context_set_logfunc +.Fa "dc_context_t *context" +.Fa "dc_logfunc_t logfunc" +.Fa "void *userdata" +.Fc +.Sh DESCRIPTION +Set the logging function +.Fa logfunc +associated with a dive computer context. +The logging function is invoked with argument +.Fa userdata +when the log level +.Pq see Xr dc_context_set_loglevel 3 +has been exceeded. +.Pp +The +.Fa logfunc +accepts the following values: +.Bl -tag -width Ds +.It Fa context +The context in which it was invoked. +.It Fa loglevel +The level of the log message. +.It Fa file +The source file where the message was raised. +.It Fa line +The source line (from 1) where the message was raised. +.It Fa function +The function that raised the log message. +.It Fa message +The log message itself. +.It Fa userdata +The pointer passed to +.Nm dc_context_set_logfunc . +.El +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_OK +on setting the log level, +.Dv DC_STATUS_INVALIDARGS +if +.Fa context +is +.Dv NULL , +or another error code on failure. +.Sh SEE ALSO +.Xr dc_context_new 3 , +.Xr dc_context_set_loglevel 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_context_set_loglevel.3 b/doc/man/dc_context_set_loglevel.3 new file mode 100644 index 0000000..57b88b5 --- /dev/null +++ b/doc/man/dc_context_set_loglevel.3 @@ -0,0 +1,90 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_CONTEXT_SET_LOGLEVEL 3 +.Os +.Sh NAME +.Nm dc_context_set_loglevel +.Nd set the logging level for a dive computer context +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/context.h +.Ft dc_status_t +.Fo dc_context_set_loglevel +.Fa "dc_context_t *context" +.Fa "dc_loglevel_t loglevel" +.Fc +.Sh DESCRIPTION +Set the +.Em minimum +log level required to raise a logging event with the +.Xr dc_context_set_logfunc 3 +callback. +Operates on a dive computer context created with +.Xr dc_context_new 3 . +The log levels are ordered as follows: +.Bl -enum +.It +.Dv DC_LOGLEVEL_NONE +.It +.Dv DC_LOGLEVEL_ERROR +.It +.Dv DC_LOGLEVEL_WARNING +.It +.Dv DC_LOGLEVEL_INFO +.It +.Dv DC_LOGLEVEL_DEBUG +.It +.Dv DC_LOGLEVEL_ALL +.El +.Pp +By setting, for exammple, +.Dv DC_LOGLEVEL_INFO , +all events of +.Dv DC_LOGLEVEL_ERROR , +.Dv DC_LOGLEVEL_WARNING , +and +.Dv DC_LOGLEVEL_INFO +will be reported via the callback in +.Xr dc_context_set_logfunc 3 . +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_OK +on setting the log level, +.Dv DC_STATUS_INVALIDARGS +if +.Fa context +is +.Dv NULL , +or another error code on failure. +.Sh SEE ALSO +.Xr dc_context_new 3 , +.Xr dc_context_set_logfunc 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_descriptor_free.3 b/doc/man/dc_descriptor_free.3 new file mode 100644 index 0000000..e7f4fde --- /dev/null +++ b/doc/man/dc_descriptor_free.3 @@ -0,0 +1,54 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DESCRIPTOR_FREE 3 +.Os +.Sh NAME +.Nm dc_descriptor_free +.Nd free a dive computer descriptor reference +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/descriptor.h +.Ft void +.Fo dc_descriptor_free +.Fa "dc_descriptor_t *descriptor" +.Fc +.Sh DESCRIPTION +Frees a descriptor usually returned with +.Xr dc_iterator_next 3 +as created with +.Xr dc_descriptor_iterator 3 . +It's safe to pass +.Dv NULL +to this function. +.Sh SEE ALSO +.Xr dc_descriptor_iterator 3 , +.Xr dc_iterator_free 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_descriptor_get_product.3 b/doc/man/dc_descriptor_get_product.3 new file mode 100644 index 0000000..541da7c --- /dev/null +++ b/doc/man/dc_descriptor_get_product.3 @@ -0,0 +1,59 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DESCRIPTOR_GET_PRODUCT 3 +.Os +.Sh NAME +.Nm dc_descriptor_get_product +.Nd get the product of a dive computer descriptor +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/descriptor.h +.Ft "const char *" +.Fo dc_descriptor_get_product +.Fa "dc_descriptor_t *descriptor" +.Fc +.Sh DESCRIPTION +Gets the product +.Pq e.g., Do D6i Dc for my Suunto +of a dive computer descriptor or +.Dv NULL +if none was declared. +.Sh RETURN VALUES +This returns the nil-terminated product string or +.Dv NULL +if none exists. +.Pp +The returned pointer is not valid after the +.Fa descriptor +has been freed. +.Sh SEE ALSO +.Xr dc_descriptor_get_vendor 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_descriptor_get_vendor.3 b/doc/man/dc_descriptor_get_vendor.3 new file mode 100644 index 0000000..6c5de33 --- /dev/null +++ b/doc/man/dc_descriptor_get_vendor.3 @@ -0,0 +1,59 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DESCRIPTOR_GET_VENDOR 3 +.Os +.Sh NAME +.Nm dc_descriptor_get_vendor +.Nd get the vendor of a dive computer descriptor +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/descriptor.h +.Ft "const char *" +.Fo dc_descriptor_get_vendor +.Fa "dc_descriptor_t *descriptor" +.Fc +.Sh DESCRIPTION +Gets the vendor +.Pq e.g., Dq Suunto +of a dive computer descriptor or +.Dv NULL +if none was declared. +.Sh RETURN VALUES +This returns the nil-terminated vendor string or +.Dv NULL +if none exists. +.Pp +The returned pointer is not valid after the +.Fa descriptor +has been freed. +.Sh SEE ALSO +.Xr dc_descriptor_get_product 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_descriptor_iterator.3 b/doc/man/dc_descriptor_iterator.3 new file mode 100644 index 0000000..5d6619d --- /dev/null +++ b/doc/man/dc_descriptor_iterator.3 @@ -0,0 +1,78 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DESCRIPTOR_ITERATOR 3 +.Os +.Sh NAME +.Nm dc_descriptor_iterator +.Nd get all supported dive computers +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/descriptor.h +.Ft dc_status_t +.Fo dc_descriptor_iterator +.Fa "dc_iterator_t **iterator" +.Fc +.Sh DESCRIPTION +Gets all descriptors available to +.Lb libdivecomputer . +It must be matched with +.Xr dc_iterator_free 3 +if the return value is +.Dv DC_STATUS_SUCCESS . +The +.Xr dc_iterator_next 3 +function must be used to iterate over the iterator. +You must use +.Xr dc_descriptor_free 3 +on the returned descriptor value. +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_SUCCESS +and fills in the +.Fa iterator +pointer on success. +.Sh EXAMPLES +The following iterates over all descriptors, printing the vendor, then +frees the iterator. +It does no error checking. +.Bd -literal +dc_descriptor_iterator(&iter)); +while (dc_iterator_next(iter, &desc) == DC_STATUS_SUCCESS) { + printf("%s\en", dc_descriptor_get_vendor(desc)); + dc_descriptor_free(desc); +} +dc_iterator_free(iter); +.Ed +.Sh SEE ALSO +.Xr dc_descriptor_free 3 , +.Xr dc_iterator_free 3 , +.Xr dc_iterator_next 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_device_close.3 b/doc/man/dc_device_close.3 new file mode 100644 index 0000000..996be8b --- /dev/null +++ b/doc/man/dc_device_close.3 @@ -0,0 +1,58 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DEVICE_CLOSE 3 +.Os +.Sh NAME +.Nm dc_device_close +.Nd close a dive computer device +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/device.h +.Ft dc_status_t +.Fo dc_device_close +.Fa "dc_device_t *device" +.Fc +.Sh DESCRIPTION +Closes a dive computer device opened with +.Xr dc_device_open 3 . +If +.Fa device +is +.Dv NULL , +this returns +.Dv DC_STATUS_SUCCESS . +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_SUCCESS +on success or one of several error values on error. +.Sh SEE ALSO +.Xr dc_device_open 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_device_foreach.3 b/doc/man/dc_device_foreach.3 new file mode 100644 index 0000000..a349a72 --- /dev/null +++ b/doc/man/dc_device_foreach.3 @@ -0,0 +1,84 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DEVICE_FOREACH 3 +.Os +.Sh NAME +.Nm dc_device_foreach +.Nd iterate over dives in a dive computer +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/device.h +.Ft typedef int +.Fo (*dc_dive_callback_t) +.Fa "const unsigned char *data" +.Fa "unsigned int size" +.Fa "const unsigned char *fingerprint" +.Fa "unsigned int fsize" +.Fa "void *userdata" +.Fc +.Ft dc_status_t +.Fo dc_device_foreach +.Fa "dc_device_t *device" +.Fa "dc_dive_callback_t callback" +.Fa "void *userdata" +.Fc +.Sh DESCRIPTION +Iterate over all dives on +.Fa device +by calling +.Fa callback +with +.Fa userdata . +.Pp +Each dive invokes +.Fa callback +with the dive data, which should be parsed with +.Xr dc_parser_set_data 3 , +and the binary fingerprint of the dive. +The fingerprint can be used to record the newest dive and stop +processing (on subsequent invocations) when the same dive fingerprint is +encountered. +.Pp +The +.Fa callback +function must return non-zero to continue downloading dives, or zero to +stop. +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_SUCCESS +on success or one of several error values on error. +If +.Fa callback +returns zero, this will not be reflected in the return value (usually +.Dv DC_STATUS_SUCCESS ) . +.Sh SEE ALSO +.Xr dc_parser_set_data 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_device_open.3 b/doc/man/dc_device_open.3 new file mode 100644 index 0000000..265d129 --- /dev/null +++ b/doc/man/dc_device_open.3 @@ -0,0 +1,88 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DEVICE_OPEN 3 +.Os +.Sh NAME +.Nm dc_device_open +.Nd open a dive computer device +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/device.h +.Ft dc_status_t +.Fo dc_device_open +.Fa "dc_device_t **device" +.Fa "dc_context_t *context" +.Fa "dc_descriptor_t *descriptor" +.Fa "const char *name" +.Fc +.Sh DESCRIPTION +Open a dive computer device for processing. +Accepts a +.Fa context +opened with +.Xr dc_context_new 3 , +a dive computer +.Fa descriptor +usually found by searching through +.Xr dc_descriptor_iterator 3 , +and a platform-specific device +.Fa name +.Po +such as +.Pa /dev/ttyUSBx +on Linux, +.Pa /dev/tty.xxx +on Mac OS X, +.Pa /dev/ttyUx +on the BSDs, +or +.Pa COMx +on Microsoft Windows +.Pc . +.Pp +Upon returning +.Dv DC_STATUS_SUCCESS , +the +.Fa device +pointer must be freed with +.Xr dc_device_close 3 . +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_SUCCESS +on success or one of several error values on error. +On success, the +.Fa device +pointer is filled in with an open handle. +.Sh SEE ALSO +.Xr dc_context_new 3 , +.Xr dc_descriptor_iterator 3 , +.Xr dc_device_close 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_device_set_cancel.3 b/doc/man/dc_device_set_cancel.3 new file mode 100644 index 0000000..59e79ca --- /dev/null +++ b/doc/man/dc_device_set_cancel.3 @@ -0,0 +1,79 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DEVICE_SET_CANCEL 3 +.Os +.Sh NAME +.Nm dc_device_set_cancel +.Nd callback to check whether processing should cancel +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/device.h +.Ft "typedef int" +.Fo "(*dc_cancel_callback_t)" +.Fa "void *userdata" +.Fc +.Ft dc_status_t +.Fo dc_device_set_cancel +.Fa "dc_device_t *device" +.Fa "dc_cancel_callback_t callback" +.Fa "void *userdata" +.Fc +.Sh DESCRIPTION +Provide a function that the underlying +.Fa device +will periodically call to see if it should cancel its processing. +The +.Fa callback +will return zero if the operation should not be cancelled, one if it +should be cancelled. +.Pp +The callback usually checks a value that is set during a signal handling +callback. +For example, one can invoke +.Xr signal 3 +to a function that sets a +.Vt "volatile sig_atomic_t" +value checked by the +.Fa callback +handler. +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_UNSUPPORTED +if the +.Fa device +is +.Dv NULL , +or +.Dv DC_STATUS_SUCCESS +otherwise. +.Sh SEE ALSO +.Xr dc_device_open 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 . diff --git a/doc/man/dc_device_set_events.3 b/doc/man/dc_device_set_events.3 new file mode 100644 index 0000000..1c53fcc --- /dev/null +++ b/doc/man/dc_device_set_events.3 @@ -0,0 +1,125 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DEVICE_SET_EVENTS 3 +.Os +.Sh NAME +.Nm dc_device_set_events +.Nd set events logged during device interaction +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/device.h +.Ft "typedef void" +.Fo "(*dc_event_callback_t)" +.Fa "dc_device_t *device" +.Fa "dc_event_type_t event" +.Fa "const void *data" +.Fa "void *userdata" +.Fc +.Ft dc_status_t +.Fo dc_device_set_events +.Fa "dc_device_t *device" +.Fa "unsigned int events" +.Fa "dc_event_callback_t callback" +.Fa "void *userdata" +.Fc +.Sh DESCRIPTION +Register a series of event callbacks on a device opened with +.Xr dc_device_open 3 . +Event callbacks are informative messages during device processing passed +to the +.Fa callback +function with an optional argument +.Fa userdata. +.Pp +The +.Fa events +value is a bit-field of events, one of which is passed to the +.Fa callback +as +.Fa event . +The +.Fa data +field will be cast to an event-specific type: +.Bl -tag -width Ds +.It Dv DC_EVENT_WAITING +Indicate that the device is waiting for user input, such as activating +the data transfer mode on the device. +No +.Fa data +is set. +.It Dv DC_EVENT_PROGRESS +Progress metre of the parse. +The +.Fa data +variable is set to a +.Vt dc_event_progress_t , +with the +.Va current +and +.Va maximum +progress values from which one can compute a percentage. +.It Dv DC_EVENT_DEVINFO +Sets the +.Fa data +value to a +.Vt dc_event_devinfo_t , +which can be used to acquire the +.Va model , +.Va firmware , +and +.Va serial +numbers of the underlying device. +.It Dv DC_EVENT_CLOCK +Report the system (local machine) and device time in epoch seconds. +Fills in +.Fa data +as a +.Va dc_event_clock_t , +with +.Va devtime +being the device and +.Va systime +being the system time. +See +.Xr time 3 . +.It Dv DC_EVENT_VENDOR +A vendor-specific event filling +.Fa data +as a +.Va dc_event_vendor_t . +.El +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_SUCCESS +on success or one of several error values on error. +.Sh SEE ALSO +.Xr dc_device_open 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 . diff --git a/doc/man/dc_device_set_fingerprint.3 b/doc/man/dc_device_set_fingerprint.3 new file mode 100644 index 0000000..641ae78 --- /dev/null +++ b/doc/man/dc_device_set_fingerprint.3 @@ -0,0 +1,70 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_DEVICE_SET_FINGERPRINT 3 +.Os +.Sh NAME +.Nm dc_device_set_fingerprint +.Nd set the last-seen dive fingerprint +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/device.h +.Ft dc_status_t +.Fo dc_device_set_fingerprint +.Fa "dc_device_t *device" +.Fa "const unsigned char data[]" +.Fa "unsigned int size" +.Fc +.Sh DESCRIPTION +Sets the last-seen dive fingerprint on a device opened with +.Xr dc_device_open 3 . +This mechanism is used to only download dives +.Dq newer +.Po +as reported by the dive computer, not necessarily on the calendar +.Pc +than the last seen dive. +.Pp +In general usage, the fingerprint is acquired (and saved) from the first +dive downloaded from a dive computer by +.Xr dc_device_foreach 3 . +In subsequent openings of the device, the fingerprint is set with +.Nm +and, when a dive reports a fingerprint matching that dive, the download +exits before reporting that dive. +.Pq The first fingerprint is saved again for subsequent invocations. +In this way, only the newest dives are reported. +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_SUCCESS +if the fingerprint was set or one of several error values on error. +.Sh SEE ALSO +.Xr dc_device_open 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_iterator_free.3 b/doc/man/dc_iterator_free.3 new file mode 100644 index 0000000..b086aaa --- /dev/null +++ b/doc/man/dc_iterator_free.3 @@ -0,0 +1,56 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_ITERATOR_FREE 3 +.Os +.Sh NAME +.Nm dc_iterator_free +.Nd frees an iterator +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/iterator.h +.Ft dc_status_t +.Fo dc_iterator_free +.Fa "dc_iterator_t *iterator" +.Fc +.Sh DESCRIPTION +Frees the iterator +.Fa iterator . +It may be invoked on any iterator type, e.g., one created with +.Xr dc_descriptor_iterator 3 . +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_SUCCESS +on success (or if +.Fa iterator +is +.Dv NULL ) +or other values on failure. +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_iterator_next.3 b/doc/man/dc_iterator_next.3 new file mode 100644 index 0000000..66ac480 --- /dev/null +++ b/doc/man/dc_iterator_next.3 @@ -0,0 +1,55 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_ITERATOR_NEXT 3 +.Os +.Sh NAME +.Nm dc_iterator_next +.Nd next element in an iterator +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/iterator.h +.Ft dc_status_t +.Fo dc_iterator_next +.Fa "dc_iterator_t *iterator" +.Fa "void *item" +.Fc +.Sh DESCRIPTION +Fills in +.Fa item +with the next element in the iterator +.Fa iterator , +which may not be +.Dv NULL . +.Sh RETURN VALUES +This returns +.Dv DC_STATUS_SUCCESS +on success. +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_parser_destroy.3 b/doc/man/dc_parser_destroy.3 new file mode 100644 index 0000000..c293666 --- /dev/null +++ b/doc/man/dc_parser_destroy.3 @@ -0,0 +1,57 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_PARSER_DESTROY 3 +.Os +.Sh NAME +.Nm dc_parser_destroy +.Nd destroys a single dive parser +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/parser.h +.Ft dc_status_t +.Fo dc_parser_destroy +.Fa "dc_parser_t *parser" +.Fc +.Sh DESCRIPTION +Destroys a parser allocated with +.Xr dc_parser_new 3 . +The +.Fa parser +parameter may be +.Dv NULL , +in which case it will return with success. +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_OK +on success and another code on failure. +.Sh SEE ALSO +.Xr dc_parser_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_parser_get_datetime.3 b/doc/man/dc_parser_get_datetime.3 new file mode 100644 index 0000000..4dd6456 --- /dev/null +++ b/doc/man/dc_parser_get_datetime.3 @@ -0,0 +1,60 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_PARSER_GET_DATETIME 3 +.Os +.Sh NAME +.Nm dc_parser_get_datetime +.Nd extract the date and time from a parsed dive +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/parser.h +.Ft dc_status_t +.Fo dc_parser_get_datetime +.Fa "dc_parser_t *parser" +.Fa "dc_datetime_t *datetime" +.Fc +.Sh DESCRIPTION +Extract the date and time of a dive, +.Fa parser , +previously initialised with +.Xr dc_parser_set_data 3 . +This returns the broken-down time-stamp of the dive in the local time of +the dive. +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_SUCCESS +if the date and time were retrieved, +.Dv DC_STATUS_UNSUPPORTED +if the date and time are not supported by the device, or other error +messages on further failure. +.Sh SEE ALSO +.Xr dc_parser_set_data 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_parser_get_field.3 b/doc/man/dc_parser_get_field.3 new file mode 100644 index 0000000..7d9e54e --- /dev/null +++ b/doc/man/dc_parser_get_field.3 @@ -0,0 +1,197 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_PARSER_GET_FIELD 3 +.Os +.Sh NAME +.Nm dc_parser_get_field +.Nd extract a field from a parsed dive +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/parser.h +.Ft dc_status_t +.Fo dc_parser_get_field +.Fa "dc_parser_t *parser" +.Fa "dc_field_type_t type" +.Fa "unsigned int flags" +.Fa "void *value" +.Fc +.Sh DESCRIPTION +Extract a field from a dive, +.Fa parser , +previously initialised with +.Xr dc_parser_set_data 3 . +The +.Fa value +field type depends upon the +.Fa type . +The +.Fa flags +field is ignored for all types but +.Dv DC_FIELD_GASMIX +and +.Dv DC_FIELD_TANK . +.Pp +The +.Fa type +may be one of the following values: +.Bl -tag -width Ds +.It Dv DC_FIELD_DIVETIME +Time (duration) of dive in seconds. +The +.Fa value +must be an +.Vt unsigned int . +.It Dv DC_FIELD_MAXDEPTH +Maximum depth in metres. +The +.Fa value +must be a +.Vt double . +.It Dv DC_FIELD_AVGDEPTH +Average depth (over all samples) in metres. +The +.Fa value +must be a +.Vt double . +.It Dv DC_FIELD_GASMIX_COUNT +Number of different gas mixes used in this dive. +The +.Fa value +must be a +.Vt unsigned int . +.It Dv DC_FIELD_GASMIX +Mixture for a particular gas. +The +.Fa value +must be a +.Vt dc_gasmix_t , +which has +.Vt double +fields for +.Va oxygen , +.Va helium , +and +.Va nitrogen . +These are set to the unit fraction of gas (not percentage). +The +.Fa flags +value is interpreted as the gas mixture index, which must be less than the +value of +.Dv DC_FIELD_GASMIX_COUNT . +.It Dv DC_FIELD_SALINITY +The water salinity as a +.Vt dc_salinity_t +field, which consists of a +.Va type , +.Dv DC_WATER_FRESH +or +.Dv DC_WATER_SALT , +and the salinity +.Va density . +.It Dv DC_FIELD_ATMOSPHERIC +Atmospheric pressure in bar. +The +.Fa value +field must be a +.Vt double . +.It Dv DC_FIELD_TEMPERATURE_SURFACE +Air temperature (at the surface) in Celsius. +The +.Fa value +field must be a +.Vt double . +.It Dv DC_FIELD_TEMPERATURE_MINIMUM +Minimum water temperature surface in Celsius. +The +.Fa value +field must be a +.Vt double . +.It Dv DC_FIELD_TEMPERATURE_MAXIMUM +Maximum water temperature in Celsius. +The +.Fa value +field must be a +.Vt double . +.It Dv DC_FIELD_TANK_COUNT +The number of tanks as an +.Vt unsigned int . +.It Dv DC_FIELD_TANK +Tank configuration as a +.Vt dc_tank_t . +This structure consists of a +.Va gasmix , +which may be retrieved with +.Dv DC_FIELD_GASMIX ; +.Va type , +the tank volume units as +.Dv DC_TANKVOLUME_NONE , +.Dv DC_TANKVOLUME_IMPERIAL , +or +.Dv DC_TANKVOLUME_METRIC ; +.Va volume , +the tank volume in bar or zero if the tank is +.Dv DC_TANKVOLUME_NONE ; +.Va workpressure , +the work pressure in bar or zero if +.Dv DC_TANKVOLUME_NONE +and maybe zero if +.Dv DC_TANKVOLUME_METRIC ; +.Va beginpressure +and +.Va endpressure +being the pressures at start and finish in bar. +The +.Fa flags +value is the tank index. +.It Dv DC_FIELD_DIVEMODE +Mode of the dive: +.Dv DC_DIVEMODE_FREEDIVE +for free-diving, +.Dv DC_DIVEMODE_GAUGE +for gauge (i.e., running as a record and not computing, say, +decompression events), +.Dv DC_DIVEMODE_OC +for standard open-circuit diving, and +.Dv DC_DIVEMODE_CC +for closed-circuit +.Dq rebreather +diving. +.El +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_SUCCESS +if the field was retrieved, +.Dv DC_STATUS_UNSUPPORTED +if the field is not supported by the device, or other error messages on +further failure. +.Sh SEE ALSO +.Xr dc_parser_set_data 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_parser_new.3 b/doc/man/dc_parser_new.3 new file mode 100644 index 0000000..9f879cd --- /dev/null +++ b/doc/man/dc_parser_new.3 @@ -0,0 +1,82 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_PARSER_NEW 3 +.Os +.Sh NAME +.Nm dc_parser_new , +.Nm dc_parser_new2 +.Nd create a parser for a single dive +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/parser.h +.Ft dc_status_t +.Fo dc_parser_new +.Fa "dc_parser_t **parser" +.Fa "dc_device_t *device" +.Fc +.Ft dc_status_t +.Fo dc_parser_new2 +.Fa "dc_parser_t **parser" +.Fa "dc_context_t *context" +.Fa "dc_descriptor_t *descriptor" +.Fa "unsigned int devtime" +.Fa "dc_ticks_t systime" +.Fc +.Sh DESCRIPTION +Creates a parser for a single dive extracted from the dive computer with +.Xr dc_device_foreach 3 . +The parser operates on the data extracted: it does not touch the device +directly to acquire data. +Thus, there are two forms of invocation: +.Nm dc_parser_new , +which extracts relevant values from the +.Fa device +parameter; and +.Nm dc_parser_new2 , +which is given device values (model, etc.) directly. +.Pp +After filling in the +.Fa parser +parameter, one usually sets parser data with +.Xr dc_parser_set_data 3 . +The pointer must later be freed with +.Xr dc_parser_destroy 3 . +.Sh RETURN VALUES +These return +.Dv DC_STATUS_OK , +and fill in the +.Fa parser +pointer on success. +Otherwise, an error is returned. +.Sh SEE ALSO +.Xr dc_device_foreach 3 , +.Xr dc_parser_destroy 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_parser_samples_foreach.3 b/doc/man/dc_parser_samples_foreach.3 new file mode 100644 index 0000000..5a92011 --- /dev/null +++ b/doc/man/dc_parser_samples_foreach.3 @@ -0,0 +1,196 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_PARSER_SAMPLES_FOREACH 3 +.Os +.Sh NAME +.Nm dc_parser_samples_foreach +.Nd iterate over samples taken during a dive +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/parser.h +.Ft "typedef void" +.Fo "(*dc_sample_callback_t)" +.Fa "dc_sample_type_t type" +.Fa "dc_sample_value_t value" +.Fa "void *userdata" +.Fc +.Ft dc_status_t +.Fo dc_parser_samples_foreach +.Fa "dc_parser_t *parser" +.Fa "dc_sample_callback_t callback" +.Fa "void *userdata" +.Fc +.Sh DESCRIPTION +Extract the samples taken during a dive as previously initialised with +.Xr dc_parser_set_data 3 . +Each sample is passed to +.Fa callback +with the +.Fa type +of the sample and its data +.Fa value . +.Pp +Samples are invoked as a sequence of sample sets. +Each sequence begins with a +.Dv DC_SAMPLE_TIME , +then a number of sample types in the set. +When the next +.Dv DC_SAMPLE_TIME +is recorded, the sample set may be closed and a new one reopened. +After all samples have been rendered, the last sample set should be +closed. +.Pp +The following sample types may be raised: +.Bl -tag -width Ds +.It Dv DC_SAMPLE_TIME +The time of the sample taken in seconds after the dive began. +Set in the +.Fa time +field. +.It Dv DC_SAMPLE_DEPTH +The depth taken at the sample in metres. +Set in the +.Fa depth +field. +.It Dv DC_SAMPLE_PRESSURE +Tank pressure taken at the sample. +Sets the +.Fa tank +index (see the +.Dv DC_FIELD_TANK_COUNT +in +.Xr dc_parser_get_field 3 ) +and the +.Fa pressure +in bar. +.It Dv DC_SAMPLE_TEMPERATURE +Temperature in celsius. +Sets the +.Fa temperature +field. +.It Dv DC_SAMPLE_EVENT +An diving event raised by the computer. +This may have the +.Va type +value of the +.Va event +structure set to +.Dv SAMPLE_EVENT_NONE , +.Dv SAMPLE_EVENT_DECOSTOP , +.Dv SAMPLE_EVENT_RBT , +.Dv SAMPLE_EVENT_ASCENT , +.Dv SAMPLE_EVENT_CEILING , +.Dv SAMPLE_EVENT_WORKLOAD , +.Dv SAMPLE_EVENT_TRANSMITTER , +.Dv SAMPLE_EVENT_VIOLATION , +.Dv SAMPLE_EVENT_BOOKMARK , +.Dv SAMPLE_EVENT_SURFACE , +.Dv SAMPLE_EVENT_SAFETYSTOP , +.Dv SAMPLE_EVENT_SAFETYSTOP_VOLUNTARY , +.Dv SAMPLE_EVENT_SAFETYSTOP_MANDATORY , +.Dv SAMPLE_EVENT_DEEPSTOP , +.Dv SAMPLE_EVENT_CEILING_SAFETYSTOP , +.Dv SAMPLE_EVENT_FLOOR , +.Dv SAMPLE_EVENT_DIVETIME , +.Dv SAMPLE_EVENT_MAXDEPTH , +.Dv SAMPLE_EVENT_OLF , +.Dv SAMPLE_EVENT_PO2 , +.Dv SAMPLE_EVENT_AIRTIME , +.Dv SAMPLE_EVENT_RGBM , +.Dv SAMPLE_EVENT_HEADING , +or +.Dv SAMPLE_EVENT_TISSUELEVEL . +.It Dv DC_SAMPLE_RBT +The remaining bottom time in seconds. +Sets the +.Fa rbt +field. +.It Dv DC_SAMPLE_HEARTBEAT +The diver's heartbeet in beats per minute. +Sets the +.Fa heartbeat +field. +.It Dv DC_SAMPLE_BEARING +The diver's bearing in degrees. +Sets the +.Fa bearing +field. +.It Dv DC_SAMPLE_VENDOR +A vendor-specific data field. +.It Dv DC_SAMPLE_SETPOINT +The closed-circuit setpoint (PO2) has changed. +Sets the +.Fa setpoint +value in bar. +.It Dv DC_SAMPLE_PPO2 +The partial pressure of oxygen has changed (in bar). +Sets the +.Fa ppo2 +field. +.It Dv DC_SAMPLE_CNS +The CNS (central nervous system oxygen toxicity) value as a unit +fraction. +Sets the +.Fa cns +value. +.It Dv DC_SAMPLE_DECO +Decompression phase of +.Fa type +.Dv DC_DECO_NDL +.Pq no decompression limit , +.Dv DC_DECO_SAFETYSTOP +.Pq the safety stop , +.Dv DC_DECO_DECOSTOP +.Pq a decompression stop , +or +.Dv DC_DECO_DEEPSTOP +.Pq a mandatory or suggested deep-stop . +Also sets the +.Fa depth +in metres and the +.Fa time +in seconds. +.It Dv DC_SAMPLE_GASMIX +Switch to a given gas mix index (see the +.Dv DC_FIELD_GASMIX_COUNT +in +.Xr dc_parser_get_field 3 ) . +Sets the +.Fa gasmix +field. +.El +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_OK +on success and another code on failure. +.Sh SEE ALSO +.Xr dc_parser_set_data 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/dc_parser_set_data.3 b/doc/man/dc_parser_set_data.3 new file mode 100644 index 0000000..39af43b --- /dev/null +++ b/doc/man/dc_parser_set_data.3 @@ -0,0 +1,65 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 DC_PARSER_SET_DATA 3 +.Os +.Sh NAME +.Nm dc_parser_set_data +.Nd assigns parse data to a dive parser +.Sh LIBRARY +.Lb libdivecomputer +.Sh SYNOPSIS +.In libdivecomputer/parser.h +.Ft dc_status_t +.Fo dc_parser_set_data +.Fa "dc_parser_t *parser" +.Fa "const unsigned char *data" +.Fa "unsigned int size" +.Fc +.Sh DESCRIPTION +Assigns the binary sequence +.Fa data +of length +.Fa size +bytes to +.Fa parser , +which was created with +.Xr dc_parser_new 3 . +How the data is parsed depends upon the values provided to +.Xr dc_parser_new 3 . +The data usually comes from the callback assigned to +.Xr dc_device_foreach 3 . +.Sh RETURN VALUES +Returns +.Dv DC_STATUS_OK +on success and another code on failure. +.Sh SEE ALSO +.Xr dc_device_foreach 3 , +.Xr dc_parser_new 3 +.Sh AUTHORS +The +.Lb libdivecomputer +library was written by +.An Jef Driesen , +.Mt jef@libdivecomputer.org . +The manpages were written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . diff --git a/doc/man/libdivecomputer.3 b/doc/man/libdivecomputer.3 new file mode 100644 index 0000000..c85f140 --- /dev/null +++ b/doc/man/libdivecomputer.3 @@ -0,0 +1,141 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 . +This supplies a parse context: logging, error handling, etc. +Override the values 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 +Open the hardware device to which the dive computer is connected with +.Xr dc_device_open 3 , +then invoke +.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 +and set the parsed data with +.Xr dc_parser_set_data 3 . +.It +Get attributes of the parsed dive with +.Xr dc_parser_get_field 3 , +then 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_buffer_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 .