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

source code of include/nspr/prnetdb.h