1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup Networking 19 * @{ 20 */ 21 22 /** 23 * @file multinetwork.h 24 */ 25 26 #ifndef ANDROID_MULTINETWORK_H 27 #define ANDROID_MULTINETWORK_H 28 29 #include <netdb.h> 30 #include <stdlib.h> 31 #include <sys/cdefs.h> 32 33 __BEGIN_DECLS 34 35 /** 36 * The corresponding C type for android.net.Network#getNetworkHandle() return 37 * values. The Java signed long value can be safely cast to a net_handle_t: 38 * 39 * [C] ((net_handle_t) java_long_network_handle) 40 * [C++] static_cast<net_handle_t>(java_long_network_handle) 41 * 42 * as appropriate. 43 */ 44 typedef uint64_t net_handle_t; 45 46 /** 47 * The value NETWORK_UNSPECIFIED indicates no specific network. 48 * 49 * For some functions (documented below), a previous binding may be cleared 50 * by an invocation with NETWORK_UNSPECIFIED. 51 * 52 * Depending on the context it may indicate an error. It is expressly 53 * not used to indicate some notion of the "current default network". 54 */ 55 #define NETWORK_UNSPECIFIED ((net_handle_t)0) 56 57 58 /** 59 * All functions below that return an int return 0 on success or -1 60 * on failure with an appropriate errno value set. 61 */ 62 63 /** 64 * Set the network to be used by the given socket file descriptor. 65 * 66 * To clear a previous socket binding, invoke with NETWORK_UNSPECIFIED. 67 * 68 * This is the equivalent of: [android.net.Network#bindSocket()](https://developer.android.com/reference/android/net/Network.html#bindSocket(java.net.Socket)) 69 * 70 * Available since API level 23. 71 */ 72 int android_setsocknetwork(net_handle_t network, int fd) __INTRODUCED_IN(23); 73 74 75 /** 76 * Binds the current process to |network|. All sockets created in the future 77 * (and not explicitly bound via android_setsocknetwork()) will be bound to 78 * |network|. All host name resolutions will be limited to |network| as well. 79 * Note that if the network identified by |network| ever disconnects, all 80 * sockets created in this way will cease to work and all host name 81 * resolutions will fail. This is by design so an application doesn't 82 * accidentally use sockets it thinks are still bound to a particular network. 83 * 84 * To clear a previous process binding, invoke with NETWORK_UNSPECIFIED. 85 * 86 * This is the equivalent of: [android.net.ConnectivityManager#bindProcessToNetwork()](https://developer.android.com/reference/android/net/ConnectivityManager.html#bindProcessToNetwork(android.net.Network)) 87 * 88 * Available since API level 23. 89 */ 90 int android_setprocnetwork(net_handle_t network) __INTRODUCED_IN(23); 91 92 93 /** 94 * Gets the |network| bound to the current process, as per android_setprocnetwork. 95 * 96 * This is the equivalent of: [android.net.ConnectivityManager#getBoundNetworkForProcess()](https://developer.android.com/reference/android/net/ConnectivityManager.html#getBoundNetworkForProcess(android.net.Network)) 97 * Returns 0 on success, or -1 setting errno to EINVAL if a null pointer is 98 * passed in. 99 * 100 * 101 * Available since API level 31. 102 */ 103 int android_getprocnetwork(net_handle_t *network) __INTRODUCED_IN(31); 104 105 /** 106 * Binds domain name resolutions performed by this process to |network|. 107 * android_setprocnetwork takes precedence over this setting. 108 * 109 * To clear a previous process binding, invoke with NETWORK_UNSPECIFIED. 110 * On success 0 is returned. On error -1 is returned, and errno is set. 111 * 112 * Available since API level 31. 113 */ 114 int android_setprocdns(net_handle_t network) __INTRODUCED_IN(31); 115 116 /** 117 * Gets the |network| to which domain name resolutions are bound on the 118 * current process. 119 * 120 * Returns 0 on success, or -1 setting errno to EINVAL if a null pointer is 121 * passed in. 122 * 123 * Available since API level 31. 124 */ 125 int android_getprocdns(net_handle_t *network) __INTRODUCED_IN(31); 126 127 128 /** 129 * Perform hostname resolution via the DNS servers associated with |network|. 130 * 131 * All arguments (apart from |network|) are used identically as those passed 132 * to getaddrinfo(3). Return and error values are identical to those of 133 * getaddrinfo(3), and in particular gai_strerror(3) can be used as expected. 134 * Similar to getaddrinfo(3): 135 * - |hints| may be NULL (in which case man page documented defaults apply) 136 * - either |node| or |service| may be NULL, but not both 137 * - |res| must not be NULL 138 * 139 * This is the equivalent of: [android.net.Network#getAllByName()](https://developer.android.com/reference/android/net/Network.html#getAllByName(java.lang.String)) 140 * 141 * Available since API level 23. 142 */ 143 int android_getaddrinfofornetwork(net_handle_t network, 144 const char *node, const char *service, 145 const struct addrinfo *hints, struct addrinfo **res) __INTRODUCED_IN(23); 146 147 /** 148 * Possible values of the flags argument to android_res_nsend and android_res_nquery. 149 * Values are ORed together. 150 */ 151 enum ResNsendFlags : uint32_t { 152 /** 153 * Send a single request to a single resolver and fail on timeout or network errors 154 */ 155 ANDROID_RESOLV_NO_RETRY = 1 << 0, 156 157 /** 158 * Don't lookup this request in the cache, and don't cache the result of the lookup. 159 * This flag implies {@link #ANDROID_RESOLV_NO_CACHE_LOOKUP}. 160 */ 161 ANDROID_RESOLV_NO_CACHE_STORE = 1 << 1, 162 163 /** 164 * Don't lookup the request in cache. 165 */ 166 ANDROID_RESOLV_NO_CACHE_LOOKUP = 1 << 2, 167 }; 168 169 /** 170 * Look up the {|ns_class|, |ns_type|} Resource Record (RR) associated 171 * with Domain Name |dname| on the given |network|. 172 * The typical value for |ns_class| is ns_c_in, while |type| can be any 173 * record type (for instance, ns_t_aaaa or ns_t_txt). 174 * |flags| is a additional config to control actual querying behavior, see 175 * ResNsendFlags for detail. 176 * 177 * Returns a file descriptor to watch for read events, or a negative 178 * POSIX error code (see errno.h) if an immediate error occurs. 179 * 180 * Available since API level 29. 181 */ 182 int android_res_nquery(net_handle_t network, 183 const char *dname, int ns_class, int ns_type, uint32_t flags) __INTRODUCED_IN(29); 184 185 /** 186 * Issue the query |msg| on the given |network|. 187 * |flags| is a additional config to control actual querying behavior, see 188 * ResNsendFlags for detail. 189 * 190 * Returns a file descriptor to watch for read events, or a negative 191 * POSIX error code (see errno.h) if an immediate error occurs. 192 * 193 * Available since API level 29. 194 */ 195 int android_res_nsend(net_handle_t network, 196 const uint8_t *msg, size_t msglen, uint32_t flags) __INTRODUCED_IN(29); 197 198 /** 199 * Read a result for the query associated with the |fd| descriptor. 200 * Closes |fd| before returning. 201 * 202 * Available since 29. 203 * 204 * Returns: 205 * < 0: negative POSIX error code (see errno.h for possible values). |rcode| is not set. 206 * >= 0: length of |answer|. |rcode| is the resolver return code (e.g., ns_r_nxdomain) 207 */ 208 int android_res_nresult(int fd, 209 int *rcode, uint8_t *answer, size_t anslen) __INTRODUCED_IN(29); 210 211 /** 212 * Attempts to cancel the in-progress query associated with the |nsend_fd| 213 * descriptor. 214 * 215 * Available since API level 29. 216 */ 217 void android_res_cancel(int nsend_fd) __INTRODUCED_IN(29); 218 219 /* 220 * Set the socket tag and owning UID for traffic statistics on the specified 221 * socket. 222 * 223 * Subsequent calls always replace any existing parameters. The socket tag and 224 * uid (if set) are kept when the socket is sent to another process using binder 225 * IPCs or other mechanisms such as UNIX socket fd passing. Any app can accept 226 * blame for future traffic performed on a socket originally created by another 227 * app by calling this method with its own UID (or calling 228 * android_tag_socket(int sockfd, int tag)). However, only apps holding the 229 * android.Manifest.permission#UPDATE_DEVICE_STATS permission may assign blame 230 * to another UIDs. If unset (default) the socket tag is 0, and the uid is the 231 * socket creator's uid. 232 * 233 * Returns 0 on success, or a negative POSIX error code (see errno.h) on 234 * failure. 235 * 236 * Available since API level 33. 237 */ 238 int android_tag_socket_with_uid(int sockfd, uint32_t tag, uid_t uid) __INTRODUCED_IN(33); 239 240 /* 241 * Set the socket tag for traffic statistics on the specified socket. 242 * 243 * This function tags the socket with the caller's UID (accepting blame for 244 * future traffic performed on this socket) even if the socket was originally 245 * opened by another UID or was previously tagged by another UID. Subsequent 246 * calls always replace any existing parameters. The socket tag is kept when the 247 * socket is sent to another process using binder IPCs or other mechanisms such 248 * as UNIX socket fd passing. The tag is a value defined by the caller and used 249 * together with uid for data traffic accounting, so that the function callers 250 * can account different types of data usage for a uid. 251 * 252 * Returns 0 on success, or a negative POSIX error code (see errno.h) on 253 * failure. 254 * 255 * Some possible error codes: 256 * -EBADF Bad socketfd. 257 * -EPERM No permission. 258 * -EAFNOSUPPORT Socket family is neither AF_INET nor AF_INET6. 259 * -EPROTONOSUPPORT Socket protocol is neither IPPROTO_UDP nor IPPROTO_TCP. 260 * -EMFILE Too many stats entries. 261 * There are still other error codes that may provided by -errno of 262 * [getsockopt()](https://man7.org/linux/man-pages/man2/getsockopt.2.html) or by 263 * BPF maps read/write sys calls, which are set appropriately. 264 * 265 * Available since API level 33. 266 */ 267 int android_tag_socket(int sockfd, uint32_t tag) __INTRODUCED_IN(33); 268 269 /* 270 * Untag a network socket. 271 * 272 * Future traffic on this socket will no longer be associated with any 273 * previously configured tag and uid. If the socket was created by another UID 274 * or was previously tagged by another UID, calling this function will clear the 275 * statistics parameters, and thus the UID blamed for traffic on the socket will 276 * be the UID that originally created the socket, even if the socket was 277 * subsequently tagged by a different UID. 278 * 279 * Returns 0 on success, or a negative POSIX error code (see errno.h) on 280 * failure. 281 * 282 * One of possible error code: 283 * -EBADF Bad socketfd. 284 * Other error codes are either provided by -errno of 285 * [getsockopt()](https://man7.org/linux/man-pages/man2/getsockopt.2.html) or by 286 * BPF map element deletion sys call, which are set appropriately. 287 * 288 * Available since API level 33. 289 */ 290 int android_untag_socket(int sockfd) __INTRODUCED_IN(33); 291 292 __END_DECLS 293 294 #endif // ANDROID_MULTINETWORK_H 295 296 /** @} */ 297