api.h

Go to the documentation of this file.

#pragma once
#ifdef __cplusplus
extern "C" {
#endif
#include <stddef.h>
#include <stdint.h>
 
/* ========================================================================
 * Version and ABI Constants
 * ======================================================================== */
#define DUVC_VERSION_MAJOR 1
#define DUVC_VERSION_MINOR 0
#define DUVC_VERSION_PATCH 0
#define DUVC_ABI_VERSION                                                       \
  ((DUVC_VERSION_MAJOR << 16) | (DUVC_VERSION_MINOR << 8) | DUVC_VERSION_PATCH)
 
/* ========================================================================
 * Core Enumerations
 * ======================================================================== */
typedef enum {
  DUVC_SUCCESS = 0,            
  DUVC_ERROR_NOT_IMPLEMENTED,  
  DUVC_ERROR_INVALID_ARGUMENT, 
  DUVC_ERROR_DEVICE_NOT_FOUND, 
  DUVC_ERROR_DEVICE_BUSY, 
  DUVC_ERROR_PROPERTY_NOT_SUPPORTED, 
  DUVC_ERROR_INVALID_VALUE,          
  DUVC_ERROR_PERMISSION_DENIED, 
  DUVC_ERROR_SYSTEM_ERROR,      
  DUVC_ERROR_CONNECTION_FAILED, 
  DUVC_ERROR_TIMEOUT,           
  DUVC_ERROR_BUFFER_TOO_SMALL   
} duvc_result_t;
 
typedef enum {
  DUVC_CAM_PROP_PAN = 0,           
  DUVC_CAM_PROP_TILT,              
  DUVC_CAM_PROP_ROLL,              
  DUVC_CAM_PROP_ZOOM,              
  DUVC_CAM_PROP_EXPOSURE,          
  DUVC_CAM_PROP_IRIS,              
  DUVC_CAM_PROP_FOCUS,             
  DUVC_CAM_PROP_SCAN_MODE,         
  DUVC_CAM_PROP_PRIVACY,           
  DUVC_CAM_PROP_PAN_RELATIVE,      
  DUVC_CAM_PROP_TILT_RELATIVE,     
  DUVC_CAM_PROP_ROLL_RELATIVE,     
  DUVC_CAM_PROP_ZOOM_RELATIVE,     
  DUVC_CAM_PROP_EXPOSURE_RELATIVE, 
  DUVC_CAM_PROP_IRIS_RELATIVE,     
  DUVC_CAM_PROP_FOCUS_RELATIVE,    
  DUVC_CAM_PROP_PAN_TILT,          
  DUVC_CAM_PROP_PAN_TILT_RELATIVE, 
  DUVC_CAM_PROP_FOCUS_SIMPLE,      
  DUVC_CAM_PROP_DIGITAL_ZOOM,      
  DUVC_CAM_PROP_DIGITAL_ZOOM_RELATIVE,  
  DUVC_CAM_PROP_BACKLIGHT_COMPENSATION, 
  DUVC_CAM_PROP_LAMP                    
} duvc_cam_prop_t;
 
typedef enum {
  DUVC_VID_PROP_BRIGHTNESS = 0,         
  DUVC_VID_PROP_CONTRAST,               
  DUVC_VID_PROP_HUE,                    
  DUVC_VID_PROP_SATURATION,             
  DUVC_VID_PROP_SHARPNESS,              
  DUVC_VID_PROP_GAMMA,                  
  DUVC_VID_PROP_COLOR_ENABLE,           
  DUVC_VID_PROP_WHITE_BALANCE,          
  DUVC_VID_PROP_BACKLIGHT_COMPENSATION, 
  DUVC_VID_PROP_GAIN,                   
  DUVC_VID_PROP_DIGITAL_MULTIPLIER,        
  DUVC_VID_PROP_DIGITAL_MULTIPLIER_LIMIT, 
  DUVC_VID_PROP_WHITE_BALANCE_COMPONENT,  
  DUVC_VID_PROP_POWER_LINE_FREQUENCY     
} duvc_vid_prop_t;
 
typedef enum {
  DUVC_CAM_MODE_AUTO = 0, 
  DUVC_CAM_MODE_MANUAL    
} duvc_cam_mode_t;
 
typedef enum {
  DUVC_LOG_DEBUG = 0, 
  DUVC_LOG_INFO,      
  DUVC_LOG_WARNING,   
  DUVC_LOG_ERROR,     
  DUVC_LOG_CRITICAL   
} duvc_log_level_t;
 
typedef enum {
  DUVC_LOGITECH_PROP_RIGHT_LIGHT = 1,  
  DUVC_LOGITECH_PROP_RIGHT_SOUND,      
  DUVC_LOGITECH_PROP_FACE_TRACKING,    
  DUVC_LOGITECH_PROP_LED_INDICATOR,    
  DUVC_LOGITECH_PROP_PROCESSOR_USAGE,  
  DUVC_LOGITECH_PROP_RAW_DATA_BITS,    
  DUVC_LOGITECH_PROP_FOCUS_ASSIST,     
  DUVC_LOGITECH_PROP_VIDEO_STANDARD,   
  DUVC_LOGITECH_PROP_DIGITAL_ZOOM_ROI, 
  DUVC_LOGITECH_PROP_TILT_PAN          
} duvc_logitech_prop_t;
 
/* ========================================================================
 * Core Data Structures
 * ======================================================================== */
typedef struct {
  int32_t value;        
  duvc_cam_mode_t mode; 
} duvc_prop_setting_t;
 
typedef struct {
  int32_t min;                  
  int32_t max;                  
  int32_t step;                 
  int32_t default_val;          
  duvc_cam_mode_t default_mode; 
} duvc_prop_range_t;
 
typedef struct {
  char property_set_guid[39]; 
  uint32_t property_id;       
  void *data;                 
  size_t data_size;           
} duvc_vendor_property_t;
 
typedef struct duvc_device_t duvc_device_t;
 
typedef struct duvc_connection_t duvc_connection_t;
 
typedef struct duvc_device_capabilities_t duvc_device_capabilities_t;
 
/* ========================================================================
 * Callback Types
 * ======================================================================== */
typedef void (*duvc_log_callback)(duvc_log_level_t level, const char *message,
                                  void *user_data);
 
typedef void (*duvc_device_change_callback)(int added, const char *device_path,
                                            void *user_data);
 
/* ========================================================================
 * Constants
 * ======================================================================== */
extern const char DUVC_LOGITECH_PROPERTY_SET_GUID[39];
 
/* ========================================================================
 * Version and ABI Management
 * ======================================================================== */
uint32_t duvc_get_version(void);
 
const char *duvc_get_version_string(void);
 
int duvc_check_abi_compatibility(uint32_t compiled_version);
 
/* ========================================================================
 * Library Lifecycle
 * ======================================================================== */
duvc_result_t duvc_initialize(void);
 
void duvc_shutdown(void);
 
int duvc_is_initialized(void);
 
/* ========================================================================
 * Logging System
 * ======================================================================== */
duvc_result_t duvc_set_log_callback(duvc_log_callback callback,
                                    void *user_data);
 
duvc_result_t duvc_set_log_level(duvc_log_level_t level);
 
duvc_result_t duvc_get_log_level(duvc_log_level_t *level);
 
duvc_result_t duvc_log_message(duvc_log_level_t level, const char *message);
 
duvc_result_t duvc_log_debug(const char *message);
 
duvc_result_t duvc_log_info(const char *message);
 
duvc_result_t duvc_log_warning(const char *message);
 
duvc_result_t duvc_log_error(const char *message);
 
duvc_result_t duvc_log_critical(const char *message);
 
/* ========================================================================
 * Device Management
 * ======================================================================== */
duvc_result_t duvc_list_devices(duvc_device_t ***devices, size_t *count);
 
duvc_result_t duvc_find_device_by_path(const char *device_path_utf8,
                                       duvc_device_t **device);
 
void duvc_free_device_list(duvc_device_t **devices, size_t count);
 
duvc_result_t duvc_is_device_connected(const duvc_device_t *device,
                                       int *connected);
 
duvc_result_t duvc_get_device_name(const duvc_device_t *device, char *buffer,
                                   size_t buffer_size, size_t *required);
 
duvc_result_t duvc_get_device_path(const duvc_device_t *device, char *buffer,
                                   size_t buffer_size, size_t *required);
 
duvc_result_t duvc_get_device_id(const duvc_device_t *device, char *buffer,
                                 size_t buffer_size, size_t *required);
 
duvc_result_t duvc_device_is_valid(const duvc_device_t *device, int *valid);
 
/* ========================================================================
 * Device Change Monitoring
 * ======================================================================== */
duvc_result_t
duvc_register_device_change_callback(duvc_device_change_callback callback,
                                     void *user_data);
 
void duvc_unregister_device_change_callback(void);
 
/* ========================================================================
 * Camera Connections
 * ======================================================================== */
duvc_result_t duvc_open_camera_by_index(int device_index,
                                        duvc_connection_t **conn);
 
duvc_result_t duvc_open_camera(const duvc_device_t *device,
                               duvc_connection_t **conn);
 
void duvc_close_camera(duvc_connection_t *conn);
 
int duvc_camera_is_valid(const duvc_connection_t *conn);
 
/* ========================================================================
 * Property Access - Single Properties
 * ======================================================================== */
duvc_result_t duvc_get_camera_property(duvc_connection_t *conn,
                                       duvc_cam_prop_t prop,
                                       duvc_prop_setting_t *setting);
 
duvc_result_t duvc_set_camera_property(duvc_connection_t *conn,
                                       duvc_cam_prop_t prop,
                                       const duvc_prop_setting_t *setting);
 
duvc_result_t duvc_get_camera_property_range(duvc_connection_t *conn,
                                             duvc_cam_prop_t prop,
                                             duvc_prop_range_t *range);
 
duvc_result_t duvc_get_video_property(duvc_connection_t *conn,
                                      duvc_vid_prop_t prop,
                                      duvc_prop_setting_t *setting);
 
duvc_result_t duvc_set_video_property(duvc_connection_t *conn,
                                      duvc_vid_prop_t prop,
                                      const duvc_prop_setting_t *setting);
 
duvc_result_t duvc_get_video_property_range(duvc_connection_t *conn,
                                            duvc_vid_prop_t prop,
                                            duvc_prop_range_t *range);
 
/* ========================================================================
 * Property Access - Multiple Properties
 * ======================================================================== */
duvc_result_t duvc_get_multiple_camera_properties(duvc_connection_t *conn,
                                                  const duvc_cam_prop_t *props,
                                                  duvc_prop_setting_t *settings,
                                                  size_t count);
 
duvc_result_t duvc_set_multiple_camera_properties(
    duvc_connection_t *conn, const duvc_cam_prop_t *props,
    const duvc_prop_setting_t *settings, size_t count);
 
duvc_result_t duvc_get_multiple_video_properties(duvc_connection_t *conn,
                                                 const duvc_vid_prop_t *props,
                                                 duvc_prop_setting_t *settings,
                                                 size_t count);
 
duvc_result_t duvc_set_multiple_video_properties(
    duvc_connection_t *conn, const duvc_vid_prop_t *props,
    const duvc_prop_setting_t *settings, size_t count);
 
/* ========================================================================
 * Quick API - Direct Device Access
 * ======================================================================== */
duvc_result_t duvc_quick_get_camera_property(const duvc_device_t *device,
                                             duvc_cam_prop_t prop,
                                             duvc_prop_setting_t *setting);
 
duvc_result_t
duvc_quick_set_camera_property(const duvc_device_t *device,
                               duvc_cam_prop_t prop,
                               const duvc_prop_setting_t *setting);
 
duvc_result_t duvc_quick_get_camera_property_range(const duvc_device_t *device,
                                                   duvc_cam_prop_t prop,
                                                   duvc_prop_range_t *range);
 
duvc_result_t duvc_quick_get_video_property(const duvc_device_t *device,
                                            duvc_vid_prop_t prop,
                                            duvc_prop_setting_t *setting);
 
duvc_result_t duvc_quick_set_video_property(const duvc_device_t *device,
                                            duvc_vid_prop_t prop,
                                            const duvc_prop_setting_t *setting);
 
duvc_result_t duvc_quick_get_video_property_range(const duvc_device_t *device,
                                                  duvc_vid_prop_t prop,
                                                  duvc_prop_range_t *range);
 
/* ========================================================================
 * Device Capability Snapshots
 * ======================================================================== */
duvc_result_t duvc_get_device_capabilities(const duvc_device_t *device,
                                           duvc_device_capabilities_t **caps);
 
duvc_result_t
duvc_get_device_capabilities_by_index(int device_index,
                                      duvc_device_capabilities_t **caps);
 
void duvc_free_device_capabilities(duvc_device_capabilities_t *caps);
 
duvc_result_t
duvc_refresh_device_capabilities(duvc_device_capabilities_t *caps);
 
/* ========================================================================
 * Capability Queries
 * ======================================================================== */
duvc_result_t duvc_get_camera_capability(const duvc_device_capabilities_t *caps,
                                         duvc_cam_prop_t prop,
                                         duvc_prop_range_t *range,
                                         duvc_prop_setting_t *current);
 
duvc_result_t duvc_get_video_capability(const duvc_device_capabilities_t *caps,
                                        duvc_vid_prop_t prop,
                                        duvc_prop_range_t *range,
                                        duvc_prop_setting_t *current);
 
duvc_result_t
duvc_supports_camera_property(const duvc_device_capabilities_t *caps,
                              duvc_cam_prop_t prop, int *supported);
 
duvc_result_t
duvc_supports_video_property(const duvc_device_capabilities_t *caps,
                             duvc_vid_prop_t prop, int *supported);
 
duvc_result_t
duvc_get_supported_camera_properties(const duvc_device_capabilities_t *caps,
                                     duvc_cam_prop_t *props, size_t max_count,
                                     size_t *actual_count);
 
duvc_result_t
duvc_get_supported_video_properties(const duvc_device_capabilities_t *caps,
                                    duvc_vid_prop_t *props, size_t max_count,
                                    size_t *actual_count);
 
duvc_result_t
duvc_capabilities_is_device_accessible(const duvc_device_capabilities_t *caps,
                                       int *accessible);
 
/* ========================================================================
 * Property Range Utilities
 * ======================================================================== */
duvc_result_t duvc_prop_range_is_valid(const duvc_prop_range_t *range,
                                       int32_t value, int *valid);
 
duvc_result_t duvc_prop_range_clamp(const duvc_prop_range_t *range,
                                    int32_t value, int32_t *clamped_value);
 
duvc_result_t duvc_prop_capability_supports_auto(const duvc_prop_range_t *range,
                                                 int *supports_auto);
 
/* ========================================================================
 * Generic Vendor Properties
 * ======================================================================== */
duvc_result_t duvc_get_vendor_property(const duvc_device_t *device,
                                       const char *property_set_guid,
                                       uint32_t property_id, void *data,
                                       size_t data_size,
                                       size_t *bytes_returned);
 
duvc_result_t duvc_set_vendor_property(const duvc_device_t *device,
                                       const char *property_set_guid,
                                       uint32_t property_id, const void *data,
                                       size_t data_size);
 
duvc_result_t duvc_query_vendor_property_support(const duvc_device_t *device,
                                                 const char *property_set_guid,
                                                 uint32_t property_id,
                                                 int *supported);
 
/* ========================================================================
 * Logitech Vendor Extensions
 * ======================================================================== */
duvc_result_t duvc_get_logitech_property(const duvc_device_t *device,
                                         duvc_logitech_prop_t prop, void *data,
                                         size_t data_size,
                                         size_t *bytes_returned);
 
duvc_result_t duvc_set_logitech_property(const duvc_device_t *device,
                                         duvc_logitech_prop_t prop,
                                         const void *data, size_t data_size);
 
duvc_result_t duvc_supports_logitech_properties(const duvc_device_t *device,
                                                int *supported);
 
/* ========================================================================
 * String Conversions
 * ======================================================================== */
const char *duvc_cam_prop_to_string(duvc_cam_prop_t prop);
 
const char *duvc_vid_prop_to_string(duvc_vid_prop_t prop);
 
const char *duvc_cam_mode_to_string(duvc_cam_mode_t mode);
 
const char *duvc_error_code_to_string(duvc_result_t code);
 
const char *duvc_log_level_to_string(duvc_log_level_t level);
 
/* ========================================================================
 * Wide String Conversions (Windows Support)
 * ======================================================================== */
duvc_result_t duvc_cam_prop_to_wstring(duvc_cam_prop_t prop, wchar_t *buffer,
                                       size_t buffer_size, size_t *required);
 
duvc_result_t duvc_vid_prop_to_wstring(duvc_vid_prop_t prop, wchar_t *buffer,
                                       size_t buffer_size, size_t *required);
 
duvc_result_t duvc_cam_mode_to_wstring(duvc_cam_mode_t mode, wchar_t *buffer,
                                       size_t buffer_size, size_t *required);
 
/* ========================================================================
 * Error Handling and Diagnostics
 * ======================================================================== */
duvc_result_t duvc_get_last_error_details(char *buffer, size_t buffer_size,
                                          size_t *required_size);
 
duvc_result_t duvc_get_diagnostic_info(char *buffer, size_t buffer_size,
                                       size_t *required_size);
 
int duvc_is_device_error(duvc_result_t result);
 
int duvc_is_permission_error(duvc_result_t result);
 
void duvc_clear_last_error(void);
 
/* ========================================================================
 * Windows-Specific Error Diagnostics
 * ======================================================================== */
#ifdef _WIN32
duvc_result_t duvc_decode_system_error(unsigned long error_code, char *buffer,
                                       size_t buffer_size, size_t *required);
 
duvc_result_t duvc_decode_hresult(int32_t hr, char *buffer, size_t buffer_size,
                                  size_t *required);
 
duvc_result_t duvc_get_hresult_details(int32_t hr, char *buffer,
                                       size_t buffer_size, size_t *required);
 
int duvc_is_hresult_device_error(int32_t hr);
 
int duvc_is_hresult_permission_error(int32_t hr);
#endif
 
/* ========================================================================
 * Convenience Macros for Logging
 * ======================================================================== */
#define DUVC_LOG_DEBUG(msg) duvc_log_debug(msg)
#define DUVC_LOG_INFO(msg) duvc_log_info(msg)
#define DUVC_LOG_WARNING(msg) duvc_log_warning(msg)
#define DUVC_LOG_ERROR(msg) duvc_log_error(msg)
#define DUVC_LOG_CRITICAL(msg) duvc_log_critical(msg)
 
/* ========================================================================
 * Additional Platform Utilities
 * ======================================================================== */
duvc_result_t duvc_has_camera_permissions(int *has_permissions);
 
duvc_result_t duvc_get_platform_info(char *buffer, size_t buffer_size,
                                     size_t *required);
 
#ifdef __cplusplus
}
#endif