1 /* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2019 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 typedef union { 33 #if defined(LWS_WITH_IPV6) 34 struct sockaddr_in6 sa6; 35 #endif 36 struct sockaddr_in sa4; 37 } lws_sockaddr46; 38 39 /** 40 * lws_canonical_hostname() - returns this host's hostname 41 * 42 * This is typically used by client code to fill in the host parameter 43 * when making a client connection. You can only call it after the context 44 * has been created. 45 * 46 * \param context: Websocket context 47 */ 48 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT 49 lws_canonical_hostname(struct lws_context *context); 50 51 /** 52 * lws_get_peer_addresses() - Get client address information 53 * \param wsi: Local struct lws associated with 54 * \param fd: Connection socket descriptor 55 * \param name: Buffer to take client address name 56 * \param name_len: Length of client address name buffer 57 * \param rip: Buffer to take client address IP dotted quad 58 * \param rip_len: Length of client address IP buffer 59 * 60 * This function fills in name and rip with the name and IP of 61 * the client connected with socket descriptor fd. Names may be 62 * truncated if there is not enough room. If either cannot be 63 * determined, they will be returned as valid zero-length strings. 64 */ 65 LWS_VISIBLE LWS_EXTERN void 66 lws_get_peer_addresses(struct lws *wsi, lws_sockfd_type fd, char *name, 67 int name_len, char *rip, int rip_len); 68 69 /** 70 * lws_get_peer_simple() - Get client address information without RDNS 71 * 72 * \param wsi: Local struct lws associated with 73 * \param name: Buffer to take client address name 74 * \param namelen: Length of client address name buffer 75 * 76 * This provides a 123.123.123.123 type IP address in name from the 77 * peer that has connected to wsi 78 */ 79 LWS_VISIBLE LWS_EXTERN const char * 80 lws_get_peer_simple(struct lws *wsi, char *name, size_t namelen); 81 82 LWS_VISIBLE LWS_EXTERN const char * 83 lws_get_peer_simple_fd(lws_sockfd_type fd, char *name, size_t namelen); 84 85 #define LWS_ITOSA_USABLE 0 86 #define LWS_ITOSA_NOT_EXIST -1 87 #define LWS_ITOSA_NOT_USABLE -2 88 #define LWS_ITOSA_BUSY -3 /* only returned by lws_socket_bind() on 89 EADDRINUSE */ 90 91 #if !defined(LWS_PLAT_FREERTOS) && !defined(LWS_PLAT_OPTEE) 92 /** 93 * lws_interface_to_sa() - Convert interface name or IP to sockaddr struct 94 * 95 * \param ipv6: Allow IPV6 addresses 96 * \param ifname: Interface name or IP 97 * \param addr: struct sockaddr_in * to be written 98 * \param addrlen: Length of addr 99 * 100 * This converts a textual network interface name to a sockaddr usable by 101 * other network functions. 102 * 103 * If the network interface doesn't exist, it will return LWS_ITOSA_NOT_EXIST. 104 * 105 * If the network interface is not usable, eg ethernet cable is removed, it 106 * may logically exist but not have any IP address. As such it will return 107 * LWS_ITOSA_NOT_USABLE. 108 * 109 * If the network interface exists and is usable, it will return 110 * LWS_ITOSA_USABLE. 111 */ 112 LWS_VISIBLE LWS_EXTERN int 113 lws_interface_to_sa(int ipv6, const char *ifname, struct sockaddr_in *addr, 114 size_t addrlen); 115 #endif 116 117 /** 118 * lws_sa46_compare_ads() - checks if two sa46 have the same address 119 * 120 * \param sa46a: first 121 * \param sa46b: second 122 * 123 * Returns 0 if the address family and address are the same, otherwise nonzero. 124 */ 125 LWS_VISIBLE LWS_EXTERN int 126 lws_sa46_compare_ads(const lws_sockaddr46 *sa46a, const lws_sockaddr46 *sa46b); 127 128 /* 129 * lws_parse_numeric_address() - converts numeric ipv4 or ipv6 to byte address 130 * 131 * \param ads: the numeric ipv4 or ipv6 address string 132 * \param result: result array 133 * \param max_len: max length of result array 134 * 135 * Converts a 1.2.3.4 or 2001:abcd:123:: or ::ffff:1.2.3.4 formatted numeric 136 * address into an array of network ordered byte address elements. 137 * 138 * Returns < 0 on error, else length of result set, either 4 or 16 for ipv4 / 139 * ipv6. 140 */ 141 LWS_VISIBLE LWS_EXTERN int 142 lws_parse_numeric_address(const char *ads, uint8_t *result, size_t max_len); 143 144 /* 145 * lws_sa46_parse_numeric_address() - converts numeric ipv4 or ipv6 to sa46 146 * 147 * \param ads: the numeric ipv4 or ipv6 address string 148 * \param sa46: pointer to sa46 to set 149 * 150 * Converts a 1.2.3.4 or 2001:abcd:123:: or ::ffff:1.2.3.4 formatted numeric 151 * address into an sa46, a union of sockaddr_in or sockaddr_in6 depending on 152 * what kind of address was found. sa46->sa4.sin_fmaily will be AF_INET if 153 * ipv4, or AF_INET6 if ipv6. 154 * 155 * Returns 0 if the sa46 was set, else < 0 on error. 156 */ 157 LWS_VISIBLE LWS_EXTERN int 158 lws_sa46_parse_numeric_address(const char *ads, lws_sockaddr46 *sa46); 159 160 /** 161 * lws_write_numeric_address() - convert network byte order ads to text 162 * 163 * \param ads: network byte order address array 164 * \param size: number of bytes valid in ads 165 * \param buf: result buffer to take text format 166 * \param len: max size of text buffer 167 * 168 * Converts an array of network-ordered byte address elements to a textual 169 * representation of the numeric address, like "1.2.3.4" or "::1". Return 0 170 * if OK else < 0. ipv6 only supported with LWS_IPV6=1 at cmake. 171 */ 172 LWS_VISIBLE LWS_EXTERN int 173 lws_write_numeric_address(const uint8_t *ads, int size, char *buf, size_t len); 174 175 /** 176 * lws_sa46_write_numeric_address() - convert sa46 ads to textual numeric ads 177 * 178 * \param sa46: the sa46 whose address to show 179 * \param buf: result buffer to take text format 180 * \param len: max size of text buffer 181 * 182 * Converts the ipv4 or ipv6 address in an lws_sockaddr46 to a textual 183 * representation of the numeric address, like "1.2.3.4" or "::1". Return 0 184 * if OK else < 0. ipv6 only supported with LWS_IPV6=1 at cmake. 185 */ 186 LWS_VISIBLE LWS_EXTERN int 187 lws_sa46_write_numeric_address(lws_sockaddr46 *sa46, char *buf, size_t len); 188 189 ///@} 190