src/third_party/npapi/npspy/extern/nspr/prnetdb.h

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