mirror of https://github.com/c-ares/c-ares.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
62 lines
2.3 KiB
62 lines
2.3 KiB
.\" |
|
.\" Copyright 2024 by the c-ares project and its contributors |
|
.\" SPDX-License-Identifier: MIT |
|
.\" |
|
.TH ARES_SET_SERVER_STATE_CALLBACK 3 "26 Apr 2024" |
|
.SH NAME |
|
ares_set_server_state_callback \- Function for setting a server state callback |
|
.SH SYNOPSIS |
|
.nf |
|
#include <ares.h> |
|
|
|
typedef void (*ares_server_state_callback)(const char *\fIserver_string\fP, |
|
ares_bool_t \fIsuccess\fP, |
|
int \fIflags\fP, |
|
void *\fIdata\fP); |
|
|
|
void ares_set_server_state_callback(ares_channel_t *\fIchannel\fP, |
|
ares_server_state_callback \fIcallback\fP, |
|
void *\fIuser_data\fP); |
|
.fi |
|
|
|
.SH DESCRIPTION |
|
The \fBares_set_server_state_callback(3)\fP function sets a callback function |
|
\fIcallback\fP in the given ares channel handle \fIchannel\fP that is invoked |
|
whenever a query on the channel completes. This includes both successful and |
|
unsuccessful queries (including hard errors and timeouts). The callback |
|
function is invoked with a number of parameters describing the query, as |
|
follows. |
|
|
|
The \fIserver_string\fP parameter indicates the DNS server that was used for |
|
the query, given as a string with the same format returned by |
|
\fBares_get_servers_csv(3)\fP. |
|
|
|
The \fIsuccess\fP parameter indicates whether the query succeeded or not. It is |
|
set to \fBARES_TRUE\fP on success and \fBARES_FALSE\fP on failure. |
|
|
|
The \fIflags\fP parameter is a bitmask of flags describing various aspects of |
|
the query (for example whether the query used UDP or TCP). These are described |
|
below. |
|
|
|
The \fIdata\fP parameter is a reference to the custom user data \fIuser_data\fP |
|
that was passed to \fBares_set_server_state_callback(3)\fP when setting the |
|
server state callback. |
|
|
|
The server state callback can be used by applications to monitor the state of |
|
the DNS servers used by an ares channel. For example, it can be used to track |
|
metrics about the numbers and types of queries sent to each server or to |
|
detect when a server is uncontactable or unhealthy. |
|
|
|
.SH FLAGS |
|
.TP 5 |
|
.B ARES_SERV_STATE_UDP |
|
Indicates that the query was tried over UDP. |
|
.TP 5 |
|
.B ARES_SERV_STATE_TCP |
|
Indicates that the query was tried over TCP. |
|
|
|
.SH AVAILABILITY |
|
This function was first introduced in c-ares version 1.29.0. |
|
|
|
.SH SEE ALSO |
|
.BR ares_get_servers_csv (3)
|
|
|