libdivecomputer

https://www.libdivecomputer.org/doc/
Admin
libdivecomputer is a cross-platform, open-source library for communicating with and extracting dive...
Tokens:19,838
Snippets:194
Trust Score:7.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Iterate over all dive computer descriptors

Source: https://www.libdivecomputer.org/doc/dc_descriptor_iterator.3.html

This example demonstrates how to initialize the iterator, loop through all available descriptors to print the vendor name, and clean up resources. Note that this example omits error checking.

```c
dc_descriptor_iterator(&iter)); 
while (dc_iterator_next(iter, &desc) == DC_STATUS_SUCCESS) { 
	printf("%s\n", dc_descriptor_get_vendor(desc)); 
	dc_descriptor_free(desc); 
}
dc_iterator_free(iter);
```

--------------------------------

### Build libdivecomputer on UNIX with autoreconf, configure, make

Source: https://www.libdivecomputer.org/documentation.html

Compile the library on UNIX platforms using the standard autotools build sequence. Requires only the default tools installed on most UNIX systems.

```bash
autoreconf --install
./configure
make
make install

```

--------------------------------

### dc_device_set_cancel

Source: https://www.libdivecomputer.org/doc/dc_device_set_cancel.3.html

Documentation for the dc_device_set_cancel function, including its signature, parameters, return values, and an example usage.

```APIDOC
## dc_device_set_cancel

### Description
Sets a callback function that the device will periodically call to check whether processing should be cancelled. The callback returns zero to continue, one to cancel.

### Function Signature
```c
dc_status_t dc_device_set_cancel(dc_device_t *device, dc_cancel_callback_t callback, void *userdata);
```

### Parameters
- **device** (dc_device_t *) - Required - The device handle.
- **callback** (dc_cancel_callback_t) - Required - The callback function to be invoked.
- **userdata** (void *) - Required - User data passed to the callback.

### Callback Type
```c
typedef int (*dc_cancel_callback_t)(void *userdata);
```

### Return Values
- **DC_STATUS_SUCCESS** - On success.
- **DC_STATUS_UNSUPPORTED** - If the device is NULL.

### Example
```c
#include <libdivecomputer/device.h>

static volatile sig_atomic_t cancel_flag = 0;

static int cancel_cb(void *userdata) {
    return cancel_flag;
}

void handle_signal(int sig) {
    cancel_flag = 1;
}

int main(void) {
    dc_device_t *device = NULL;
    // ... open device ...
    signal(SIGINT, handle_signal);
    dc_status_t status = dc_device_set_cancel(device, cancel_cb, NULL);
    if (status != DC_STATUS_SUCCESS) {
        // handle error
    }
    // ...
}
```
```

--------------------------------

### Check for USB HID transport support

Source: https://www.libdivecomputer.org/doc/dc_descriptor_get_transports.3.html

Use this code to determine if a specific transport is supported by the descriptor. The function returns a bitwise OR of transport flags, and the example checks the DC_TRANSPORT_USBHID flag.

```c
unsigned int transports = dc_descriptor_get_transports(descriptor); 
if(transports & DC_TRANSPORT_USBHID) { 
    // Device supports USB HID as transport 
}

```

--------------------------------

### dc_descriptor_iterator(dc_iterator_t **iterator)

Source: https://www.libdivecomputer.org/doc/dc_descriptor_iterator.3.html

Gets all descriptors available to the libdivecomputer library. On success, it fills the iterator pointer and returns DC_STATUS_SUCCESS. The iterator must be freed with dc_iterator_free(3) and iterated with dc_iterator_next(3).

```APIDOC
## dc_descriptor_iterator(dc_iterator_t **iterator)

### Description
Gets all descriptors available to library "libdivecomputer". It must be matched with dc_iterator_free(3) if the return value is DC_STATUS_SUCCESS. The dc_iterator_next(3) function must be used to iterate over the iterator. You must use dc_descriptor_free(3) on the returned descriptor value.

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/descriptor.h>

dc_status_t
dc_descriptor_iterator(dc_iterator_t **iterator);

### Parameters
- **iterator** (dc_iterator_t **) - Output parameter. On success, it is filled with a pointer to an iterator over all descriptors.

### Return Values
Returns DC_STATUS_SUCCESS and fills in the iterator pointer on success.

### Example
```
dc_descriptor_iterator(&iter);
while (dc_iterator_next(iter, &desc) == DC_STATUS_SUCCESS) {
    printf("%s\n", dc_descriptor_get_vendor(desc));
    dc_descriptor_free(desc);
}
dc_iterator_free(iter);
```

### See Also
dc_descriptor_free(3), dc_iterator_free(3), dc_iterator_next(3)
```

--------------------------------

### dc_irda_device_get_address

Source: https://www.libdivecomputer.org/doc/dc_irda_device_get_address.3.html

Get the address of the IrDA device. The returned address is used for opening an IrDA device using dc_irda_open.

```APIDOC
## dc_irda_device_get_address

### Description
Get the address of the IrDA device. The returned address is used for opening an IrDA device using dc_irda_open.

### Library
libdivecomputer

### Synopsis
#include <libdivecomputer/irda.h>

unsigned int dc_irda_device_get_address(dc_irda_device_t *device);

### Parameters
- **device** (dc_irda_device_t *) - Required - A valid IrDA device of type dc_irda_device_t, which can be retrieved using dc_irda_iterator_new.

### Return Value
Returns the IrDA address of the given IrDA device.

### See Also
dc_irda_open(3), dc_irda_device_get_name(3).
```

--------------------------------

### dc_device_open

Source: https://www.libdivecomputer.org/doc/dc_device_open.3.html

Opens a dive computer device for processing. It requires a context, a descriptor, and an iostream, and returns a device handle on success.

```APIDOC
## dc_device_open

### Description
Opens a dive computer device for processing. Accepts a context opened with dc_context_new(3), a dive computer descriptor usually found by searching through dc_descriptor_iterator(3), and an iostream opened with a transport specific open function like dc_usbhid_open(3), dc_irda_open(3), dc_serial_open(3), or dc_bluetooth_open(3).

### Function Signature
```c
#include <libdivecomputer/device.h>

dc_status_t dc_device_open(dc_device_t **device, dc_context_t *context, dc_descriptor_t *descriptor, dc_iostream_t *iostream);
```

### Parameters
- **device** (dc_device_t **) - Output parameter. On success, filled with an open device handle.
- **context** (dc_context_t *) - A context opened with dc_context_new(3).
- **descriptor** (dc_descriptor_t *) - A dive computer descriptor, usually found via dc_descriptor_iterator(3).
- **iostream** (dc_iostream_t *) - An iostream opened with a transport-specific open function (e.g., dc_usbhid_open, dc_irda_open, dc_serial_open, dc_bluetooth_open).

### Return Values
Returns DC_STATUS_SUCCESS on success or one of several error values on error. On success, the device pointer is filled in with an open handle.

### Notes
Upon returning DC_STATUS_SUCCESS, the device pointer must be freed with dc_device_close(3).

### See Also
dc_context_new(3), dc_descriptor_iterator(3), dc_device_close(3)
```

--------------------------------

### dc_bluetooth_device_get_name

Source: https://www.libdivecomputer.org/doc/dc_bluetooth_device_get_name.3.html

Get the name of a bluetooth device. Used for displaying. Requires a valid bluetooth_device of type dc_bluetooth_device_t which can be retrieved using dc_bluetooth_iterator_new(3).

```APIDOC
## dc_bluetooth_device_get_name

### Description
Get the name of a bluetooth device. Used for displaying. Requires a valid bluetooth_device of type dc_bluetooth_device_t which can be retrieved using dc_bluetooth_iterator_new(3).

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/bluetooth.h>

const char *
dc_bluetooth_device_get_name(dc_bluetooth_device_t *device);

### Parameters
- **device** (dc_bluetooth_device_t *) - Required - A valid bluetooth device.

### Return Values
Returns the bluetooth device of device.

### See Also
dc_bluetooth_open(3), dc_bluetooth_iterator_new(3), dc_bluetooth_device_get_address(3).
```

--------------------------------

### dc_device_foreach(dc_device_t *device, dc_dive_callback_t callback, void *userdata)

Source: https://www.libdivecomputer.org/doc/dc_device_foreach.3.html

Iterates over all dives on a dive computer, invoking the provided callback for each dive. The callback receives the dive data and fingerprint, and should return non-zero to continue or zero to stop.

```APIDOC
## dc_device_foreach(dc_device_t *device, dc_dive_callback_t callback, void *userdata)

### Description
Iterate over all dives on device by calling callback with userdata. Each dive invokes callback with the dive data, which should be parsed with 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. The callback function must return non-zero to continue downloading dives, or zero to stop.

### Library
libdivecomputer

### Synopsis
#include <libdivecomputer/device.h>

typedef int (*dc_dive_callback_t)(const unsigned char *data, unsigned int size, const unsigned char *fingerprint, unsigned int fsize, void *userdata);

dc_status_t dc_device_foreach(dc_device_t *device, dc_dive_callback_t callback, void *userdata);

### Parameters
- **device** (dc_device_t *) - Required - The dive computer device handle.
- **callback** (dc_dive_callback_t) - Required - The callback function to invoke for each dive. It receives the dive data, size, fingerprint, fingerprint size, and userdata.
- **userdata** (void *) - Required - User data passed to the callback.

### Callback Parameters
- **data** (const unsigned char *) - The dive data, to be parsed with dc_parser_set_data(3).
- **size** (unsigned int) - The size of the dive data.
- **fingerprint** (const unsigned char *) - The binary fingerprint of the dive.
- **fsize** (unsigned int) - The size of the fingerprint.
- **userdata** (void *) - The user data passed to dc_device_foreach.

### Return Value
Returns DC_STATUS_SUCCESS on success or one of several error values on error. If callback returns zero, this will not be reflected in the return value (usually DC_STATUS_SUCCESS).

### See Also
dc_parser_set_data(3)
```

--------------------------------

### dc_descriptor_get_transports

Source: https://www.libdivecomputer.org/doc/dc_descriptor_get_transports.3.html

Gets the transports supported by the given descriptor. The descriptor is usually found by searching through dc_descriptor_iterator(3). Returns a union (bitwise OR) of the transports supported by the descriptor.

```APIDOC
## dc_descriptor_get_transports

### Description
Gets the transports supported by the given descriptor. The descriptor is usually found by searching through dc_descriptor_iterator(3).

### Function Signature
unsigned int dc_descriptor_get_transports(dc_descriptor_t *descriptor);

### Parameters
- **descriptor** (dc_descriptor_t *) - Required - The descriptor to query.

### Return Value
Returns a union (bitwise OR) of the transports supported by the given descriptor. The result is a combination of DC_TRANSPORT_USB, DC_TRANSPORT_USBHID, DC_TRANSPORT_BLE, DC_TRANSPORT_BLUETOOTH, DC_TRANSPORT_SERIAL, DC_TRANSPORT_IRDA.

### Example
```c
unsigned int transports = dc_descriptor_get_transports(descriptor);
if(transports & DC_TRANSPORT_USBHID) {
    // Device supports USB HID as transport
}
```
```

--------------------------------

### dc_parser_new2(dc_parser_t **parser, dc_context_t *context, dc_descriptor_t *descriptor, unsigned int devtime, dc_ticks_t systime)

Source: https://www.libdivecomputer.org/doc/dc_parser_new.3.html

Creates a parser for a single dive using device values (model, etc.) directly, without a device object.

```APIDOC
## dc_parser_new2

### Description
Creates a parser for a single dive extracted from the dive computer. This form of invocation is given device values (model, etc.) directly.

### Function Signature
```c
dc_status_t dc_parser_new2(dc_parser_t **parser, dc_context_t *context, dc_descriptor_t *descriptor, unsigned int devtime, dc_ticks_t systime);
```

### Parameters
- **parser** (dc_parser_t **) - Output parameter. On success, a pointer to the newly created parser is stored here.
- **context** (dc_context_t *) - The context object.
- **descriptor** (dc_descriptor_t *) - The device descriptor.
- **devtime** (unsigned int) - The device time.
- **systime** (dc_ticks_t) - The system time.

### Return Value
Returns `DC_STATUS_OK` on success, and fills in the parser pointer. Otherwise, an error is returned.

### Usage Notes
After creating the parser, one usually sets parser data with `dc_parser_set_data(3)`. The parser must later be freed with `dc_parser_destroy(3)`.

### See Also
dc_device_foreach(3), dc_parser_destroy(3)
```

--------------------------------

### dc_context_new

Source: https://www.libdivecomputer.org/doc/dc_context_new.3.html

Creates a new device-handling context for querying dive computers. The context supplies logging messages and can be reused for multiple sessions. On success, the context must be freed with dc_context_free.

```APIDOC
## dc_context_new

### Description
Creates a new device-handling context for querying dive computers. The context supplies logging messages and can be reused for multiple sessions. On success, the context must be freed with dc_context_free.

### Library
libdivecomputer

### Synopsis
#include <libdivecomputer/context.h>

dc_status_t dc_context_new(dc_context_t **context);

### Parameters
- **context** (dc_context_t **) - Required - Pointer to a pointer where the new context will be stored on success.

### Return Values
Returns DC_STATUS_OK on success, in which case context is filled in, or an error code on failure.

### Notes
The context is usually passed to dc_device_open(3) to query a specific dive computer device. You may configure the context with dc_context_set_loglevel(3) and dc_context_set_logfunc(3). This is highly recommended as the default logging behaviour depends upon compile-time values.

### See Also
dc_context_free(3), dc_context_set_logfunc(3), dc_context_set_loglevel(3), dc_device_open(3)
```

--------------------------------

### dc_parser_new(dc_parser_t **parser, dc_device_t *device)

Source: https://www.libdivecomputer.org/doc/dc_parser_new.3.html

Creates a parser for a single dive using a device object. The parser extracts relevant values from the device parameter.

```APIDOC
## dc_parser_new

### Description
Creates a parser for a single dive extracted from the dive computer. This form of invocation extracts relevant values from the device parameter.

### Function Signature
```c
dc_status_t dc_parser_new(dc_parser_t **parser, dc_device_t *device);
```

### Parameters
- **parser** (dc_parser_t **) - Output parameter. On success, a pointer to the newly created parser is stored here.
- **device** (dc_device_t *) - The device from which the dive data was extracted.

### Return Value
Returns `DC_STATUS_OK` on success, and fills in the parser pointer. Otherwise, an error is returned.

### Usage Notes
After creating the parser, one usually sets parser data with `dc_parser_set_data(3)`. The parser must later be freed with `dc_parser_destroy(3)`.

### See Also
dc_device_foreach(3), dc_parser_destroy(3)
```

--------------------------------

### dc_context_free(dc_context_t *context)

Source: https://www.libdivecomputer.org/doc/dc_context_free.3.html

Frees a device-handling context that was previously created by dc_context_new. Returns DC_STATUS_OK on success or if the pointer is NULL, otherwise an error code.

```APIDOC
## dc_context_free(dc_context_t *context)

### Description
Frees a device-handling context created by dc_context_new(3).

### Library
libdivecomputer

### Synopsis
#include <libdivecomputer/context.h>

dc_status_t
dc_context_free(dc_context_t *context);

### Parameters
- **context** (dc_context_t *) - Required - Pointer to the context to free.

### Return Values
Returns DC_STATUS_OK on success or if the pointer is NULL. Otherwise, returns an error code.

### See Also
dc_context_new(3)
```

--------------------------------

### dc_usbhid_open

Source: https://www.libdivecomputer.org/doc/dc_usbhid_open.3.html

Opens an iostream for a USB HID device. Accepts a context opened with dc_context_new(3) and a device usually found by searching through dc_usbhid_iterator_new(3). Upon returning DC_STATUS_SUCCESS, the iostream pointer must be freed with dc_iostream_close(3).

```APIDOC
## dc_usbhid_open

### Description
Opens an iostream for a USB HID device. Accepts a context opened with dc_context_new(3) and a device usually found by searching through dc_usbhid_iterator_new(3). Upon returning DC_STATUS_SUCCESS, the iostream pointer must be freed with dc_iostream_close(3).

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/usbhid.h>

dc_status_t dc_usbhid_open(dc_iostream_t **iostream, dc_context_t *context, dc_usbhid_device_t *device);

### Parameters
- **iostream** (dc_iostream_t **) - Output parameter. On success, filled with an open iostream handle.
- **context** (dc_context_t *) - A context opened with dc_context_new(3).
- **device** (dc_usbhid_device_t *) - A USB HID device, usually found by searching through dc_usbhid_iterator_new(3).

### Return Values
Returns DC_STATUS_SUCCESS on success or one of several error values on error. On success, the iostream pointer is filled in with an open handle.

### See Also
dc_context_new(3), dc_usbhid_iterator_new(3), dc_iostream_close(3), dc_serial_open(3), dc_irda_open(3), dc_bluetooth_open(3).

```

--------------------------------

### dc_usbhid_iterator_new

Source: https://www.libdivecomputer.org/doc/dc_usbhid_iterator_new.3.html

Creates an iterator to enumerate USB HID devices matching the given descriptor. Takes a context and descriptor, and on success returns an iterator that can be used to iterate over available USB HID devices.

```APIDOC
## dc_usbhid_iterator_new

### Description
Creates an iterator to enumerate the USB HID devices matching the given descriptor. Accepts a context opened with dc_context_new(3) and a descriptor usually found by searching through dc_descriptor_iterator(3). On returning DC_STATUS_SUCCESS the iterator will be set to an dc_iterator_t which can be used to iterate the available USB HID devices using dc_iterator_next(3).

### Library
library \"libdivecomputer\"

### Synopsis
#include <libdivecomputer/usbhid.h>

dc_status_t dc_usbhid_iterator_new(dc_iterator_t **iterator, dc_context_t *context, dc_descriptor_t *descriptor);

### Parameters
- **iterator** (dc_iterator_t **) - Output parameter that will point to the newly created iterator on success.
- **context** (dc_context_t *) - Context opened with dc_context_new(3).
- **descriptor** (dc_descriptor_t *) - Descriptor used to filter matching USB HID devices, usually obtained from dc_descriptor_iterator(3).

### Return Values
Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure. On success, the returned iterator needs to be freed when done using dc_iterator_free(3).

### Notes
The iterator value type is dc_usbhid_device_t. This value can be used with dc_usbhid_device_get_pid(3) and dc_usbhid_device_get_vid(3) to extract information about the USB HID device. When done with the device, it needs to be freed with dc_usbhid_device_free(3). After iterating, the iterator must be freed with dc_iterator_free(3).
```

--------------------------------

### dc_usbhid_device_get_vid

Source: https://www.libdivecomputer.org/doc/dc_usbhid_device_get_vid.3.html

Documentation for the dc_usbhid_device_get_vid function, which retrieves the vendor ID of a USB HID device.

```APIDOC
## dc_usbhid_device_get_vid

### Description
Get the vendor id (VID) of the USB HID device. Used for displaying.

### Syntax
```c
#include <libdivecomputer/usbhid.h>

unsigned int dc_usbhid_device_get_vid(dc_usbhid_device_t *device);
```

### Parameters
- **device** (dc_usbhid_device_t *) - Required - A valid USB HID device of type `dc_usbhid_device_t`, which can be retrieved using `dc_usbhid_iterator_new(3)`.

### Return Value
Returns the vendor id (VID) of the given USB HID device.

### Library
library "libdivecomputer"

### See Also
- `dc_usbhid_device_get_vid(3)`
- `dc_usbhid_iterator_new(3)`
```

--------------------------------

### dc_bluetooth_open

Source: https://www.libdivecomputer.org/doc/dc_bluetooth_open.3.html

Opens an iostream for a bluetooth device. Accepts a context, a 48-bit bluetooth address, and a bluetooth rfcomm port number (use 0 for autodetection). On success, the iostream pointer is filled with an open handle that must be freed with dc_iostream_close(3).

```APIDOC
## dc_bluetooth_open

### Description
Opens an iostream for a bluetooth device. Accepts a context opened with dc_context_new(3), a 48-bit bluetooth address given by dc_bluetooth_iterator_new(3) together with dc_bluetooth_device_get_address(3) or dc_bluetooth_str2addr(3) and a bluetooth rfcomm port number (use 0 for autodetection). Upon returning DC_STATUS_SUCCESS, the iostream pointer must be freed with dc_iostream_close(3).

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/bluetooth.h>

dc_status_t dc_bluetooth_open(dc_iostream_t **iostream, dc_context_t *context, dc_bluetooth_address_t address, unsigned int port);

### Parameters
- **iostream** (dc_iostream_t **) - Output parameter. On success, filled with an open handle.
- **context** (dc_context_t *) - A context opened with dc_context_new(3).
- **address** (dc_bluetooth_address_t) - A 48-bit bluetooth address.
- **port** (unsigned int) - A bluetooth rfcomm port number. Use 0 for autodetection.

### Return Values
Returns DC_STATUS_SUCCESS on success or one of several error values on error. On success, the iostream pointer is filled in with an open handle.

### See Also
dc_context_new(3), dc_iostream_close(3), dc_serial_open(3), dc_irda_open(3), dc_usbhid_open(3), dc_bluetooth_iterator_new(3), dc_bluetooth_device_get_address(3), dc_bluetooth_str2addr(3)
```

--------------------------------

### dc_serial_open

Source: https://www.libdivecomputer.org/doc/dc_serial_open.3.html

Opens an iostream for a serial device. Accepts a context and a device name, and returns a status code. On success, the iostream pointer must be freed with dc_iostream_close.

```APIDOC
## dc_serial_open

### Description
Opens an iostream for a serial device. Accepts a context opened with dc_context_new(3) and a device name, usually found through dc_serial_iterator_new(3) with dc_serial_device_get_name(3).

### Function Signature
```c
dc_status_t dc_serial_open(dc_iostream_t **iostream, dc_context_t *context, const char *name);
```

### Parameters
- **iostream** (dc_iostream_t **) - Output parameter. On success, filled with an open handle.
- **context** (dc_context_t *) - A context opened with dc_context_new(3).
- **name** (const char *) - Device name, usually obtained via dc_serial_iterator_new(3) and dc_serial_device_get_name(3).

### Return Values
Returns `DC_STATUS_SUCCESS` on success or one of several error values on error.

### Notes
Upon returning `DC_STATUS_SUCCESS`, the iostream pointer must be freed with dc_iostream_close(3).

### See Also
dc_context_new(3), dc_iostream_close(3), dc_usbhid_open(3), dc_irda_open(3), dc_bluetooth_open(3), dc_serial_iterator_new(3), dc_serial_device_get_name(3).
```

--------------------------------

### dc_parser_samples_foreach

Source: https://www.libdivecomputer.org/doc/dc_parser_samples_foreach.3.html

Iterates over samples taken during a dive, invoking a callback for each sample. The callback receives the sample type and value.

```APIDOC
## dc_parser_samples_foreach

### Description
Iterates over samples taken during a dive, invoking a callback for each sample. The callback receives the sample type and value.

### Function Signature
```c
dc_status_t dc_parser_samples_foreach(dc_parser_t *parser, dc_sample_callback_t callback, void *userdata);
```

### Parameters
- **parser** (dc_parser_t *) - Required - The parser object previously initialized with dc_parser_set_data.
- **callback** (dc_sample_callback_t) - Required - A function pointer that will be called for each sample.
- **userdata** (void *) - Required - User-defined data passed to the callback.

### Callback Signature
```c
typedef void (*dc_sample_callback_t)(dc_sample_type_t type, dc_sample_value_t value, void *userdata);
```

### Sample Types
- **DC_SAMPLE_TIME** - The time of the sample in seconds after the dive began. Set in the time field.
- **DC_SAMPLE_DEPTH** - The depth in metres. Set in the depth field.
- **DC_SAMPLE_PRESSURE** - Tank pressure in bar. Sets the tank index and pressure.
- **DC_SAMPLE_TEMPERATURE** - Temperature in celsius. Sets the temperature field.
- **DC_SAMPLE_EVENT** - A diving event. The type field may be one of the SAMPLE_EVENT_* values.
- **DC_SAMPLE_RBT** - Remaining bottom time in seconds. Sets the rbt field.
- **DC_SAMPLE_HEARTBEAT** - Heartbeat in beats per minute. Sets the heartbeat field.
- **DC_SAMPLE_BEARING** - Bearing in degrees. Sets the bearing field.
- **DC_SAMPLE_VENDOR** - Vendor-specific data field.
- **DC_SAMPLE_SETPOINT** - Closed-circuit setpoint (PO2) in bar. Sets the setpoint value.
- **DC_SAMPLE_PPO2** - Partial pressure of oxygen in bar. Sets the ppo2 field.
- **DC_SAMPLE_CNS** - CNS value as a unit fraction. Sets the cns value.
- **DC_SAMPLE_DECO** - Decompression phase. Sets depth and time.
- **DC_SAMPLE_GASMIX** - Switch to a gas mix index. Sets the gasmix field.

### Return Value
Returns DC_STATUS_OK on success, or another error code on failure.

### Example
```c
#include <libdivecomputer/parser.h>

void sample_callback(dc_sample_type_t type, dc_sample_value_t value, void *userdata) {
    // Handle sample
}

dc_status_t status = dc_parser_samples_foreach(parser, sample_callback, NULL);
```
```

--------------------------------

### dc_irda_open

Source: https://www.libdivecomputer.org/doc/dc_irda_open.3.html

Opens an iostream for an IrDA (Infra Red) device. Accepts a context, an address, and an LSAP port number. On success, the iostream pointer must be freed with dc_iostream_close.

```APIDOC
## dc_irda_open

### Description
Opens an iostream for an IrDA (Infra Red) device. Accepts a context opened with dc_context_new(3), an address given through dc_irda_iterator_new(3) together with dc_irda_device_get_address(3), and an LSAP port number used during communication. Currently only Uwatec computers use IrDA communication and for those the LSAP can be hardcoded to 1.

### Function Signature
```c
dc_status_t dc_irda_open(dc_iostream_t **iostream, dc_context_t *context, unsigned int address, unsigned int lsap);
```

### Parameters
- **iostream** (dc_iostream_t **) - Output parameter. On success, filled with an open handle.
- **context** (dc_context_t *) - A context opened with dc_context_new(3).
- **address** (unsigned int) - The device address obtained from dc_irda_device_get_address(3).
- **lsap** (unsigned int) - A port number used during communication. For Uwatec computers, can be hardcoded to 1.

### Return Values
Returns DC_STATUS_SUCCESS on success or one of several error values on error. On success, the iostream pointer is filled with an open handle.

### Notes
Upon returning DC_STATUS_SUCCESS, the iostream pointer must be freed with dc_iostream_close(3).

### See Also
dc_context_new(3), dc_iostream_close(3), dc_serial_open(3), dc_usbhid_open(3), dc_bluetooth_open(3), dc_irda_iterator_new(3), dc_irda_device_get_address(3).
```

--------------------------------

### dc_usbhid_device_get_pid

Source: https://www.libdivecomputer.org/doc/dc_usbhid_device_get_pid.3.html

Retrieves the product ID (PID) of a USB HID device. Requires a valid dc_usbhid_device_t object obtained from dc_usbhid_iterator_new(3).

```APIDOC
## dc_usbhid_device_get_pid

### Description
Get the product id (PID) of the USB HID device. Used for displaying.

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/usbhid.h>

unsigned int dc_usbhid_device_get_pid(dc_usbhid_device_t *device);

### Parameters
- **device** (dc_usbhid_device_t *) - Required - A valid USB HID device object obtained from dc_usbhid_iterator_new(3).

### Return Value
Returns the product id (PID) of the given usbhid_device.

### See Also
dc_usbhid_device_get_vid(3), dc_usbhid_iterator_new(3).
```

--------------------------------

### dc_bluetooth_iterator_new

Source: https://www.libdivecomputer.org/doc/dc_bluetooth_iterator_new.3.html

Creates an iterator to enumerate bluetooth devices matching the given descriptor. The iterator can be used with dc_iterator_next to retrieve bluetooth device information.

```APIDOC
## dc_bluetooth_iterator_new

### Description
Creates an iterator to enumerate the available bluetooth devices that match the given descriptor. The iterator can be used to iterate through bluetooth devices using dc_iterator_next.

### Library
libdivecomputer

### Header
#include <libdivecomputer/bluetooth.h>

### Signature
dc_status_t dc_bluetooth_iterator_new(dc_iterator_t **iterator, dc_context_t *context, dc_descriptor_t *descriptor);

### Parameters
- **iterator** (dc_iterator_t **) - Output parameter. On success, set to a new iterator that can be used to iterate bluetooth devices.
- **context** (dc_context_t *) - A context opened with dc_context_new.
- **descriptor** (dc_descriptor_t *) - A descriptor usually found by searching through dc_descriptor_iterator.

### Return Values
Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure. On success, the returned iterator must be freed with dc_iterator_free when done.

### Usage Notes
The iterator yields values of type dc_bluetooth_device_t. Use dc_bluetooth_device_get_name and dc_bluetooth_device_get_address to extract information. Each bluetooth device must be freed with dc_bluetooth_device_free. After iterating, free the iterator with dc_iterator_free.

### See Also
dc_context_new, dc_usbhid_iterator_new, dc_serial_iterator_new, dc_irda_iterator_new, dc_bluetooth_device_get_name, dc_bluetooth_device_get_address, dc_bluetooth_device_free
```

--------------------------------

### dc_irda_iterator_new

Source: https://www.libdivecomputer.org/doc/dc_irda_iterator_new.3.html

Creates an iterator to enumerate IrDA devices matching the given descriptor. The iterator is used with dc_iterator_next to iterate over available IrDA devices, and must be freed with dc_iterator_free.

```APIDOC
## dc_irda_iterator_new

### Description
Creates an iterator to enumerate the IrDA devices that match the given descriptor. The iterator can be used with dc_iterator_next to iterate over available IrDA devices, and must be freed with dc_iterator_free when done.

### Library
libdivecomputer

### Synopsis
#include <libdivecomputer/irda.h>

dc_status_t dc_irda_iterator_new(dc_iterator_t **iterator, dc_context_t *context, dc_descriptor_t *descriptor);

### Parameters
- **iterator** (dc_iterator_t **) - Output parameter. On success, set to a pointer to the newly created iterator.
- **context** (dc_context_t *) - A context opened with dc_context_new.
- **descriptor** (dc_descriptor_t *) - A descriptor usually found by searching through dc_descriptor_iterator.

### Return Values
Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure. On success, the returned iterator must be freed with dc_iterator_free when done.

### Usage Notes
The iterator yields values of type dc_irda_device_t. These values can be used with dc_irda_device_get_name and dc_irda_device_get_address to extract device information, and must be freed with dc_irda_device_free when done.

### See Also
dc_context_new(3), dc_usbhid_iterator_new(3), dc_serial_iterator_new(3), dc_bluetooth_iterator_new(3), dc_irda_device_get_name(3), dc_irda_device_get_address(3), dc_irda_device_free(3).
```

--------------------------------

### dc_iostream_close(dc_iostream_t *iostream)

Source: https://www.libdivecomputer.org/doc/dc_iostream_close.3.html

Closes the I/O stream and frees all resources. Accepts the iostream to close and free. Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure.

```APIDOC
## dc_iostream_close(dc_iostream_t *iostream)

### Description
Close the I/O stream and free all resources. Accepts the iostream to close and free.

### Library
library "libdivecomputer"

### Include
#include <libdivecomputer/iostream.h>

### Signature
dc_status_t dc_iostream_close(dc_iostream_t *iostream);

### Parameters
- **iostream** (dc_iostream_t *) - Required - The I/O stream to close and free.

### Return Values
Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure.

### See Also
dc_usbhid_open(3), dc_serial_open(3), dc_irda_open(3), dc_bluetooth_open(3).
```

--------------------------------

### dc_context_set_loglevel

Source: https://www.libdivecomputer.org/doc/dc_context_set_loglevel.3.html

Sets the minimum log level required to raise a logging event with the dc_context_set_logfunc callback. Operates on a dive computer context created with dc_context_new.

```APIDOC
## dc_context_set_loglevel

### Description
Sets the minimum log level required to raise a logging event with the dc_context_set_logfunc(3) callback. Operates on a dive computer context created with dc_context_new(3).

### Library
libdivecomputer

### Synopsis
#include <libdivecomputer/context.h>

dc_status_t dc_context_set_loglevel(dc_context_t *context, dc_loglevel_t loglevel);

### Parameters
- **context** (dc_context_t *) - Required - The dive computer context.
- **loglevel** (dc_loglevel_t) - Required - The minimum log level to set. Must be one of: DC_LOGLEVEL_NONE, DC_LOGLEVEL_ERROR, DC_LOGLEVEL_WARNING, DC_LOGLEVEL_INFO, DC_LOGLEVEL_DEBUG, DC_LOGLEVEL_ALL.

### Description
Log levels are ordered as follows: DC_LOGLEVEL_NONE, DC_LOGLEVEL_ERROR, DC_LOGLEVEL_WARNING, DC_LOGLEVEL_INFO, DC_LOGLEVEL_DEBUG, DC_LOGLEVEL_ALL. Setting a level such as DC_LOGLEVEL_INFO will report all events of DC_LOGLEVEL_ERROR, DC_LOGLEVEL_WARNING, and DC_LOGLEVEL_INFO via the callback in dc_context_set_logfunc(3).

### Return Values
Returns DC_STATUS_OK on success, DC_STATUS_INVALIDARGS if context is NULL, or another error code on failure.

### See Also
dc_context_new(3), dc_context_set_logfunc(3)
```

--------------------------------

### dc_device_close

Source: https://www.libdivecomputer.org/doc/dc_device_close.3.html

Documentation for the dc_device_close function, which closes a dive computer device.

```APIDOC
## dc_device_close

### Description
Closes a dive computer device opened with dc_device_open(3). If device is NULL, this returns DC_STATUS_SUCCESS.

### Prototype
```c
dc_status_t dc_device_close(dc_device_t *device);
```

### Parameters
- **device** (dc_device_t *) - Required - Pointer to the device to close.

### Return Values
Returns DC_STATUS_SUCCESS on success or one of several error values on error.

### See Also
dc_device_open(3)
```

--------------------------------

### dc_usbhid_device_free

Source: https://www.libdivecomputer.org/doc/dc_usbhid_device_free.3.html

Destroys the USB HID device and frees all resources. The device is usually found by searching through dc_usbhid_iterator_new(3).

```APIDOC
## dc_usbhid_device_free

### Description
Destroys the USB HID device and frees all resources. The usbhid device is usually found by searching through dc_usbhid_iterator_new(3).

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/usbhid.h>

void dc_usbhid_device_free(dc_usbhid_device_t *device);

### Parameters
- **device** (dc_usbhid_device_t *) - Required - Pointer to the USB HID device to destroy.

### Return Value
None (void).

### See Also
dc_usbhid_iterator_new(3)
```

--------------------------------

### dc_context_set_logfunc

Source: https://www.libdivecomputer.org/doc/dc_context_set_logfunc.3.html

Sets the logging function for a dive computer context. The logging function is invoked with userdata when the log level has been exceeded.

```APIDOC
## dc_context_set_logfunc

### Description
Sets the logging function for a dive computer context. The logging function is invoked with userdata when the log level (see dc_context_set_loglevel(3)) has been exceeded.

### Function Signature
```c
dc_status_t dc_context_set_logfunc(dc_context_t *context, dc_logfunc_t logfunc, void *userdata);
```

### Parameters
- **context** (dc_context_t *) - The dive computer context.
- **logfunc** (dc_logfunc_t) - The logging function to set.
- **userdata** (void *) - Pointer passed to the logging function when invoked.

### Callback Type
```c
typedef void (*dc_logfunc_t)(dc_context_t *context, dc_loglevel_t loglevel, const char *file, unsigned int line, const char *function, const char *message, void *userdata);
```

### Callback Parameters
- **context** - The context in which it was invoked.
- **loglevel** - The level of the log message.
- **file** - The source file where the message was raised.
- **line** - The source line (from 1) where the message was raised.
- **function** - The function that raised the log message.
- **message** - The log message itself.
- **userdata** - The pointer passed to dc_context_set_logfunc.

### Return Values
Returns DC_STATUS_OK on setting the log level, DC_STATUS_INVALIDARGS if context is NULL, or another error code on failure.

### See Also
dc_context_new(3), dc_context_set_loglevel(3)
```

--------------------------------

### dc_serial_iterator_new

Source: https://www.libdivecomputer.org/doc/dc_serial_iterator_new.3.html

Creates an iterator to enumerate serial devices matching a given descriptor. The iterator yields dc_serial_device_t values that can be used to extract device information.

```APIDOC
## dc_serial_iterator_new

### Description
Creates an iterator to enumerate the available serial devices matching the given descriptor. The iterator yields dc_serial_device_t values that can be used to extract device information.

### Function Signature
```c
dc_status_t dc_serial_iterator_new(dc_iterator_t **iterator, dc_context_t *context, dc_descriptor_t *descriptor);
```

### Parameters
- **iterator** (dc_iterator_t **) - Output parameter. On success, set to a new iterator that can be used with dc_iterator_next(3).
- **context** (dc_context_t *) - A context opened with dc_context_new(3).
- **descriptor** (dc_descriptor_t *) - A descriptor usually found by searching through dc_descriptor_iterator(3).

### Return Value
Returns DC_STATUS_SUCCESS on success, or another dc_status_t code on failure. On success, the returned iterator must be freed with dc_iterator_free(3) when done.

### Usage Notes
- The iterator yields values of type dc_serial_device_t.
- Use dc_serial_device_get_name(3) to extract information about each device.
- Free each device with dc_serial_device_free(3) when done.
- Free the iterator with dc_iterator_free(3) after iteration.

### See Also
dc_context_new(3), dc_usbhid_iterator_new(3), dc_irda_iterator_new(3), dc_bluetooth_iterator_new(3), dc_serial_device_get_name(3), dc_serial_device_free(3).
```

--------------------------------

### dc_bluetooth_addr2str

Source: https://www.libdivecomputer.org/doc/dc_bluetooth_addr2str.3.html

Documentation for the dc_bluetooth_addr2str function, which converts a bluetooth address to a string.

```APIDOC
## dc_bluetooth_addr2str

### Description
Convert a bluetooth address to a string. The bluetooth address is formatted as XX:XX:XX:XX:XX:XX, where each XX is a hexadecimal number specifying an octet of the 48-bit address. The minimum size for the buffer is DC_BLUETOOTH_SIZE bytes.

### Library
libdivecomputer

### Header
#include <libdivecomputer/bluetooth.h>

### Syntax
const char* dc_bluetooth_addr2str(dc_bluetooth_address_t address, char *str, size_t size);

### Parameters
- **address** (dc_bluetooth_address_t) - Required - The bluetooth address to convert.
- **str** (char *) - Required - Pointer to a buffer where the resulting string will be stored. The buffer must be at least DC_BLUETOOTH_SIZE bytes.
- **size** (size_t) - Required - Size of the buffer pointed to by str.

### Return Value
Returns the bluetooth address represented as a string.

### See Also
dc_bluetooth_str2addr(3)
```

--------------------------------

### dc_serial_device_free

Source: https://www.libdivecomputer.org/doc/dc_serial_device_free.3.html

Destroys the serial device and frees all resources. The serial device is typically obtained from dc_serial_iterator_new(3).

```APIDOC
## dc_serial_device_free

### Description
Destroys the serial device and frees all resources. The serial device is usually found by searching through dc_serial_iterator_new(3).

### Function Signature
void dc_serial_device_free(dc_serial_device_t *device);

### Parameters
- **device** (dc_serial_device_t *) - Required - Pointer to the serial device to be destroyed.

### Return Value
None (void).

### Library
libdivecomputer

### Header File
#include <libdivecomputer/serial.h>

### See Also
dc_serial_iterator_new(3)
```

--------------------------------

### dc_iterator_next

Source: https://www.libdivecomputer.org/doc/dc_iterator_next.3.html

Fills in item with the next element in the iterator. The iterator must not be NULL. Returns DC_STATUS_SUCCESS on success.

```APIDOC
## dc_iterator_next

### Description
Fills in item with the next element in the iterator iterator, which may not be NULL.

### Library
libdivecomputer

### Header
#include <libdivecomputer/iterator.h>

### Signature
dc_status_t dc_iterator_next(dc_iterator_t *iterator, void *item);

### Parameters
- **iterator** (dc_iterator_t *) - Required - The iterator from which to retrieve the next element. Must not be NULL.
- **item** (void *) - Required - Pointer to a memory location where the next element will be stored.

### Return Values
- **DC_STATUS_SUCCESS** - On success.

```

--------------------------------

### dc_device_set_fingerprint

Source: https://www.libdivecomputer.org/doc/dc_device_set_fingerprint.3.html

Sets the last-seen dive fingerprint on a device opened with dc_device_open(3). This is used to download only dives newer than the last seen dive.

```APIDOC
## dc_device_set_fingerprint

### Description
Sets the last-seen dive fingerprint on a device opened with dc_device_open(3). This mechanism is used to only download dives "newer" (as reported by the dive computer, not necessarily on the calendar) than the last seen dive.

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/device.h>

dc_status_t
dc_device_set_fingerprint(dc_device_t *device, const unsigned char data[], unsigned int size);

### Parameters
- **device** (dc_device_t *) - Required - The device handle obtained from dc_device_open(3).
- **data** (const unsigned char[]) - Required - The fingerprint data to set.
- **size** (unsigned int) - Required - The size of the fingerprint data in bytes.

### Return Values
Returns `DC_STATUS_SUCCESS` if the fingerprint was set, or one of several error values on error.

### Usage
In general usage, the fingerprint is acquired (and saved) from the first dive downloaded from a dive computer by dc_device_foreach(3). In subsequent openings of the device, the fingerprint is set with `dc_device_set_fingerprint` and, when a dive reports a fingerprint matching that dive, the download exits before reporting that dive. (The first fingerprint is saved again for subsequent invocations.) In this way, only the newest dives are reported.

### See Also
dc_device_open(3)
```

--------------------------------

### dc_bluetooth_device_get_address

Source: https://www.libdivecomputer.org/doc/dc_bluetooth_device_get_address.3.html

Retrieves the bluetooth address of a given bluetooth device. The address is returned as a 64-bit integer and can be formatted as a string using dc_bluetooth_addr2str.

```APIDOC
## dc_bluetooth_device_get_address

### Description
Get the bluetooth device address of a given bluetooth device. Required when opening transport communication with dc_bluetooth_open(3). Requires a valid device of type dc_bluetooth_device_t which can be retrieved using dc_bluetooth_iterator_new(3).

### Library
library "libdivecomputer"

### Synopsis
#include <libdivecomputer/bluetooth.h>

dc_bluetooth_address_t dc_bluetooth_device_get_address(dc_bluetooth_device_t *device);

### Parameters
- **device** (dc_bluetooth_device_t *) - Required - A valid bluetooth device obtained from dc_bluetooth_iterator_new(3).

### Return Values
Returns the bluetooth address of the device as dc_bluetooth_address_t, which is a 64-bit integer holding the bluetooth address. The address can be formatted as a string using dc_bluetooth_addr2str(3).

### See Also
dc_bluetooth_open(3), dc_bluetooth_iterator_new(3), dc_bluetooth_device_get_name(3), dc_bluetooth_addr2str(3).
```
Tokens:
Raw