PageRenderTime 166ms CodeModel.GetById 101ms app.highlight 11ms RepoModel.GetById 49ms app.codeStats 0ms

/gecko_api/include/prnetdb.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 499 lines | 89 code | 34 blank | 376 comment | 5 complexity | a119650cd64db1f80d817160e7aae467 MD5 | raw file
  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
 44PR_BEGIN_EXTERN_C
 45
 46
 47/*
 48 *********************************************************************
 49 *  Translate an Internet address to/from a character string
 50 *********************************************************************
 51 */
 52NSPR_API(PRStatus) PR_StringToNetAddr(
 53    const char *string, PRNetAddr *addr);
 54
 55NSPR_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*/
 68typedef 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***********************************************************************/
109NSPR_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
146NSPR_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***********************************************************************/
175NSPR_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***********************************************************************/
209NSPR_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***********************************************************************/
234typedef 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
242NSPR_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***********************************************************************/
270NSPR_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***********************************************************************/
286NSPR_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***********************************************************************/
303NSPR_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
354typedef 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
364NSPR_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***********************************************************************/
389NSPR_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***********************************************************************/
413typedef struct PRAddrInfo PRAddrInfo;
414
415NSPR_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***********************************************************************/
430NSPR_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***********************************************************************/
455NSPR_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***********************************************************************/
474NSPR_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***********************************************************************/
490NSPR_API(PRUint16) PR_ntohs(PRUint16);
491NSPR_API(PRUint32) PR_ntohl(PRUint32);
492NSPR_API(PRUint64) PR_ntohll(PRUint64);
493NSPR_API(PRUint16) PR_htons(PRUint16);
494NSPR_API(PRUint32) PR_htonl(PRUint32);
495NSPR_API(PRUint64) PR_htonll(PRUint64);
496
497PR_END_EXTERN_C
498
499#endif /* prnetdb_h___ */