quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

ares_set_server_state_callback.3 (2388B)

      1 .\"
      2 .\" Copyright 2024 by the c-ares project and its contributors
      3 .\" SPDX-License-Identifier: MIT
      4 .\"
      5 .TH ARES_SET_SERVER_STATE_CALLBACK 3 "26 Apr 2024"
      6 .SH NAME
      7 ares_set_server_state_callback \- Function for setting a server state callback
      8 .SH SYNOPSIS
      9 .nf
     10 #include <ares.h>
     11 
     12 typedef void (*ares_server_state_callback)(const char *\fIserver_string\fP,
     13                                            ares_bool_t \fIsuccess\fP,
     14                                            int \fIflags\fP,
     15                                            void *\fIdata\fP);
     16 
     17 void ares_set_server_state_callback(ares_channel_t *\fIchannel\fP,
     18                                     ares_server_state_callback \fIcallback\fP,
     19                                     void *\fIuser_data\fP);
     20 .fi
     21 
     22 .SH DESCRIPTION
     23 The \fBares_set_server_state_callback(3)\fP function sets a callback function
     24 \fIcallback\fP in the given ares channel handle \fIchannel\fP that is invoked
     25 whenever a query on the channel completes. This includes both successful and
     26 unsuccessful queries (including hard errors and timeouts). The callback
     27 function is invoked with a number of parameters describing the query, as
     28 follows.
     29 
     30 The \fIserver_string\fP parameter indicates the DNS server that was used for
     31 the query, given as a string with the same format returned by
     32 \fBares_get_servers_csv(3)\fP.
     33 
     34 The \fIsuccess\fP parameter indicates whether the query succeeded or not. It is
     35 set to \fBARES_TRUE\fP on success and \fBARES_FALSE\fP on failure.
     36 
     37 The \fIflags\fP parameter is a bitmask of flags describing various aspects of
     38 the query (for example whether the query used UDP or TCP). These are described
     39 below.
     40 
     41 The \fIdata\fP parameter is a reference to the custom user data \fIuser_data\fP
     42 that was passed to \fBares_set_server_state_callback(3)\fP when setting the
     43 server state callback.
     44 
     45 The server state callback can be used by applications to monitor the state of
     46 the DNS servers used by an ares channel. For example, it can be used to track
     47 metrics about the numbers and types of queries sent to each server or to
     48 detect when a server is uncontactable or unhealthy.
     49 
     50 .SH FLAGS
     51 .TP 5
     52 .B ARES_SERV_STATE_UDP
     53 Indicates that the query was tried over UDP.
     54 .TP 5
     55 .B ARES_SERV_STATE_TCP
     56 Indicates that the query was tried over TCP.
     57 
     58 .SH AVAILABILITY
     59 This function was first introduced in c-ares version 1.29.0.
     60 
     61 .SH SEE ALSO
     62 .BR ares_get_servers_csv (3)