NCBI C++ ToolKit
ncbi_ipv6.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_IPV6__H
2 #define CONNECT___NCBI_IPV6__H
3 
4 /* $Id: ncbi_ipv6.h 94296 2021-07-18 15:04:54Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Anton Lavrentiev
30  *
31  * File Description:
32  * @file ncbi_ipv6.h
33  * IPv6 addressing support
34  *
35  */
36 
37 #include <connect/connect_export.h>
38 #include <stddef.h>
39 
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif /*__cplusplus*/
44 
45 
46 typedef struct {
47  unsigned char octet[16]; /* assume no alignment */
49 
50 
51 /** Return non-zero if the address is empty (either as IPv6 or IPv4); return
52  * zero otherwise.
53  * @sa
54  * NcbiIsIPv4
55  */
57 int/*bool*/ NcbiIsEmptyIPv6(const TNCBI_IPv6Addr* addr);
58 
59 
60 /** Return non-zero(true) if the address is a true IPv4 address (a mapped IPv4
61  * address); return zero(false) otherwise.
62  * @sa
63  * NcbiIsIPv4Ex, NcbiIPv4ToIPv6, NcbiIPv6ToIPv4
64  */
66 int/*bool*/ NcbiIsIPv4 (const TNCBI_IPv6Addr* addr);
67 
68 
69 /** Return non-zero(true) if the address is either a mapped IPv4 address or
70  * (optionally) an IPv4-compatible IPv6 address; return zero(false) otherwise.
71  * @param compat
72  * non-zero causes IPv4-compatible IPv6 addresses to pass the test
73  * @note
74  * NcbiIsIPv4Ex(, 0) is equivalent to NcbiIsIPv4()
75  * @sa
76  * NcbiIsIPv4, NcbiIPv4ToIPv6, NcbiIPv6ToIPv4
77  */
79 int/*bool*/ NcbiIsIPv4Ex (const TNCBI_IPv6Addr* addr, int/*bool*/ compat);
80 
81 
82 /** Extract and return a network byte order IPv4 embedded address from an IPv6
83  * address, using the specified prefix length (RFC6052). Return INADDR_NONE
84  * (-1 = 255.255.255.255) when the specified prefix length is not valid. A
85  * special case (and the most anticipated common use-case) is to use prefix
86  * length 0, which checks that the passed IPv6 address is actually a mapped or
87  * compatible IPv4 address, then extracts it using the prefix length of 96.
88  * Return 0 if the extraction cannot be made (not an IPv4 mapped/compatible
89  * address).
90  * @sa
91  * NcbiIsIPv4, NcbiIPv4ToIPv6
92  */
94 unsigned int NcbiIPv6ToIPv4(const TNCBI_IPv6Addr* addr, size_t pfxlen);
95 
96 
97 /** Embed a passed network byte order IPv4 address into an IPv6 address using
98  * the specified prefix length (RFC6052). Return zero when the specified
99  * prefix length is not valid, non-zero otherwise. A special case (and the
100  * most anticipated common use-case) is to use prefix length 0, which first
101  * clears the passed IPv6 address, then embeds the IPv4 address as a mapped
102  * address using the prefix length of 96.
103  * @sa
104  * NcbiIsIPv4, NcbiIPv6ToIPv4
105  */
107 int/*bool*/ NcbiIPv4ToIPv6(TNCBI_IPv6Addr* addr,
108  unsigned int ipv4, size_t pfxlen);
109 
110 
111 /** Convert into a network byte order IPv4 address, the first "len" (or
112  * "strlen(str)" if "len" is 0) bytes of "str" from a full-quad decimal
113  * notation. Return a non-zero string pointer to the first non-converted
114  * character (which is neither a digit nor a dot); return 0 if conversion
115  * failed and no IPv4 address had been found.
116  * @note Unlike SOCK_gethostbyname[Ex], this call can handle correctly both
117  * "0.0.0.0" and "255.255.255.255".
118  * @sa
119  * NcbiIPToAddr, NcbiIPv4ToIPv6, NcbiStringToAddr,
120  * SOCK_StringToHostPort, SOCK_gethostbyname[Ex]
121  */
123 const char* NcbiStringToIPv4(unsigned int* addr,
124  const char* str, size_t len);
125 
126 
127 /** Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is
128  * 0) bytes of "str" from a hexadecimal colon-separated notation (including
129  * full-quad trailing IPv4). Return a non-zero string pointer to the first
130  * non-converted character (which is neither a hex-digit, nor a colon, nor a
131  * dot); return 0 if conversion failed and no IPv6 address had been found.
132  * @sa
133  * NcbiIPToAddr, NcbiStringToAddr
134  */
136 const char* NcbiStringToIPv6(TNCBI_IPv6Addr* addr,
137  const char* str, size_t len);
138 
139 
140 /** Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is
141  * 0) bytes of "str" from either a full-quad decimal IPv4 or a hexadecimal
142  * colon-separated IPv6. Return a non-zero string pointer to the first
143  * non-converted character (which is neither a [hex-]digit, nor a colon, nor a
144  * dot); return 0 if no conversion can be made.
145  * @sa
146  * NcbiStringToIPv4, NcbiStringToIPv6, NcbiStingToAddr, NcbiAddrToString
147  */
149 const char* NcbiIPToAddr(TNCBI_IPv6Addr* addr,
150  const char* str, size_t len);
151 
152 
153 /** Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is
154  * 0) bytes of "str", which can be either an .in-addr.arpa- or an
155  * .in6.arpa-domain names. Return a non-zero string pointer to the first
156  * non-converted character; return 0 if no conversion can be made.
157  * @sa
158  * NcbiAddrToDNS, NcbiStringToAddr
159  */
161 const char* NcbiDNSIPToAddr(TNCBI_IPv6Addr* addr,
162  const char* str, size_t len);
163 
164 
165 /** Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is
166  * 0) bytes of "str", which can be either of a full-quad decimal IPv4, a
167  * hexadecimal colon-separated IPv6, an .in-addr.arpa- or an .in6.arpa-domain
168  * names. Return a non-zero string pointer to the first non-converted
169  * character (which is neither a [hex-]digit, nor a colon, nor a dot); return
170  * 0 if no conversion can be made.
171  * @sa
172  * NcbiAddrToString, NcbiAddrToDNS
173  */
175 const char* NcbiStringToAddr(TNCBI_IPv6Addr* addr,
176  const char* str, size_t len);
177 
178 
179 /** Convert a network byte order IPv4 into a full-quad text form and store the
180  * result in the "buf" of size "bufsize". Return non-zero string address
181  * past the stored result, or 0 when the conversion failed for buffer being
182  * too small.
183  * In either case, if "buf" is non-NULL and "bufsize" is at least one, "buf"
184  * gets '\0'-terminated: in case of an error (NULL return) this results in
185  * an empty string at "buf", and in case of a non-NULL return value the
186  * returned pointer points to the terminating '\0' byte.
187  * @sa
188  * NcbiStringToIPv4, SOCK_ntoa, SOCK_HostPortToString
189  */
191 char* NcbiIPv4ToString(char* buf, size_t bufsize,
192  unsigned int addr);
193 
194 
195 /** Convert an IPv6 address into a hex colon-separated text form and store the
196  * result in the "buf" of size "bufsize". Return non-zero string address
197  * past the stored result, or 0 when the conversion failed for buffer being
198  * too small.
199  * In either case, if "buf" is non-NULL and "bufsize" is at least one, "buf"
200  * gets '\0'-terminated: in case of an error (NULL return) this results in
201  * an empty string at "buf", and in case of a non-NULL return value the
202  * returned pointer points to the terminating '\0' byte.
203  * @sa
204  * NcbiStringToIPv6, NcbiStringToAddr, NcbiAddrToString
205  */
207 char* NcbiIPv6ToString(char* buf, size_t bufsize,
208  const TNCBI_IPv6Addr* addr);
209 
210 
211 /** Convert an IPv6 address into either a full-quad text IPv4 (for IPv4-mapped
212  * IPv6 addresses) or a hex colon-separated text form (for all other), and
213  * store the result in the "buf" of size "bufsize". Return non-zero string
214  * address past the stored result, or 0 when the conversion failed for buffer
215  * being too small.
216  * In either case, if "buf" is non-NULL and "bufsize" is at least one, "buf"
217  * gets '\0'-terminated: in case of an error (NULL return) this results in
218  * an empty string at "buf", and in case of a non-NULL return value the
219  * returned pointer points to the terminating '\0' byte.
220  * @sa
221  * NcbiStringToAddr, NcbiAddrToDNS, SOCK_ntoa, SOCK_HostPortToString
222  */
224 char* NcbiAddrToString(char* buf, size_t bufsize,
225  const TNCBI_IPv6Addr* addr);
226 
227 
228 /** Convert an IPv6 address into either .in-addr.arpa domain (for IPv4-mapped
229  * IPv6 addresses) or .ip6.arpa domain (for all other), and store the result
230  * in the "buf" of size "bufsize". Return non-zero string address past the
231  * stored result, or 0 when the conversion failed for buffer being too small.
232  * In either case, if "buf" is non-NULL and "bufsize" is at least one, "buf"
233  * gets '\0'-terminated: in case of an error (NULL return) this results in
234  * an empty string at "buf", and in case of a non-NULL return value the
235  * returned pointer points to the terminating '\0' byte.
236  * @sa
237  * NcbiAddrToString, NcbiDNSIPToAddr
238  */
240 const char* NcbiAddrToDNS(char* buf, size_t bufsize,
241  const TNCBI_IPv6Addr* addr);
242 
243 
244 /** Return non-zero(true) if "addr" belongs to the network specified as CIDR
245  * "base/bits"; return a zero(false) otherwise.
246  * @note "base" is not checked to contain all zero bits beyond "bits" (as it
247  * should), but if it does not then the return value will always be a
248  * zero(false).
249  * @sa
250  * NcbiIPv6Subnet
251  */
253 int/*bool*/ NcbiIsInIPv6Network(const TNCBI_IPv6Addr* base,
254  unsigned int bits,
255  const TNCBI_IPv6Addr* addr);
256 
257 
258 /** Retain first "bits" in a given "addr", resetting all remaining bits to 0.
259  * Return non-zero(true) if the resultant "addr" is non-empty; return a
260  * zero(false) otherwise.
261  * @note "addr" remains unmodified for "bits" larger than 127, so this call
262  * becomes functionally (but less efficiently) equivalent to negation of
263  * NcbiIsEmptyIPv6().
264  * @sa
265  * NcbiIsEmptyIPv6, NcbiIsInIPv6Network, NcbiIPv6Suffix
266  */
268 int/*bool*/ NcbiIPv6Subnet(TNCBI_IPv6Addr* addr,
269  unsigned int bits);
270 
271 
272 /** Retain last "bits" in a given "addr", resetting all remaining bits to 0.
273  * Return non-zero(true) if the resultant "addr" is non-empty; return a
274  * zero(false) otherwise.
275  * @note "addr" remains unmodified for "bits" larger than 127, so this call
276  * becomes functionally (but less efficiently) equivalent to negation of
277  * NcbiIsEmptyIPv6().
278  * @sa
279  * NcbiIsEmptyIPv6, NcbiIPv6Subnet
280  */
282 int/*bool*/ NcbiIPv6Suffix(TNCBI_IPv6Addr* addr,
283  unsigned int bits);
284 
285 
286 #ifdef __cplusplus
287 }
288 #endif /*__cplusplus*/
289 
290 
291 #endif /* CONNECT___NCBI_IPV6__H */
static const char * str(char *buf, int n)
Definition: stats.c:84
#define NCBI_XCONNECT_EXPORT
char * buf
int len
int NcbiIsEmptyIPv6(const TNCBI_IPv6Addr *addr)
Return non-zero if the address is empty (either as IPv6 or IPv4); return zero otherwise.
Definition: ncbi_ipv6.c:80
const char * NcbiStringToIPv6(TNCBI_IPv6Addr *addr, const char *str, size_t len)
Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is 0) bytes of "str" from a ...
Definition: ncbi_ipv6.c:365
const char * NcbiDNSIPToAddr(TNCBI_IPv6Addr *addr, const char *str, size_t len)
Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is 0) bytes of "str",...
Definition: ncbi_ipv6.c:697
unsigned int NcbiIPv6ToIPv4(const TNCBI_IPv6Addr *addr, size_t pfxlen)
Extract and return a network byte order IPv4 embedded address from an IPv6 address,...
Definition: ncbi_ipv6.c:101
char * NcbiAddrToString(char *buf, size_t bufsize, const TNCBI_IPv6Addr *addr)
Convert an IPv6 address into either a full-quad text IPv4 (for IPv4-mapped IPv6 addresses) or a hex c...
Definition: ncbi_ipv6.c:490
int NcbiIPv6Suffix(TNCBI_IPv6Addr *addr, unsigned int bits)
Retain last "bits" in a given "addr", resetting all remaining bits to 0.
Definition: ncbi_ipv6.c:763
char * NcbiIPv6ToString(char *buf, size_t bufsize, const TNCBI_IPv6Addr *addr)
Convert an IPv6 address into a hex colon-separated text form and store the result in the "buf" of siz...
Definition: ncbi_ipv6.c:476
int NcbiIsIPv4(const TNCBI_IPv6Addr *addr)
Return non-zero(true) if the address is a true IPv4 address (a mapped IPv4 address); return zero(fals...
Definition: ncbi_ipv6.c:89
const char * NcbiStringToIPv4(unsigned int *addr, const char *str, size_t len)
Convert into a network byte order IPv4 address, the first "len" (or "strlen(str)" if "len" is 0) byte...
Definition: ncbi_ipv6.c:346
int NcbiIsIPv4Ex(const TNCBI_IPv6Addr *addr, int compat)
Return non-zero(true) if the address is either a mapped IPv4 address or (optionally) an IPv4-compatib...
Definition: ncbi_ipv6.c:95
char * NcbiIPv4ToString(char *buf, size_t bufsize, unsigned int addr)
Convert a network byte order IPv4 into a full-quad text form and store the result in the "buf" of siz...
Definition: ncbi_ipv6.c:463
int NcbiIPv6Subnet(TNCBI_IPv6Addr *addr, unsigned int bits)
Retain first "bits" in a given "addr", resetting all remaining bits to 0.
Definition: ncbi_ipv6.c:737
const char * NcbiStringToAddr(TNCBI_IPv6Addr *addr, const char *str, size_t len)
Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is 0) bytes of "str",...
Definition: ncbi_ipv6.c:688
int NcbiIsInIPv6Network(const TNCBI_IPv6Addr *base, unsigned int bits, const TNCBI_IPv6Addr *addr)
Return non-zero(true) if "addr" belongs to the network specified as CIDR "base/bits"; return a zero(f...
Definition: ncbi_ipv6.c:706
const char * NcbiAddrToDNS(char *buf, size_t bufsize, const TNCBI_IPv6Addr *addr)
Convert an IPv6 address into either .in-addr.arpa domain (for IPv4-mapped IPv6 addresses) or ....
Definition: ncbi_ipv6.c:507
int NcbiIPv4ToIPv6(TNCBI_IPv6Addr *addr, unsigned int ipv4, size_t pfxlen)
Embed a passed network byte order IPv4 address into an IPv6 address using the specified prefix length...
Definition: ncbi_ipv6.c:142
const char * NcbiIPToAddr(TNCBI_IPv6Addr *addr, const char *str, size_t len)
Convert into an IPv6 address, the first "len" (or "strlen(str)" if "len" is 0) bytes of "str" from ei...
Definition: ncbi_ipv6.c:679
static int bufsize
Definition: pcregrep.c:162
Modified on Wed May 29 18:37:53 2024 by modify_doxy.py rev. 669887