nsprpub/pr/include/prnetdb.h

   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___ */