FlapJackApps/libdc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document the public api with man pages

Browse Source
This commit is contained in:
Kristaps Dzonsons 2017-01-05 11:22:10 +01:00 committed by Jef Driesen
parent 07dcc8998b
commit 77b0cebb35
32 changed files with 2364 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
configure.ac
View File

@ -171,6 +171,7 @@ AC_CONFIG_FILES([
src/libdivecomputer.rc
doc/Makefile
doc/doxygen.cfg
doc/man/Makefile
examples/Makefile
])
AC_OUTPUT

2
doc/Makefile.am
View File

@ -1,3 +1,5 @@
SUBDIRS = man
doxygen: doxygen.cfg
if HAVE_DOXYGEN
$(DOXYGEN) $(DOXYFLAGS) $<

30
doc/man/Makefile.am Normal file
View File

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

61
doc/man/dc_buffer_append.3 Normal file
View File

@ -0,0 +1,61 @@
.\"
.\" 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 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 .

51
doc/man/dc_buffer_free.3 Normal file
View File

@ -0,0 +1,51 @@
.\"
.\" 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 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 .

64
doc/man/dc_buffer_get_data.3 Normal file
View File

@ -0,0 +1,64 @@
.\"
.\" 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 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 .

59
doc/man/dc_buffer_get_size.3 Normal file
View File

@ -0,0 +1,59 @@
.\"
.\" 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 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

57
doc/man/dc_buffer_new.3 Normal file
View File

@ -0,0 +1,57 @@
.\"
.\" 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 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 .

61
doc/man/dc_buffer_prepend.3 Normal file
View File

@ -0,0 +1,61 @@
.\"
.\" 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 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 .

54
doc/man/dc_context_free.3 Normal file
View File

@ -0,0 +1,54 @@
.\"
.\" 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 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 .

73
doc/man/dc_context_new.3 Normal file
View File

@ -0,0 +1,73 @@
.\"
.\" 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 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 .

98
doc/man/dc_context_set_logfunc.3 Normal file
View File

@ -0,0 +1,98 @@
.\"
.\" 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 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 .

90
doc/man/dc_context_set_loglevel.3 Normal file
View File

@ -0,0 +1,90 @@
.\"
.\" 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 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 .

54
doc/man/dc_descriptor_free.3 Normal file
View File

@ -0,0 +1,54 @@
.\"
.\" 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 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 .

59
doc/man/dc_descriptor_get_product.3 Normal file
View File

@ -0,0 +1,59 @@
.\"
.\" 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 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 .

59
doc/man/dc_descriptor_get_vendor.3 Normal file
View File

@ -0,0 +1,59 @@
.\"
.\" 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 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 .

78
doc/man/dc_descriptor_iterator.3 Normal file
View File

@ -0,0 +1,78 @@
.\"
.\" 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 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 .

58
doc/man/dc_device_close.3 Normal file
View File

@ -0,0 +1,58 @@
.\"
.\" 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 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 .

84
doc/man/dc_device_foreach.3 Normal file
View File

@ -0,0 +1,84 @@
.\"
.\" 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 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 .

88
doc/man/dc_device_open.3 Normal file
View File

@ -0,0 +1,88 @@
.\"
.\" 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 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 .

79
doc/man/dc_device_set_cancel.3 Normal file
View File

@ -0,0 +1,79 @@
.\"
.\" 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 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 .

125
doc/man/dc_device_set_events.3 Normal file
View File

@ -0,0 +1,125 @@
.\"
.\" 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 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 .

70
doc/man/dc_device_set_fingerprint.3 Normal file
View File

@ -0,0 +1,70 @@
.\"
.\" 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 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 .

56
doc/man/dc_iterator_free.3 Normal file
View File

@ -0,0 +1,56 @@
.\"
.\" 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 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 .

55
doc/man/dc_iterator_next.3 Normal file
View File

@ -0,0 +1,55 @@
.\"
.\" 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 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 .

57
doc/man/dc_parser_destroy.3 Normal file
View File

@ -0,0 +1,57 @@
.\"
.\" 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 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 .

60
doc/man/dc_parser_get_datetime.3 Normal file
View File

@ -0,0 +1,60 @@
.\"
.\" 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 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 .

197
doc/man/dc_parser_get_field.3 Normal file
View File

@ -0,0 +1,197 @@
.\"
.\" 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 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 .

82
doc/man/dc_parser_new.3 Normal file
View File

@ -0,0 +1,82 @@
.\"
.\" 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 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 .

196
doc/man/dc_parser_samples_foreach.3 Normal file
View File

@ -0,0 +1,196 @@
.\"
.\" 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 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 .

65
doc/man/dc_parser_set_data.3 Normal file
View File

@ -0,0 +1,65 @@
.\"
.\" 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 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 .

141
doc/man/libdivecomputer.3 Normal file
View File

@ -0,0 +1,141 @@
.\"
.\" 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 .
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 .