nsprpub/pr/include/prnetdb.h

   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
  12 PR_BEGIN_EXTERN_C
  13
  14
  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);
  22
  23 NSPR_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 */
  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;
  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 ***********************************************************************/
  82 NSPR_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
 119 NSPR_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 ***********************************************************************/
 148 NSPR_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 ***********************************************************************/
 182 NSPR_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 ***********************************************************************/
 207 typedef 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
 215 NSPR_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 ***********************************************************************/
 243 NSPR_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 ***********************************************************************/
 259 NSPR_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 ***********************************************************************/
 276 NSPR_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
 327 typedef 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
 337 NSPR_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 ***********************************************************************/
 362 NSPR_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 ***********************************************************************/
 386 typedef struct PRAddrInfo PRAddrInfo;
 387
 388 NSPR_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 ***********************************************************************/
 403 NSPR_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 ***********************************************************************/
 428 NSPR_API(void *) PR_EnumerateAddrInfo(
 429     void *enumPtr, const PRAddrInfo *addrInfo, PRUint16 port, PRNetAddr *result);
 430
 431 NSPR_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 ***********************************************************************/
 450 NSPR_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 ***********************************************************************/
 466 NSPR_API(PRUint16) PR_ntohs(PRUint16);
 467 NSPR_API(PRUint32) PR_ntohl(PRUint32);
 468 NSPR_API(PRUint64) PR_ntohll(PRUint64);
 469 NSPR_API(PRUint16) PR_htons(PRUint16);
 470 NSPR_API(PRUint32) PR_htonl(PRUint32);
 471 NSPR_API(PRUint64) PR_htonll(PRUint64);
 472
 473 PR_END_EXTERN_C
 474
 475 #endif /* prnetdb_h___ */