nsprpub/pr/include/prnetdb.h@44a2da4a2ab2
nsprpub/pr/include/prnetdb.h
Fri, 16 Jan 2015 04:50:19 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 04:50:19 +0100
- branch
- TOR_BUG_9701
- changeset 13
- 44a2da4a2ab2
- permissions
- -rw-r--r--
Replace accessor implementation with direct member state manipulation, by
request https://trac.torproject.org/projects/tor/ticket/9701#comment:32
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #ifndef prnetdb_h___
7 #define prnetdb_h___
9 #include "prtypes.h"
10 #include "prio.h"
12 PR_BEGIN_EXTERN_C
15 /*
16 *********************************************************************
17 * Translate an Internet address to/from a character string
18 *********************************************************************
19 */
20 NSPR_API(PRStatus) PR_StringToNetAddr(
21 const char *string, PRNetAddr *addr);
23 NSPR_API(PRStatus) PR_NetAddrToString(
24 const PRNetAddr *addr, char *string, PRUint32 size);
26 /*
27 ** Structures returned by network data base library. All addresses are
28 ** supplied in host order, and returned in network order (suitable for
29 ** use in system calls).
30 */
31 /*
32 ** Beware that WINSOCK.H defines h_addrtype and h_length as short.
33 ** Client code does direct struct copies of hostent to PRHostEnt and
34 ** hence the ifdef.
35 */
36 typedef struct PRHostEnt {
37 char *h_name; /* official name of host */
38 char **h_aliases; /* alias list */
39 #ifdef WIN32
40 PRInt16 h_addrtype; /* host address type */
41 PRInt16 h_length; /* length of address */
42 #else
43 PRInt32 h_addrtype; /* host address type */
44 PRInt32 h_length; /* length of address */
45 #endif
46 char **h_addr_list; /* list of addresses from name server */
47 } PRHostEnt;
49 /* A safe size to use that will mostly work... */
50 #if (defined(AIX) && defined(_THREAD_SAFE)) || defined(OSF1)
51 #define PR_NETDB_BUF_SIZE sizeof(struct protoent_data)
52 #else
53 #define PR_NETDB_BUF_SIZE 1024
54 #endif
56 /***********************************************************************
57 ** FUNCTION:
58 ** DESCRIPTION: PR_GetHostByName()
59 ** Lookup a host by name.
60 **
61 ** INPUTS:
62 ** char *hostname Character string defining the host name of interest
63 ** char *buf A scratch buffer for the runtime to return result.
64 ** This buffer is allocated by the caller.
65 ** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
66 ** use is PR_NETDB_BUF_SIZE.
67 ** OUTPUTS:
68 ** PRHostEnt *hostentry
69 ** This structure is filled in by the runtime if
70 ** the function returns PR_SUCCESS. This structure
71 ** is allocated by the caller.
72 ** RETURN:
73 ** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
74 ** the result will be PR_FAILURE and the reason
75 ** for the failure can be retrieved by PR_GetError().
76 ***********************************************************************/
77 NSPR_API(PRStatus) PR_GetHostByName(
78 const char *hostname, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
80 /***********************************************************************
81 ** FUNCTION:
82 ** DESCRIPTION: PR_GetIPNodeByName()
83 ** Lookup a host by name. Equivalent to getipnodebyname(AI_DEFAULT)
84 ** of RFC 2553.
85 **
86 ** INPUTS:
87 ** char *hostname Character string defining the host name of interest
88 ** PRUint16 af Address family (either PR_AF_INET or PR_AF_INET6)
89 ** PRIntn flags Specifies the types of addresses that are searched
90 ** for and the types of addresses that are returned.
91 ** The only supported flag is PR_AI_DEFAULT.
92 ** char *buf A scratch buffer for the runtime to return result.
93 ** This buffer is allocated by the caller.
94 ** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
95 ** use is PR_NETDB_BUF_SIZE.
96 ** OUTPUTS:
97 ** PRHostEnt *hostentry
98 ** This structure is filled in by the runtime if
99 ** the function returns PR_SUCCESS. This structure
100 ** is allocated by the caller.
101 ** RETURN:
102 ** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
103 ** the result will be PR_FAILURE and the reason
104 ** for the failure can be retrieved by PR_GetError().
105 ***********************************************************************/
108 #define PR_AI_ALL 0x08
109 #define PR_AI_V4MAPPED 0x10
110 #define PR_AI_ADDRCONFIG 0x20
111 #define PR_AI_NOCANONNAME 0x8000
112 #define PR_AI_DEFAULT (PR_AI_V4MAPPED | PR_AI_ADDRCONFIG)
114 NSPR_API(PRStatus) PR_GetIPNodeByName(
115 const char *hostname,
116 PRUint16 af,
117 PRIntn flags,
118 char *buf,
119 PRIntn bufsize,
120 PRHostEnt *hostentry);
122 /***********************************************************************
123 ** FUNCTION:
124 ** DESCRIPTION: PR_GetHostByAddr()
125 ** Lookup a host entry by its network address.
126 **
127 ** INPUTS:
128 ** char *hostaddr IP address of host in question
129 ** char *buf A scratch buffer for the runtime to return result.
130 ** This buffer is allocated by the caller.
131 ** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
132 ** use is PR_NETDB_BUF_SIZE.
133 ** OUTPUTS:
134 ** PRHostEnt *hostentry
135 ** This structure is filled in by the runtime if
136 ** the function returns PR_SUCCESS. This structure
137 ** is allocated by the caller.
138 ** RETURN:
139 ** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
140 ** the result will be PR_FAILURE and the reason
141 ** for the failure can be retrieved by PR_GetError().
142 ***********************************************************************/
143 NSPR_API(PRStatus) PR_GetHostByAddr(
144 const PRNetAddr *hostaddr, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
146 /***********************************************************************
147 ** FUNCTION: PR_EnumerateHostEnt()
148 ** DESCRIPTION:
149 ** A stateless enumerator over a PRHostEnt structure acquired from
150 ** PR_GetHostByName() PR_GetHostByAddr() to evaluate the possible
151 ** network addresses.
152 **
153 ** INPUTS:
154 ** PRIntn enumIndex Index of the enumeration. The enumeration starts
155 ** and ends with a value of zero.
156 **
157 ** PRHostEnt *hostEnt A pointer to a host entry struct that was
158 ** previously returned by PR_GetHostByName() or
159 ** PR_GetHostByAddr().
160 **
161 ** PRUint16 port The port number to be assigned as part of the
162 ** PRNetAddr.
163 **
164 ** OUTPUTS:
165 ** PRNetAddr *address A pointer to an address structure that will be
166 ** filled in by the call to the enumeration if the
167 ** result of the call is greater than zero.
168 **
169 ** RETURN:
170 ** PRIntn The value that should be used for the next call
171 ** of the enumerator ('enumIndex'). The enumeration
172 ** is ended if this value is returned zero.
173 ** If a value of -1 is returned, the enumeration
174 ** has failed. The reason for the failure can be
175 ** retrieved by calling PR_GetError().
176 ***********************************************************************/
177 NSPR_API(PRIntn) PR_EnumerateHostEnt(
178 PRIntn enumIndex, const PRHostEnt *hostEnt, PRUint16 port, PRNetAddr *address);
180 /***********************************************************************
181 ** FUNCTION: PR_InitializeNetAddr(),
182 ** DESCRIPTION:
183 ** Initialize the fields of a PRNetAddr, assigning well known values as
184 ** appropriate.
185 **
186 ** INPUTS
187 ** PRNetAddrValue val The value to be assigned to the IP Address portion
188 ** of the network address. This can only specify the
189 ** special well known values that are equivalent to
190 ** INADDR_ANY and INADDR_LOOPBACK.
191 **
192 ** PRUint16 port The port number to be assigned in the structure.
193 **
194 ** OUTPUTS:
195 ** PRNetAddr *addr The address to be manipulated.
196 **
197 ** RETURN:
198 ** PRStatus To indicate success or failure. If the latter, the
199 ** reason for the failure can be retrieved by calling
200 ** PR_GetError();
201 ***********************************************************************/
202 typedef enum PRNetAddrValue
203 {
204 PR_IpAddrNull, /* do NOT overwrite the IP address */
205 PR_IpAddrAny, /* assign logical INADDR_ANY to IP address */
206 PR_IpAddrLoopback, /* assign logical INADDR_LOOPBACK */
207 PR_IpAddrV4Mapped /* IPv4 mapped address */
208 } PRNetAddrValue;
210 NSPR_API(PRStatus) PR_InitializeNetAddr(
211 PRNetAddrValue val, PRUint16 port, PRNetAddr *addr);
213 /***********************************************************************
214 ** FUNCTION: PR_SetNetAddr(),
215 ** DESCRIPTION:
216 ** Set the fields of a PRNetAddr, assigning well known values as
217 ** appropriate. This function is similar to PR_InitializeNetAddr
218 ** but differs in that the address family is specified.
219 **
220 ** INPUTS
221 ** PRNetAddrValue val The value to be assigned to the IP Address portion
222 ** of the network address. This can only specify the
223 ** special well known values that are equivalent to
224 ** INADDR_ANY and INADDR_LOOPBACK.
225 **
226 ** PRUint16 af The address family (either PR_AF_INET or PR_AF_INET6)
227 **
228 ** PRUint16 port The port number to be assigned in the structure.
229 **
230 ** OUTPUTS:
231 ** PRNetAddr *addr The address to be manipulated.
232 **
233 ** RETURN:
234 ** PRStatus To indicate success or failure. If the latter, the
235 ** reason for the failure can be retrieved by calling
236 ** PR_GetError();
237 ***********************************************************************/
238 NSPR_API(PRStatus) PR_SetNetAddr(
239 PRNetAddrValue val, PRUint16 af, PRUint16 port, PRNetAddr *addr);
241 /***********************************************************************
242 ** FUNCTION:
243 ** DESCRIPTION: PR_IsNetAddrType()
244 ** Determine if the network address is of the specified type.
245 **
246 ** INPUTS:
247 ** const PRNetAddr *addr A network address.
248 ** PRNetAddrValue The type of network address
249 **
250 ** RETURN:
251 ** PRBool PR_TRUE if the network address is of the
252 ** specified type, else PR_FALSE.
253 ***********************************************************************/
254 NSPR_API(PRBool) PR_IsNetAddrType(const PRNetAddr *addr, PRNetAddrValue val);
256 /***********************************************************************
257 ** FUNCTION:
258 ** DESCRIPTION: PR_ConvertIPv4AddrToIPv6()
259 ** Convert an IPv4 addr to an (IPv4-mapped) IPv6 addr
260 **
261 ** INPUTS:
262 ** PRUint32 v4addr IPv4 address
263 **
264 ** OUTPUTS:
265 ** PRIPv6Addr *v6addr The converted IPv6 address
266 **
267 ** RETURN:
268 ** void
269 **
270 ***********************************************************************/
271 NSPR_API(void) PR_ConvertIPv4AddrToIPv6(PRUint32 v4addr, PRIPv6Addr *v6addr);
273 /***********************************************************************
274 ** MACRO:
275 ** DESCRIPTION: PR_NetAddrFamily()
276 ** Get the 'family' field of a PRNetAddr union.
277 **
278 ** INPUTS:
279 ** const PRNetAddr *addr A network address.
280 **
281 ** RETURN:
282 ** PRUint16 The 'family' field of 'addr'.
283 ***********************************************************************/
284 #define PR_NetAddrFamily(addr) ((addr)->raw.family)
286 /***********************************************************************
287 ** MACRO:
288 ** DESCRIPTION: PR_NetAddrInetPort()
289 ** Get the 'port' field of a PRNetAddr union.
290 **
291 ** INPUTS:
292 ** const PRNetAddr *addr A network address.
293 **
294 ** RETURN:
295 ** PRUint16 The 'port' field of 'addr'.
296 ***********************************************************************/
297 #define PR_NetAddrInetPort(addr) \
298 ((addr)->raw.family == PR_AF_INET6 ? (addr)->ipv6.port : (addr)->inet.port)
300 /***********************************************************************
301 ** FUNCTION:
302 ** DESCRIPTION: PR_GetProtoByName()
303 ** Lookup a protocol entry based on protocol's name
304 **
305 ** INPUTS:
306 ** char *protocolname Character string of the protocol's name.
307 ** char *buf A scratch buffer for the runtime to return result.
308 ** This buffer is allocated by the caller.
309 ** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
310 ** use is PR_NETDB_BUF_SIZE.
311 ** OUTPUTS:
312 ** PRHostEnt *PRProtoEnt
313 ** This structure is filled in by the runtime if
314 ** the function returns PR_SUCCESS. This structure
315 ** is allocated by the caller.
316 ** RETURN:
317 ** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
318 ** the result will be PR_FAILURE and the reason
319 ** for the failure can be retrieved by PR_GetError().
320 ***********************************************************************/
322 typedef struct PRProtoEnt {
323 char *p_name; /* official protocol name */
324 char **p_aliases; /* alias list */
325 #ifdef WIN32
326 PRInt16 p_num; /* protocol # */
327 #else
328 PRInt32 p_num; /* protocol # */
329 #endif
330 } PRProtoEnt;
332 NSPR_API(PRStatus) PR_GetProtoByName(
333 const char* protocolname, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
335 /***********************************************************************
336 ** FUNCTION:
337 ** DESCRIPTION: PR_GetProtoByNumber()
338 ** Lookup a protocol entry based on protocol's number
339 **
340 ** INPUTS:
341 ** PRInt32 protocolnumber
342 ** Number assigned to the protocol.
343 ** char *buf A scratch buffer for the runtime to return result.
344 ** This buffer is allocated by the caller.
345 ** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
346 ** use is PR_NETDB_BUF_SIZE.
347 ** OUTPUTS:
348 ** PRHostEnt *PRProtoEnt
349 ** This structure is filled in by the runtime if
350 ** the function returns PR_SUCCESS. This structure
351 ** is allocated by the caller.
352 ** RETURN:
353 ** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
354 ** the result will be PR_FAILURE and the reason
355 ** for the failure can be retrieved by PR_GetError().
356 ***********************************************************************/
357 NSPR_API(PRStatus) PR_GetProtoByNumber(
358 PRInt32 protocolnumber, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
360 /***********************************************************************
361 ** FUNCTION:
362 ** DESCRIPTION: PR_GetAddrInfoByName()
363 ** Look up a host by name. Equivalent to getaddrinfo(host, NULL, ...) of
364 ** RFC 3493.
365 **
366 ** INPUTS:
367 ** char *hostname Character string defining the host name of interest
368 ** PRUint16 af May be PR_AF_UNSPEC or PR_AF_INET.
369 ** PRIntn flags May be either PR_AI_ADDRCONFIG or
370 ** PR_AI_ADDRCONFIG | PR_AI_NOCANONNAME. Include
371 ** PR_AI_NOCANONNAME to suppress the determination of
372 ** the canonical name corresponding to hostname.
373 ** RETURN:
374 ** PRAddrInfo* Handle to a data structure containing the results
375 ** of the host lookup. Use PR_EnumerateAddrInfo to
376 ** inspect the PRNetAddr values stored in this object.
377 ** When no longer needed, this handle must be destroyed
378 ** with a call to PR_FreeAddrInfo. If a lookup error
379 ** occurs, then NULL will be returned.
380 ***********************************************************************/
381 typedef struct PRAddrInfo PRAddrInfo;
383 NSPR_API(PRAddrInfo*) PR_GetAddrInfoByName(
384 const char *hostname, PRUint16 af, PRIntn flags);
386 /***********************************************************************
387 ** FUNCTION:
388 ** DESCRIPTION: PR_FreeAddrInfo()
389 ** Destroy the PRAddrInfo handle allocated by PR_GetAddrInfoByName().
390 **
391 ** INPUTS:
392 ** PRAddrInfo *addrInfo
393 ** The handle resulting from a successful call to
394 ** PR_GetAddrInfoByName().
395 ** RETURN:
396 ** void
397 ***********************************************************************/
398 NSPR_API(void) PR_FreeAddrInfo(PRAddrInfo *addrInfo);
400 /***********************************************************************
401 ** FUNCTION:
402 ** DESCRIPTION: PR_EnumerateAddrInfo()
403 ** A stateless enumerator over a PRAddrInfo handle acquired from
404 ** PR_GetAddrInfoByName() to inspect the possible network addresses.
405 **
406 ** INPUTS:
407 ** void *enumPtr Index pointer of the enumeration. The enumeration
408 ** starts and ends with a value of NULL.
409 ** const PRAddrInfo *addrInfo
410 ** The PRAddrInfo handle returned by a successful
411 ** call to PR_GetAddrInfoByName().
412 ** PRUint16 port The port number to be assigned as part of the
413 ** PRNetAddr.
414 ** OUTPUTS:
415 ** PRNetAddr *result A pointer to an address structure that will be
416 ** filled in by the call to the enumeration if the
417 ** result of the call is not NULL.
418 ** RETURN:
419 ** void* The value that should be used for the next call
420 ** of the enumerator ('enumPtr'). The enumeration
421 ** is ended if this value is NULL.
422 ***********************************************************************/
423 NSPR_API(void *) PR_EnumerateAddrInfo(
424 void *enumPtr, const PRAddrInfo *addrInfo, PRUint16 port, PRNetAddr *result);
426 /***********************************************************************
427 ** FUNCTION:
428 ** DESCRIPTION: PR_GetCanonNameFromAddrInfo()
429 ** Extracts the canonical name of the hostname passed to
430 ** PR_GetAddrInfoByName().
431 **
432 ** INPUTS:
433 ** const PRAddrInfo *addrInfo
434 ** The PRAddrInfo handle returned by a successful
435 ** call to PR_GetAddrInfoByName().
436 ** RETURN:
437 ** const char * A const pointer to the canonical hostname stored
438 ** in the given PRAddrInfo handle. This pointer is
439 ** invalidated once the PRAddrInfo handle is destroyed
440 ** by a call to PR_FreeAddrInfo().
441 ***********************************************************************/
442 NSPR_API(const char *) PR_GetCanonNameFromAddrInfo(
443 const PRAddrInfo *addrInfo);
445 /***********************************************************************
446 ** FUNCTIONS: PR_ntohs, PR_ntohl, PR_ntohll, PR_htons, PR_htonl, PR_htonll
447 **
448 ** DESCRIPTION: API entries for the common byte ordering routines.
449 **
450 ** PR_ntohs 16 bit conversion from network to host
451 ** PR_ntohl 32 bit conversion from network to host
452 ** PR_ntohll 64 bit conversion from network to host
453 ** PR_htons 16 bit conversion from host to network
454 ** PR_htonl 32 bit conversion from host to network
455 ** PR_ntonll 64 bit conversion from host to network
456 **
457 ***********************************************************************/
458 NSPR_API(PRUint16) PR_ntohs(PRUint16);
459 NSPR_API(PRUint32) PR_ntohl(PRUint32);
460 NSPR_API(PRUint64) PR_ntohll(PRUint64);
461 NSPR_API(PRUint16) PR_htons(PRUint16);
462 NSPR_API(PRUint32) PR_htonl(PRUint32);
463 NSPR_API(PRUint64) PR_htonll(PRUint64);
465 PR_END_EXTERN_C
467 #endif /* prnetdb_h___ */
