mark deprecated functions as such

[bradh352]

Multiple functions have been deprecated over the years, annotate them with attribute deprecated.

When possible show a message about their replacements.

This is a continuation/completion of PR #706

Fix By: Cristian Rodríguez (@crrodriguez)

[eriklax]

What is the short to mid-term plan for the deprecation of various methods not considered the new API? Is it safe to ignore these warnings (CARES_NO_DEPRECATED) for the time being and migrate slowly.

While they are more powerful, it's a lot more verbose API and more error handling needs to be in the application.

Having used the old API, and looking at the source code of eg. ares_parse_mx_reply there seems to be a lot of error handling that need to be moved to the application to have the same logic. While I don't favor the old API per se, there is less moving parts.

Also, my application use ares_create_query, it should be replaced with ares_dns_record_create, however there is some logic that isn't in the ares_dns_record_create (since I need to construct everyhing myself) functions such as .onion checking (which is in ares_dns_record_create_query). Would it make sense to make ares_dns_record_create_query public?

[bradh352]

Those deprecated functions will remain available until there is an ABI break, which honestly will likely never happen. It's more to encourage integrators to move to the more modern functions. We may decide to make a helper like ares_dns_record_create_query or something similar public at some point once we're confident on the API we should be exposing. That said, checking for .onion is done at other places later so you don't need to do that manually. Using the new functions will be more efficient as it prevents additional parses of the same message and provides access to additional metadata not otherwise available.

…

On Sat, Mar 30, 2024, 3:04 PM Erik Lax ***@***.***> wrote: What is the short to mid-term plan for the deprecation of various methods not considered the new API? Is it safe to ignore these warnings (CARES_NO_DEPRECATED) for the time being and migrate slowly. While they are more powerful, it's a lot more verbose API and more error handling needs to be in the application. Having used the old API, and looking at the source code of eg. ares_parse_mx_reply there seems to be a lot of error handling that need to be moved to the application to have the same logic. While I don't favor the old API per se, there is less moving parts. Also, my application use ares_create_query, it should be replaced with ares_dns_record_create, however there is some logic that isn't in the ares_dns_record_create (since I need to construct everyhing myself) functions such as .onion checking (which is in ares_dns_record_create_query). Would it make sense to make ares_dns_record_create_query public? — Reply to this email directly, view it on GitHub <#732 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEWRNXBDKCKPBMGB27IWXCLY235BVAVCNFSM6AAAAABFJQ72GGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQ2DGNZYG4> . You are receiving this because you modified the open/close state.Message ID: ***@***.***>

[johnthacker]

ares_set_servers[_ports] was marked as deprecated in favor of ares_set_servers[_ports]_csv "due to inability to set all available server options," but AFAICT it's impossible to set a server's TCP and UDP ports to be different from each other with ares_set_servers_ports_csv. Is that correct? A rare use case, I suppose.

[bradh352]

I've never seen that be used, and its not possible to represent that via a system configuration on any system I'm aware of so it would be some odd application-specific thing I guess. Do you use this for some purpose? If its really needed we might be able to expand the syntax to allow it in csv format.

[johnthacker]

I am a Wireshark developer, and we allow people to specify a user configurable table of what DNS servers to use optionally for resolving packets instead of the system default. The table allows for each server specifying the TCP and UDP port separately.

I don't know that anyone actually needs two different ports, it was probably set up that way just to map into the struct used by c-ares.

We are looking into what we would need to do to remove the use of deprecated functions.

On a side note, the ares_queue_wait_empty() function added in 1.27 is useful, because when tshark is run in two-pass mode, we want to wait for all the asynchronous lookups in the queue to complete before printing results. (With two passes we can do asynchronous lookups on the first pass.)

[johnthacker]

Since we don't yet support entering a device for a link local DNS server, we will probably continue to use the deprecated ares_set_servers_ports() for now.