.\"
.\" 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)