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 #if __ANDROID_API__ >= 23 64 65 /** 66 * Set the network to be used by the given socket file descriptor. 67 * 68 * To clear a previous socket binding, invoke with NETWORK_UNSPECIFIED. 69 * 70 * This is the equivalent of: [android.net.Network#bindSocket()](https://developer.android.com/reference/android/net/Network.html#bindSocket(java.net.Socket)) 71 * 72 * Available since API level 23. 73 */ 74 int android_setsocknetwork(net_handle_t network, int fd) __INTRODUCED_IN(23); 75 76 77 /** 78 * Binds the current process to |network|. All sockets created in the future 79 * (and not explicitly bound via android_setsocknetwork()) will be bound to 80 * |network|. All host name resolutions will be limited to |network| as well. 81 * Note that if the network identified by |network| ever disconnects, all 82 * sockets created in this way will cease to work and all host name 83 * resolutions will fail. This is by design so an application doesn't 84 * accidentally use sockets it thinks are still bound to a particular network. 85 * 86 * To clear a previous process binding, invoke with NETWORK_UNSPECIFIED. 87 * 88 * This is the equivalent of: [android.net.ConnectivityManager#setProcessDefaultNetwork()](https://developer.android.com/reference/android/net/ConnectivityManager.html#setProcessDefaultNetwork(android.net.Network)) 89 * 90 * Available since API level 23. 91 */ 92 int android_setprocnetwork(net_handle_t network) __INTRODUCED_IN(23); 93 94 95 /** 96 * Perform hostname resolution via the DNS servers associated with |network|. 97 * 98 * All arguments (apart from |network|) are used identically as those passed 99 * to getaddrinfo(3). Return and error values are identical to those of 100 * getaddrinfo(3), and in particular gai_strerror(3) can be used as expected. 101 * Similar to getaddrinfo(3): 102 * - |hints| may be NULL (in which case man page documented defaults apply) 103 * - either |node| or |service| may be NULL, but not both 104 * - |res| must not be NULL 105 * 106 * This is the equivalent of: [android.net.Network#getAllByName()](https://developer.android.com/reference/android/net/Network.html#getAllByName(java.lang.String)) 107 * 108 * Available since API level 23. 109 */ 110 int android_getaddrinfofornetwork(net_handle_t network, 111 const char *node, const char *service, 112 const struct addrinfo *hints, struct addrinfo **res) __INTRODUCED_IN(23); 113 114 #endif /* __ANDROID_API__ >= 23 */ 115 116 #if __ANDROID_API__ >= 29 117 118 /** 119 * Possible values of the flags argument to android_res_nsend and android_res_nquery. 120 * Values are ORed together. 121 */ 122 enum ResNsendFlags : uint32_t { 123 /** 124 * Send a single request to a single resolver and fail on timeout or network errors 125 */ 126 ANDROID_RESOLV_NO_RETRY = 1 << 0, 127 128 /** 129 * Don't lookup this request in the cache, and don't cache the result of the lookup. 130 * This flag implies {@link #ANDROID_RESOLV_NO_CACHE_LOOKUP}. 131 */ 132 ANDROID_RESOLV_NO_CACHE_STORE = 1 << 1, 133 134 /** 135 * Don't lookup the request in cache. 136 */ 137 ANDROID_RESOLV_NO_CACHE_LOOKUP = 1 << 2, 138 }; 139 140 /** 141 * Look up the {|ns_class|, |ns_type|} Resource Record (RR) associated 142 * with Domain Name |dname| on the given |network|. 143 * The typical value for |ns_class| is ns_c_in, while |type| can be any 144 * record type (for instance, ns_t_aaaa or ns_t_txt). 145 * |flags| is a additional config to control actual querying behavior, see 146 * ResNsendFlags for detail. 147 * 148 * Returns a file descriptor to watch for read events, or a negative 149 * POSIX error code (see errno.h) if an immediate error occurs. 150 * 151 * Available since API level 29. 152 */ 153 int android_res_nquery(net_handle_t network, 154 const char *dname, int ns_class, int ns_type, uint32_t flags) __INTRODUCED_IN(29); 155 156 /** 157 * Issue the query |msg| on the given |network|. 158 * |flags| is a additional config to control actual querying behavior, see 159 * ResNsendFlags for detail. 160 * 161 * Returns a file descriptor to watch for read events, or a negative 162 * POSIX error code (see errno.h) if an immediate error occurs. 163 * 164 * Available since API level 29. 165 */ 166 int android_res_nsend(net_handle_t network, 167 const uint8_t *msg, size_t msglen, uint32_t flags) __INTRODUCED_IN(29); 168 169 /** 170 * Read a result for the query associated with the |fd| descriptor. 171 * Closes |fd| before returning. 172 * 173 * Available since 29. 174 * 175 * Returns: 176 * < 0: negative POSIX error code (see errno.h for possible values). |rcode| is not set. 177 * >= 0: length of |answer|. |rcode| is the resolver return code (e.g., ns_r_nxdomain) 178 */ 179 int android_res_nresult(int fd, 180 int *rcode, uint8_t *answer, size_t anslen) __INTRODUCED_IN(29); 181 182 /** 183 * Attempts to cancel the in-progress query associated with the |nsend_fd| 184 * descriptor. 185 * 186 * Available since API level 29. 187 */ 188 void android_res_cancel(int nsend_fd) __INTRODUCED_IN(29); 189 190 #endif /* __ANDROID_API__ >= 29 */ 191 192 __END_DECLS 193 194 #endif // ANDROID_MULTINETWORK_H 195 196 /** @} */ 197