C API Changes for Release 0.9.0
See also:
- Main C API Page
The C API has been extensively revised reflecting experience gained from work on a Qt C++ GUI interface.
New header files:
| File Name |
Contents |
| ddcutil_macros.h |
Macros to specify the ddcutil version at compile time |
| ddcutil_status_codes.h |
Status codes defined by ddcutil |
Multithreading
There is rudiementary support for multi-threaded use of the API.
Considerations:
- It is safe to perform simultaneous operations on separate displays (using distinct display handles) on separate threads.
- Multiple simultaneous DDC operations on the same display will have unpredictable results.
- Do not open multiple handles for the same display.
The ddcutil API prevents opening multiple handles for devices with the same DDCA_IO_Path,
which blocks the most common case. However, it is conceivable that the same monitor might be
connected in multiple ways (e.g. with both a DDC and USB connection), with multiple cards,
or even from separate computers. In this case it is the application's or even user's responsibility
to ensure that conflict does not occur.
- The following settings are now thread specific:
- whether setvcp verification is enabled (ddca_enable_verify(), ddca_is_verify_enabled())
- output redirection (ddca_set_fout(), etc.)
- output level (ddca_set_output_level(), ddca_get_output_level())
Presently, multi-threaded operation is best managed in the application.
The C++ Qt based GUI currently under development does the following:
- Calls ddca_get_display_info_list() to enumerate the displays
- Opens the display (i.e. creates a DDCA_Display_Handle)
- Maintains a queue of requests
- Calls the ddcutil API for each request, and updates the GUI accordingly
No changes.
| Unchanged |
Comments |
| ddca_ddcutil_version() |
|
| ddca_ddcutil_version_string() |
|
| ddca_build_options() |
|
Status Code Functions
No changes.
| Unchanged |
Comments |
| ddca_rc_name() |
|
| ddca_rc_desc() |
|
Detailed Error Reports
In some cases, detailed error information is appopriate, particularly when there
are multiple causes, each of which should be reported. The following functions
get and release detailed error reports for the most recent API call.
Currently implemented only for ddca_set_profile_related_values(), reports
each case of invalid data in the input and the line at which it occurred.
| New |
Comments |
| ddca_get_error_detail() |
Get detailed error information for most recent API call |
| ddca_free_error_detai() |
Free detailed error information |
Global Settings
| Unchanged |
Comments |
| ddca_max_max_tries() |
|
| ddca_get_max_tries() |
|
| ddca_set_max_tries() |
|
| Changed |
Comments |
| ddca_enable_verify() |
now thread-specific setting, returns prior value |
| ddca_is_verify_enabled() |
now thread-specific setting |
Output Redirection and Capture
Output redirection is now thread-specific.
| Changed Functions |
Comments |
| ddca_set_fout() |
now thread-specific |
| ddca_set_fout_to_default() |
now thread-specific |
| ddca_set_ferr() |
now thread-specific |
| ddca_set_ferr_to_default() |
now thread-specific |
Added convenience functions to capture output normally directed to the terminal.
Output capture is thread specific.
| New |
Comments |
| ddca_start_capture() |
Begin capturing output |
| ddca_end_capture() |
Terminates capture, returns the captured value |
For examples of output redirection, see sample program demo_redirection.c.
Message Control
Output level settings are now thread-specific.
| Changed |
Comments |
| ddca_get_output_level() |
now thread-specific |
| ddca_set_output_level() |
now thread-specific, returns old level |
| Unchanged |
Comments |
| ddca_output_level_name() |
|
Statistics and Diagnostics
Statistics and diagnostics control are global, not thread-specific.
| Unchanged |
Comments |
| ddca_reset_stats() |
|
| ddca_show_stats() |
|
| ddca_is_report_ddc_errors_enabled() |
|
| Changed |
Comments |
| ddca_enable_report_ddc_errors() |
returns old level |
| New |
Comments |
| ddca_enable_error_info() |
control display of internal exception reports |
Feature Lists
Struct DDCA_Feature_List specifies a set of VCP feature codes using a 256 bit array.
Functions and constants for operating on feature lists:
| New |
Comments |
| ddca_feature_list_add() |
add a VCP feature code to the list |
| ddca_feature_list_and() |
returns intersection of 2 lists |
| ddca_feature_list_and_not() |
returns the features in one list that are not in a second |
| ddca_feature_list_clear() |
clear all entries in the feature list |
| ddca_feature_list_contains() |
check if a VCP feature code is in the list |
| ddca_feature_list_count() |
number of features in list |
| ddca_feature_list_id_name() |
get symbolic name of feature list id |
| ddca_feature_list_or() |
returns union of 2 feature lists |
| ddca_feature_list_string() |
returns a string representation of a feature list |
| ddca_get_feature_list_by_dref() |
returns a feature list identifying the features in named feature set (e.g. COLOR) |
| DDCA_EMPTY_FEATURE_LIST |
an empty feature list |
For an example of using feature lists, see sample program demo_feature_list.c.
MCCS Version Identification
To date, the API has had two different ways to specify the Monitor Control Command Set (MCCS) version:
- DDCA_MCCS_Version_Spec, a pair of 8 bit unsigned integers.
- DDCA_MCCS_Version_Id, an enum of valid MCCS versions.
Going forward, the API will use DDCA_MCCS_Version_Spec. Existing functions using
DDCA_MCCS_Version_Id are retained, but are marked as deprecated and will be
removed in a future release. Once the deprecated functions are removed, there
will likely be some simplification of the remaining function names.
Symbolic constants DDCA_VSPEC_V10 etc. have been added for DDCA_MCCS_Version_Spec values.
| Deprecated |
Comments |
| DDCA_MCCS_Version_Id |
MCCS version enum |
| ddca_mccs_version_id_name() |
|
| ddca_mccs_version_id_desc() |
|
| ddca_get_mccs_version_id() |
Get MCCS version id for display handle |
| Unchanged |
Comments |
| ddca_get_mccs_version() |
takes DDCA_Display_Handle argument |
Background:
Each way to specify the MCCS version has its advantages. DDCA_MCCS_Version_Spec was chosen because
it is the form already used in the MCCS spec.
DDCA_MCCS_Version_Spec
- Feature code xDF (get MCCS version) returns a number pair
- The capabilities string specifies the MCCS version as a number pair
DDCA_MCCS_Version_Id
- There are only a handful of valid version numbers
- Simplifies version specification
- Simplifies version comparisons, which are complicated by the fact
that both Version 3.0 and Version 2.2 are independent successors to Version 2.1.
Detect Displays
- ddca_display_info_list2() replaces ddca_display_info_list(), allows for including displays that don't support DDC,
signature returns a status code, conforming to standard API pattern
- ddca_report_displays() replaces ddca_report_active_displays, added parm to allow for reporting invalid displays
- Struct DDCA_Display_Info now has a field for the MCCS version.
| Deprecated |
Comments |
| ddca_get_display_info_list() |
Use ddca_get_display_info_list2() |
| ddca_report_active_displays() |
Use ddca_report_displays() |
| Unchanged |
Comments |
| ddca_report_display_info() |
|
| ddca_report_display_info_list() |
|
| ddca_free_display_info_list() |
|
| New |
Comments |
| ddca_get_display_info_list2() |
Can include displays that don't support DDC |
| ddca_report_display_by_dref() |
Report display information using code in ddcutil detect |
| ddca_report_displays() |
Optionally include displays that don't support DDC |
Display Identifiers
No changes.
| Unchanged Functions |
Comments |
| ddca_create_dispno_display_identifier() |
|
| ddca_create_busno_display_identifier() |
|
| ddca_create_adlno_display_identifier() |
|
| ddca_create_mfg_model_sn_display_identifier() |
|
| ddca_create_edid_display_identifier() |
|
| ddca_create_usb_display_identifier() |
|
| ddca_create_usb_hiddev_display_identifier() |
|
| ddca_free_display_identifier() |
|
| ddca_did_repr() |
|
Display References
| Deprecated |
Comments |
| ddca_get_edid_by_dref() |
renamed, was ddca_get_edid_by_display_reference() |
| Unchanged |
Comments |
| ddca_create_display_ref() |
|
| ddca_free_display_ref() |
|
| ddca_dref_repr() |
|
| Changed |
Comments |
| ddca_dbgrpt_display_ref() |
renamed, was ddca_report_display_ref() |
| New |
Comments |
| ddca_report_display_by_dref() |
|
Display Handles
| Deprecated API Functions |
Comments |
| ddca_open_display() |
Use ddca_open_display2() |
| Unchanged |
Comments |
| ddca_close_display() |
|
| ddca_dh_repr() |
|
| New |
Comments |
| ddca_open_display2() |
allows for waiting if display locked by another thread |
| ddca_display_ref_from_handle() |
|
Capabilities String
| Unchanged |
Comments |
| ddca_get_capabilities_string() |
|
| ddca_parse_capabilities_string() |
|
| ddca_free_parsed_capabilities() |
|
| Changed |
Comments |
| ddca_report_parsed_capabilities() |
interprets feature and value codes |
| Added |
Comments |
| ddca_feature_list_from_capabilities() |
Create feature id bitifield from capabilities |
Struct DDCA_Version_Feature_Info and related functions are deprecated. Instead, the master
record for feature metadata is now DDCA_Feature_Metadata.
| Deprecated and Deleted |
Comments |
| DDCA_Version_Feature_Info |
use DDCA_Feature_Metadata |
| ddca_get_feature_info_by_vcp_version() |
Use ddca_get_feature_metadata() - in 0.8.7 |
| ddca_get_feature_info_by_display() |
Use ddca_get_feature_metadata() |
| ddca_free_feature_info() |
in 0.8.7? |
| ddca_get_simple_sl_value_table() |
Takes a DDCA_MCCS_Version_Id argument. |
| Unchanged |
Comments |
| ddca_get_feature_name() |
|
| Added Structs and Functions |
Comments |
| DDCA_Feature_Metadata |
replaces DDCA_Version_Feature_Info |
| ddca_get_feature_metadata_by_dref() |
|
| ddca_get_feature_metadata_by_dh() |
|
| ddca_free_feature_metadata_contents() |
|
| Additional new granular functions |
Comments |
| ddca_feature_name_by_dref() |
|
| ddca_get_simple_sl_value_table_by_dref() |
Gets table of valid values if flag DDCA_SIMPLE_NC is set in DDCA_Feature_Flags. |
Miscellaneous changes:
- Bitfield DDCA_Version_Feature_Flags now has bit DDCA_NC_COMPLEX, indicating a VCP code
(designated by MCCS as Non-Continuous) that uses certain values as an NC feature and uses the
remaining range for continyous adjustment. An example of such a feature is VCP code x62 (Audio Speaker Volume)
as defined in MCCS versions 3.0 and 2.2, where value x00 is defined as "Fixed (default level)", value xFF is "Mute",
and values x01..xFE provide a continuous range for volume adjustment.
NC Feature Value Lookup
(See Metadata section for discussion of getting lookup tables)
| Deprecated and Deleted Functions |
Comments |
| ddca_get_simple_nc_feature_value_name() |
Get feature metadata, then use ddca_get_simple_nc_feature_name_by_table() |
| ddca_get_simple_nc_feature_value_name_by_display() |
Get feature metadata, then use ddca_get_simple_nc_feature_name_by_table() |
| New |
Comments |
| ddca_get_simple_nc_feature_value_name_by_table() |
new |
Symbol Name Changes
Numerous symbols have been renamed for clarity and consistency.
General changes:
- The names of report functions that display internal data structures for debugging, as opposed to reports
designed to be shown to users, now begin with "ddca_dbgrpt_" instead of "ddca_report_".
- Enum values DDCA_V10 etc. are now DDCA_MCCS_V10 etc. (but note that the use of DDCA_MCCS_Version_Id is deprecated
in favor of DDCA_MCCS_Version_Spec)
- Names of parameters that specify the address at which a pointer is to be returned now generally end in "_loc".
Specific changes not listed elsewhere:
| Old Name |
New Name |
| DDCA_IO_DEVI2C |
DDCA_IO_I2C |
Naming patterns:
- Functions that always return the same value generally do not include "_get_" in their names,
e.g. ddca_ddcutil_version(), ddca_max_max_tries()
- In the case of "overloaded" functions, "_by_" is usually used to distinguish variants,
e.g. ddca_get_feature_metadata_by_vspec(), ddca_get_feature_metadata_by_dref(), get_feature_metadata_by_display()
- However, in the case where there the result depends on a single input value from which the result
is extracted, "_from_" is used,
e.g. ddca_mmk_from_dref(), ddca_mmk_from_dh()
Get and Set VCP Feature Values
DDCA_Any_Vcp_Value vs DDCA_Non_Table_Vcp_Value
The API provides functions for getting, setting, and otherwise processing VCP values in 3 forms,
using the type specific DDCA_Non_Table_Vcp_Value or DDCA_Table_Vcp_Value or the more
general DDCA_Any_Vcp_Value. The first form is simpler to use, and does not entail the
allocation of arbitrarily size buffers.
As a practical matter, while the MCCS spec defines Table type features, they have not been observed
on any monitors. Supporting Table type features in a UI adds complexity.
API users will probably want to use the simpler DDCA_Non_Table_Vcp_Value functions.
The following tables summarize the structs and API functions for getting and setting VCP feature values.
| Deprecated |
Comments |
| ddca_set_simple_nc_vcp_value() |
unchanged, but deprecated |
| ddca_set_continuous_vcp_value() |
unchanged, but deprecated |
| Changed |
Comments |
| DDCA_Non_Table_Vcp_Value |
renamed, was DDCA_Non_Table_Value |
| DDCA_Table_Vcp_Value |
renamed, was DDCA_Table_Value |
| ddca_get_non_table_vcp_value() |
renamed, was ddca_get_nontable_vcp_value() |
| ddca_get_any_vcp_value_using_explicit_type() |
renamed, was ddca_get_any_vcp_value(), parm type change |
| ddca_set_non_table_vcp_value() |
renamed, was ddca_set_raw_vcp_value() |
| ddca_get_table_vcp_value() |
parameter change |
| ddca_free_table_vcp_value() |
renamed from ddca_free_table_value_response() |
| New |
Comments |
| ddca_get_any_vcp_value_using_implicit_type() |
new function |
| ddca_set_table_vcp_value() |
new |
| ddca_set_any_vcp_value() |
new |
| ddca_free_any_vcp_value() |
new |
| dbgrpt_any_vcp_value() |
new |
Get or Set Multiple Values
| Unchanged |
Comments |
| ddca_get_profile_related_values() |
|
| Changed |
Comments |
| ddca_set_profile_related_values() |
add display handle parm |
if ddca_set_profile_related_values() returns DDCRC_BAD_DATA, ddca_get_error_detail()
returns a detailed error report.
Functions ddca_format_table_vcp_value(), ddca_format_non_table_vcp_value(), and ddca_format_any_vcp_value()
format a feature value, based on its feature code and MCCS version.
Function ddca_get_formatted_vcp_value() continues to exist, but is essentially a convenience function
that combines reading a VCP value with formatting.
| Unchanged |
Comments |
| ddca_get_formatted_vcp_value() |
unchanged |
| New |
Comments |
| ddca_format_non_table_vcp_value_by_dref() |
new |
| ddca_format_table_vcp_value_by_dref() |
new |
| ddca_format_any_vcp_value_by_dref() |
new |
Miscellaneous Changes
- ddca_enable_report_ddc_errors(), ddca_enable_verify(), ddca_set_output_level
now return the prior setting
Sample programs
Sample programs have been revised to reflect API changes and new sample programs added. See the main C API page.