prnetdb.h@ 4885

Last change on this file since 4885 was 1, checked in by vboxsync, 55 years ago
import
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 20.4 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/xpcom18a4/nsprpub/pr/include/prnetdb.h@ 4885

Download in other formats: