NAME¶

ares_set_socket_functions, ares_set_socket_functions_ex - Set socket io callbacks

SYNOPSIS¶

#include <ares.h>
typedef enum {


  ARES_SOCKFUNC_FLAG_NONBLOCKING = 1 << 0
} ares_sockfunc_flags_t;
typedef enum {


  ARES_SOCKET_OPT_SENDBUF_SIZE,


  ARES_SOCKET_OPT_RECVBUF_SIZE,


  ARES_SOCKET_OPT_BIND_DEVICE,


  ARES_SOCKET_OPT_TCP_FASTOPEN
} ares_socket_opt_t;
typedef enum {


  ARES_SOCKET_CONN_TCP_FASTOPEN = 1 << 0
} ares_socket_connect_flags_t;
typedef enum {


  ARES_SOCKET_BIND_TCP = 1 << 0,


  ARES_SOCKET_BIND_CLIENT = 1 << 1
} ares_socket_bind_flags_t;
struct ares_socket_functions_ex {


  unsigned int version; /* ABI Version: must be "1" */


  unsigned int flags;


  ares_socket_t (*asocket)(int domain, int type, int protocol, void *user_data);


  int (*aclose)(ares_socket_t sock, void *user_data);


  int (*asetsockopt)(ares_socket_t sock, ares_socket_opt_t opt, const void *val,


                     ares_socklen_t val_size, void *user_data);


  int (*aconnect)(ares_socket_t sock, const struct sockaddr *address,


                  ares_socklen_t address_len, unsigned int flags,


                  void *user_data);


  ares_ssize_t (*arecvfrom)(ares_socket_t sock, void *buffer, size_t length,


                            int flags, struct sockaddr *address,


                            ares_socklen_t *address_len, void *user_data);


  ares_ssize_t (*asendto)(ares_socket_t sock, const void *buffer, size_t length,


                          int flags, const struct sockaddr *address,


                          ares_socklen_t address_len, void *user_data);


  int (*agetsockname)(ares_socket_t sock, struct sockaddr *address,


                      ares_socklen_t *address_len, void *user_data);


  int (*abind)(ares_socket_t sock, unsigned int flags,


               const struct sockaddr *address, socklen_t address_len,


               void *user_data);


  unsigned int (*aif_nametoindex)(const char *ifname, void *user_data);


  const char *(*aif_indextoname)(unsigned int ifindex, char *ifname_buf,


                                 size_t ifname_buf_len, void *user_data);
};
ares_status_t ares_set_socket_functions_ex(ares_channel_t *channel,


  const struct ares_socket_functions_ex *funcs, void *user_data);
struct ares_socket_functions {


    ares_socket_t (*asocket)(int, int, int, void *);


    int (*aclose)(ares_socket_t, void *);


    int (*aconnect)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *);


    ares_ssize_t (*arecvfrom)(ares_socket_t, void *, size_t, int,


                              struct sockaddr *, ares_socklen_t *, void *);


    ares_ssize_t (*asendv)(ares_socket_t, const struct iovec *, int, void *);
};
void ares_set_socket_functions(ares_channel_t *channel,


                               const struct ares_socket_functions * functions,


                               void *user_data);

DESCRIPTION¶

ares_set_socket_functions_ex(3) sets a set of callback functions in the given ares channel handle. Cannot be used when ARES_OPT_EVENT_THREAD is passed to ares_init_options(3). This function replaces the now deprecated ares_set_socket_functions(3) call.

These callback functions will be invoked to create/destroy socket objects and perform io, instead of the normal system calls. A client application can override normal network operation fully through this functionality, and provide its own transport layer.

Some callbacks may be optional and are documented as such below, but failing to implement such callbacks will disable certain features within c-ares. It is strongly recommended to implement all callbacks.

All callback functions are expected to operate like their system equivalents, and to set errno(2) or WSASetLastError(2) to an appropriate error code on failure. It is strongly recommended that io callbacks are implemented to be asynchronous and indicated as such in the flags member. The io callbacks can return error codes of EAGAIN, EWOULDBLOCK, or WSAEWOULDBLOCK when they would otherwise block.

The user_data value is provided to each callback function invocation to serve as context.

The ares_set_socket_functions_ex(3) must provide the following structure members and callbacks (which are different from the ares_set_socket_functions(3) members and callbacks):

ares_sockfunc_flags_t values:

ares_socket_opt_t values:

ares_socket_connect_flags_t values:

ares_socket_bind_flags_t values:

ares_set_socket_functions(3) sets a set of callback functions in the given ares channel handle. Cannot be used when ARES_OPT_EVENT_THREAD is passed to ares_init_options(3). This function is deprecated as of c-ares 1.34.0 in favor of ares_set_socket_functions_ex(3).

ares_set_socket_functions(3) allows you to choose to only implement some of the socket functions, and provide NULL to any others and c-ares will use its built-in system functions in that case.

All callback functions are expected to operate like their system equivalents, and to set errno(2) or WSASetLastError(2) to an appropriate error code on failure. It is strongly recommended all io functions behave asynchronously and return error codes of EAGAIN, EWOULDBLOCK, or WSAEWOULDBLOCK when they would otherwise block.

The user_data value is provided to each callback function invocation to serve as context.

The ares_set_socket_functions(3) must provide the following callbacks (which are different from the ares_set_socket_functions_ex(3) callbacks):

The ares_set_socket_functions(3) struct provided is not copied but directly referenced, and must thus remain valid through out the channels and any created socket's lifetime. However, the ares_set_socket_functions_ex(3) struct is duplicated and does not need to survive past the call to the function.

AVAILABILITY¶

ares_socket_functions added in c-ares 1.13.0, ares_socket_functions_ex added in c-ares 1.34.0

SEE ALSO¶

ares_init_options(3), socket(2), close(2), connect(2), recvfrom(2), sendto(2), bind(2), getsockname(2), setsockopt(2), writev(2)