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.