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