lws-network-helper.h (8486B)
1/* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 */ 24 25/** \defgroup net Network related helper APIs 26 * ##Network related helper APIs 27 * 28 * These wrap miscellaneous useful network-related functions 29 */ 30///@{ 31 32#if defined(LWS_ESP_PLATFORM) 33#include <lwip/sockets.h> 34#endif 35 36/* cope with large amounts of route information */ 37typedef uint16_t lws_route_uidx_t; 38 39typedef struct lws_dns_score { 40 uint8_t precedence; 41 uint8_t label; 42} lws_dns_score_t; 43 44/* 45 * This represents an entry in the system routing table 46 */ 47 48typedef struct lws_route { 49 lws_dll2_t list; 50 51 lws_sockaddr46 src; 52 lws_sockaddr46 dest; 53 lws_sockaddr46 gateway; 54 55 struct lws_route *source; /* when used as lws_dns_sort_t */ 56 lws_dns_score_t score; /* when used as lws_dns_sort_t */ 57 58 int if_idx; 59 int priority; 60 int ifa_flags; /* if source_ads */ 61 62 lws_route_uidx_t uidx; /* unique index for this route */ 63 64 uint8_t proto; 65 uint8_t dest_len; 66 uint8_t src_len; 67 uint8_t scope; /* if source_ads */ 68 uint8_t af; /* if source_ads */ 69 70 uint8_t source_ads:1; 71} lws_route_t; 72 73/* 74 * We reuse the route object as the dns sort granule, so there's only one 75 * struct needs to know all the gnarly ipv6 details 76 */ 77 78typedef lws_route_t lws_dns_sort_t; 79 80/** 81 * lws_canonical_hostname() - returns this host's hostname 82 * 83 * This is typically used by client code to fill in the host parameter 84 * when making a client connection. You can only call it after the context 85 * has been created. 86 * 87 * \param context: Websocket context 88 */ 89LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT 90lws_canonical_hostname(struct lws_context *context); 91 92/** 93 * lws_get_peer_addresses() - Get client address information 94 * \param wsi: Local struct lws associated with 95 * \param fd: Connection socket descriptor 96 * \param name: Buffer to take client address name 97 * \param name_len: Length of client address name buffer 98 * \param rip: Buffer to take client address IP dotted quad 99 * \param rip_len: Length of client address IP buffer 100 * 101 * This function fills in name and rip with the name and IP of 102 * the client connected with socket descriptor fd. Names may be 103 * truncated if there is not enough room. If either cannot be 104 * determined, they will be returned as valid zero-length strings. 105 */ 106LWS_VISIBLE LWS_EXTERN void 107lws_get_peer_addresses(struct lws *wsi, lws_sockfd_type fd, char *name, 108 int name_len, char *rip, int rip_len); 109 110/** 111 * lws_get_peer_simple() - Get client address information without RDNS 112 * 113 * \param wsi: Local struct lws associated with 114 * \param name: Buffer to take client address name 115 * \param namelen: Length of client address name buffer 116 * 117 * This provides a 123.123.123.123 type IP address in name from the 118 * peer that has connected to wsi 119 */ 120LWS_VISIBLE LWS_EXTERN const char * 121lws_get_peer_simple(struct lws *wsi, char *name, size_t namelen); 122 123LWS_VISIBLE LWS_EXTERN const char * 124lws_get_peer_simple_fd(lws_sockfd_type fd, char *name, size_t namelen); 125 126#define LWS_ITOSA_USABLE 0 127#define LWS_ITOSA_NOT_EXIST -1 128#define LWS_ITOSA_NOT_USABLE -2 129#define LWS_ITOSA_BUSY -3 /* only returned by lws_socket_bind() on 130 EADDRINUSE */ 131 132#if !defined(LWS_PLAT_FREERTOS) && !defined(LWS_PLAT_OPTEE) 133/** 134 * lws_interface_to_sa() - Convert interface name or IP to sockaddr struct 135 * 136 * \param ipv6: Allow IPV6 addresses 137 * \param ifname: Interface name or IP 138 * \param addr: struct sockaddr_in * to be written 139 * \param addrlen: Length of addr 140 * 141 * This converts a textual network interface name to a sockaddr usable by 142 * other network functions. 143 * 144 * If the network interface doesn't exist, it will return LWS_ITOSA_NOT_EXIST. 145 * 146 * If the network interface is not usable, eg ethernet cable is removed, it 147 * may logically exist but not have any IP address. As such it will return 148 * LWS_ITOSA_NOT_USABLE. 149 * 150 * If the network interface exists and is usable, it will return 151 * LWS_ITOSA_USABLE. 152 */ 153LWS_VISIBLE LWS_EXTERN int 154lws_interface_to_sa(int ipv6, const char *ifname, struct sockaddr_in *addr, 155 size_t addrlen); 156#endif 157 158/** 159 * lws_sa46_compare_ads() - checks if two sa46 have the same address 160 * 161 * \param sa46a: first 162 * \param sa46b: second 163 * 164 * Returns 0 if the address family is INET or INET6 and the address is the same, 165 * or if the AF is the same but not INET or INET6, otherwise nonzero. 166 */ 167LWS_VISIBLE LWS_EXTERN int 168lws_sa46_compare_ads(const lws_sockaddr46 *sa46a, const lws_sockaddr46 *sa46b); 169 170/** 171 * lws_sa46_on_net() - checks if an sa46 is on the subnet represented by another 172 * 173 * \param sa46a: first 174 * \param sa46_net: network 175 * \param net_len: length of network non-mask 176 * 177 * Returns 0 if sa46a belongs on network sa46_net/net_len 178 * 179 * If there is an ipv4 / v6 mismatch between the ip and the net, the ipv4 180 * address is promoted to ::ffff:x.x.x.x before the comparison. 181 */ 182LWS_VISIBLE LWS_EXTERN int 183lws_sa46_on_net(const lws_sockaddr46 *sa46a, const lws_sockaddr46 *sa46_net, 184 int net_len); 185 186/* 187 * lws_parse_numeric_address() - converts numeric ipv4 or ipv6 to byte address 188 * 189 * \param ads: the numeric ipv4 or ipv6 address string 190 * \param result: result array 191 * \param max_len: max length of result array 192 * 193 * Converts a 1.2.3.4 or 2001:abcd:123:: or ::ffff:1.2.3.4 formatted numeric 194 * address into an array of network ordered byte address elements. 195 * 196 * Returns < 0 on error, else length of result set, either 4 or 16 for ipv4 / 197 * ipv6. 198 */ 199LWS_VISIBLE LWS_EXTERN int 200lws_parse_numeric_address(const char *ads, uint8_t *result, size_t max_len); 201 202/* 203 * lws_sa46_parse_numeric_address() - converts numeric ipv4 or ipv6 to sa46 204 * 205 * \param ads: the numeric ipv4 or ipv6 address string 206 * \param sa46: pointer to sa46 to set 207 * 208 * Converts a 1.2.3.4 or 2001:abcd:123:: or ::ffff:1.2.3.4 formatted numeric 209 * address into an sa46, a union of sockaddr_in or sockaddr_in6 depending on 210 * what kind of address was found. sa46->sa4.sin_fmaily will be AF_INET if 211 * ipv4, or AF_INET6 if ipv6. 212 * 213 * Returns 0 if the sa46 was set, else < 0 on error. 214 */ 215LWS_VISIBLE LWS_EXTERN int 216lws_sa46_parse_numeric_address(const char *ads, lws_sockaddr46 *sa46); 217 218/** 219 * lws_write_numeric_address() - convert network byte order ads to text 220 * 221 * \param ads: network byte order address array 222 * \param size: number of bytes valid in ads 223 * \param buf: result buffer to take text format 224 * \param len: max size of text buffer 225 * 226 * Converts an array of network-ordered byte address elements to a textual 227 * representation of the numeric address, like "1.2.3.4" or "::1". Returns the 228 * number of chars written into buf, else < 0. ipv6 only supported with 229 * LWS_IPV6=1 at cmake. 230 */ 231LWS_VISIBLE LWS_EXTERN int 232lws_write_numeric_address(const uint8_t *ads, int size, char *buf, size_t len); 233 234/** 235 * lws_sa46_write_numeric_address() - convert sa46 ads to textual numeric ads 236 * 237 * \param sa46: the sa46 whose address to show 238 * \param buf: result buffer to take text format 239 * \param len: max size of text buffer 240 * 241 * Converts the ipv4 or ipv6 address in an lws_sockaddr46 to a textual 242 * representation of the numeric address, like "1.2.3.4" or "::1". Returns the 243 * number of chars written into buf, else < 0. ipv6 only supported with 244 * LWS_IPV6=1 at cmake. 245 */ 246LWS_VISIBLE LWS_EXTERN int 247lws_sa46_write_numeric_address(lws_sockaddr46 *sa46, char *buf, size_t len); 248 249///@}