Shared Library Changes for the Next Release (Draft)
Overview
The shared library libddcutil is not backwardly compatible. The SONAME is now libddcutil.so.5. The released library file is libddcutil.so.5.0.0. In conformance with Debian practice, the package name is libddcutil5.
To support programs that that use the old shared library, libddcuti.so.4 will continue to be published as package libddcutil4.
Because necessary changes required incrementing the major version of the shared library, it provided an opportunity to remove a large number of functions that were deprecated, made unnecessary by the ability to pass command line options to libddcutil, or otherwise cluttered the API and ABI. In practice, most existing programs will at most require recompilation to use the new version of the shared library.
Library Initialization
Library initialization has been reworked extensively to move operations that can fail, along with various settings that should be under control of the library user, into a new function ddca_init().
This function:
- controls the level of messages written to the system log
- optionally processes options obtained from the ddcutil configuration file
- processes additional options passed as a string
- sets error information for ddca_get_error_detail()
If this function is not called by the user program, any API function that relies on its processing invokes ddca_init() using arguments such that it never fails, e.g. the configuration file is not processed. As a result, most programs that use the shared library will work with just recompilation.
Execution Options
These new options apply only to libddcutil, not to ddcutil. They can be specified in configuration file $HOME/.config/ddcutil/ddcutilrc, or in the libopts string passed to ddca_init().
- Option --trcapi
: Trace the specified API function and its called functions. - Option --profile-api: Collect performance statistics for API functions that perform display IO, and report them when the shared library is terminated.
API changes
| New typedefs | Comments |
|---|---|
| DDCA_Init_Options | enum of ddca_init() options |
| DDCA_Syslog_Level | enum of ddcutil severity levels for msgs written to the system log |
| DDCA_HotplugFunc | signature of callback function reporting a display hotplug event |
| New Functions | Comments |
|---|---|
| ddca_init | Perform library initialization |
| ddca_libddcutil_filename | Returns the fully qualified name of the shared library |
| ddca_syslog_level_from_name | Given its symbolic name, return a DDCA_Syslog_Level value |
| ddca_register_display_hotplug_callback | Registers a function of type DDCA_Display_Hotplug_Func which will be called to inform the client of display hotplug events. |
| ddca_unregister_display_hotplug_callback | Unregister a callback |
| Changed Functions | Comments |
|---|---|
| ddca_set_sleep_multiplier | Operates on the display, if any, open in the current thread |
| ddca_get_sleep_multiplier | Returns the value for the display, if any, open in the current thread |
| ddca_get_display_list | Returns status code, sets error detail |
| ddca_report_display_info | Returns DDCA_Status instead of void |
| ddca_show_stats | Optionally report per-display stats, not per-thread stats |
| ddca_get_feature_name() | Implementation had been removed but the function remained in the API. This change restores the implementation. |
With the ability to configure libddcutil operation both by the ddcutil configuration file and by passing an option string in the ddca_init() arguments, many API functions are no longer needed and have been removed. These are unlikely to have been used by any existing clients other than ddcui.
| Removed Max-Tries Functions | Equivalent Option |
|---|---|
| ddca_max_max_tries | No option equivalent |
| ddca_get_max_tries | No option equivalent |
| ddca_set_max_tries | Use option --maxtries |
| Removed Sleep-Multiplier Functions | Comments |
|---|---|
| ddca_set_default_sleep_multiplier | Use option --sleep-multiplier |
| ddca_get_default_sleep_multiplier | No option equivalent |
| ddca_set_global_sleep_multiplier | Previously deprecated |
| ddca_get_global_sleep_multiplier | Previously deprecated |
| Removed USB Enablement Functions | Comments |
|---|---|
| ddca_enable_usb_display_detection | Use options --enable-usb / --disable-usb |
| ddca_is_usb_display_detection_enabled | No option equivalent |
| Removed Tracing Typedefs | Comments |
|---|---|
| DDCA_Trace_Options | used by ddca_set-trace_options() |
| Removed Tracing Functions | Comments |
|---|---|
| ddca_add_traced_function | Use option --trcfunc |
| ddca_add_traced_file | Use option --trcfile |
| ddca_set_trace_groups | Use option --trace |
| ddca_add_trace_groups | Use option --trace |
| ddca_trace_group_name_to_value | Not needed |
| ddca_set_trace_options | Use options --thread-id --timestamp, --wall-timestamp |
Most per-thread statistics are now instead maintained on a per-display basis. The following functions are no longer useful and have been removed:
| Removed Per-Thread Functions | Comments |
|---|---|
| ddca_set_thread_description | No longer useful |
| ddca_append_thread_description | No longer useful |
| ddca_get_thread_desription | No longer useful |
Remove previously deprecated functions that had been replaced by more useful alternatives:
| Removed Function | Comments |
|---|---|
| ddca_get_feature_name_by_dref | Had been replaced by ddca_get_feature_metadata_by_dref() |
| ddca_get_formatted_vcp_value | Did not support user defined features |
| ddca_open_display | Had been replaced by ddca_open_display2(). |
Miscellaneous
Symbols for functions and enums that had previously been removed from ddcutil_c_api.h are no longer exported.