andre@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public
andre@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
andre@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
andre@0: 
andre@0: #ifndef prnetdb_h___
andre@0: #define prnetdb_h___
andre@0: 
andre@0: #include "prtypes.h"
andre@0: #include "prio.h"
andre@0: 
andre@0: PR_BEGIN_EXTERN_C
andre@0: 
andre@0: 
andre@0: /*
andre@0:  *********************************************************************
andre@0:  *  Translate an Internet address to/from a character string
andre@0:  *********************************************************************
andre@0:  */
andre@0: NSPR_API(PRStatus) PR_StringToNetAddr(
andre@0:     const char *string, PRNetAddr *addr);
andre@0: 
andre@0: NSPR_API(PRStatus) PR_NetAddrToString(
andre@0:     const PRNetAddr *addr, char *string, PRUint32 size);
andre@0: 
andre@0: /*
andre@0: ** Structures returned by network data base library.  All addresses are
andre@0: ** supplied in host order, and returned in network order (suitable for
andre@0: ** use in system calls).
andre@0: */
andre@0: /*
andre@0: ** Beware that WINSOCK.H defines h_addrtype and h_length as short.
andre@0: ** Client code does direct struct copies of hostent to PRHostEnt and
andre@0: ** hence the ifdef.
andre@0: */
andre@0: typedef struct PRHostEnt {
andre@0:     char *h_name;       /* official name of host */
andre@0:     char **h_aliases;   /* alias list */
andre@0: #ifdef WIN32
andre@0:     PRInt16 h_addrtype; /* host address type */
andre@0:     PRInt16 h_length;   /* length of address */
andre@0: #else
andre@0:     PRInt32 h_addrtype; /* host address type */
andre@0:     PRInt32 h_length;   /* length of address */
andre@0: #endif
andre@0:     char **h_addr_list; /* list of addresses from name server */
andre@0: } PRHostEnt;
andre@0: 
andre@0: /* A safe size to use that will mostly work... */
andre@0: #if (defined(AIX) && defined(_THREAD_SAFE)) || defined(OSF1)
andre@0: #define PR_NETDB_BUF_SIZE sizeof(struct protoent_data)
andre@0: #else
andre@0: #define PR_NETDB_BUF_SIZE 1024
andre@0: #endif
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_GetHostByName()
andre@0: ** Lookup a host by name.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  char *hostname      Character string defining the host name of interest
andre@0: **  char *buf           A scratch buffer for the runtime to return result.
andre@0: **                      This buffer is allocated by the caller.
andre@0: **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
andre@0: **                      use is PR_NETDB_BUF_SIZE.
andre@0: ** OUTPUTS:
andre@0: **  PRHostEnt *hostentry
andre@0: **                      This structure is filled in by the runtime if
andre@0: **                      the function returns PR_SUCCESS. This structure
andre@0: **                      is allocated by the caller.
andre@0: ** RETURN:
andre@0: **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
andre@0: **                      the result will be PR_FAILURE and the reason
andre@0: **                      for the failure can be retrieved by PR_GetError().
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRStatus) PR_GetHostByName(
andre@0:     const char *hostname, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_GetIPNodeByName()
andre@0: ** Lookup a host by name. Equivalent to getipnodebyname(AI_DEFAULT)
andre@0: ** of RFC 2553.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  char *hostname      Character string defining the host name of interest
andre@0: **  PRUint16 af         Address family (either PR_AF_INET or PR_AF_INET6)
andre@0: **  PRIntn flags        Specifies the types of addresses that are searched
andre@0: **                      for and the types of addresses that are returned.
andre@0: **                      The only supported flag is PR_AI_DEFAULT.
andre@0: **  char *buf           A scratch buffer for the runtime to return result.
andre@0: **                      This buffer is allocated by the caller.
andre@0: **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
andre@0: **                      use is PR_NETDB_BUF_SIZE.
andre@0: ** OUTPUTS:
andre@0: **  PRHostEnt *hostentry
andre@0: **                      This structure is filled in by the runtime if
andre@0: **                      the function returns PR_SUCCESS. This structure
andre@0: **                      is allocated by the caller.
andre@0: ** RETURN:
andre@0: **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
andre@0: **                      the result will be PR_FAILURE and the reason
andre@0: **                      for the failure can be retrieved by PR_GetError().
andre@0: ***********************************************************************/
andre@0: 
andre@0: 
andre@0: #define PR_AI_ALL         0x08
andre@0: #define PR_AI_V4MAPPED    0x10
andre@0: #define PR_AI_ADDRCONFIG  0x20
andre@0: #define PR_AI_NOCANONNAME 0x8000
andre@0: #define PR_AI_DEFAULT     (PR_AI_V4MAPPED | PR_AI_ADDRCONFIG)
andre@0: 
andre@0: NSPR_API(PRStatus) PR_GetIPNodeByName(
andre@0:     const char *hostname,
andre@0:     PRUint16 af,
andre@0:     PRIntn flags,
andre@0:     char *buf,
andre@0:     PRIntn bufsize,
andre@0:     PRHostEnt *hostentry);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_GetHostByAddr()
andre@0: ** Lookup a host entry by its network address.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  char *hostaddr      IP address of host in question
andre@0: **  char *buf           A scratch buffer for the runtime to return result.
andre@0: **                      This buffer is allocated by the caller.
andre@0: **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
andre@0: **                      use is PR_NETDB_BUF_SIZE.
andre@0: ** OUTPUTS:
andre@0: **  PRHostEnt *hostentry
andre@0: **                      This structure is filled in by the runtime if
andre@0: **                      the function returns PR_SUCCESS. This structure
andre@0: **                      is allocated by the caller.
andre@0: ** RETURN:
andre@0: **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
andre@0: **                      the result will be PR_FAILURE and the reason
andre@0: **                      for the failure can be retrieved by PR_GetError().
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRStatus) PR_GetHostByAddr(
andre@0:     const PRNetAddr *hostaddr, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	PR_EnumerateHostEnt()	
andre@0: ** DESCRIPTION:
andre@0: **  A stateless enumerator over a PRHostEnt structure acquired from
andre@0: **  PR_GetHostByName() PR_GetHostByAddr() to evaluate the possible
andre@0: **  network addresses.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  PRIntn  enumIndex   Index of the enumeration. The enumeration starts
andre@0: **                      and ends with a value of zero.
andre@0: **
andre@0: **  PRHostEnt *hostEnt  A pointer to a host entry struct that was
andre@0: **                      previously returned by PR_GetHostByName() or
andre@0: **                      PR_GetHostByAddr().
andre@0: **
andre@0: **  PRUint16 port       The port number to be assigned as part of the
andre@0: **                      PRNetAddr.
andre@0: **
andre@0: ** OUTPUTS:
andre@0: **  PRNetAddr *address  A pointer to an address structure that will be
andre@0: **                      filled in by the call to the enumeration if the
andre@0: **                      result of the call is greater than zero.
andre@0: **
andre@0: ** RETURN:
andre@0: **  PRIntn              The value that should be used for the next call
andre@0: **                      of the enumerator ('enumIndex'). The enumeration
andre@0: **                      is ended if this value is returned zero.
andre@0: **                      If a value of -1 is returned, the enumeration
andre@0: **                      has failed. The reason for the failure can be
andre@0: **                      retrieved by calling PR_GetError().
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRIntn) PR_EnumerateHostEnt(
andre@0:     PRIntn enumIndex, const PRHostEnt *hostEnt, PRUint16 port, PRNetAddr *address);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION: PR_InitializeNetAddr(), 
andre@0: ** DESCRIPTION:
andre@0: **  Initialize the fields of a PRNetAddr, assigning well known values as
andre@0: **  appropriate.
andre@0: **
andre@0: ** INPUTS
andre@0: **  PRNetAddrValue val  The value to be assigned to the IP Address portion
andre@0: **                      of the network address. This can only specify the
andre@0: **                      special well known values that are equivalent to
andre@0: **                      INADDR_ANY and INADDR_LOOPBACK.
andre@0: **
andre@0: **  PRUint16 port       The port number to be assigned in the structure.
andre@0: **
andre@0: ** OUTPUTS:
andre@0: **  PRNetAddr *addr     The address to be manipulated.
andre@0: **
andre@0: ** RETURN:
andre@0: **  PRStatus            To indicate success or failure. If the latter, the
andre@0: **                      reason for the failure can be retrieved by calling
andre@0: **                      PR_GetError();
andre@0: ***********************************************************************/
andre@0: typedef enum PRNetAddrValue
andre@0: {
andre@0:     PR_IpAddrNull,      /* do NOT overwrite the IP address */
andre@0:     PR_IpAddrAny,       /* assign logical INADDR_ANY to IP address */
andre@0:     PR_IpAddrLoopback,  /* assign logical INADDR_LOOPBACK  */
andre@0:     PR_IpAddrV4Mapped   /* IPv4 mapped address */
andre@0: } PRNetAddrValue;
andre@0: 
andre@0: NSPR_API(PRStatus) PR_InitializeNetAddr(
andre@0:     PRNetAddrValue val, PRUint16 port, PRNetAddr *addr);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION: PR_SetNetAddr(), 
andre@0: ** DESCRIPTION:
andre@0: **  Set the fields of a PRNetAddr, assigning well known values as
andre@0: **  appropriate. This function is similar to PR_InitializeNetAddr
andre@0: **  but differs in that the address family is specified.
andre@0: **
andre@0: ** INPUTS
andre@0: **  PRNetAddrValue val  The value to be assigned to the IP Address portion
andre@0: **                      of the network address. This can only specify the
andre@0: **                      special well known values that are equivalent to
andre@0: **                      INADDR_ANY and INADDR_LOOPBACK.
andre@0: **
andre@0: **  PRUint16 af         The address family (either PR_AF_INET or PR_AF_INET6)
andre@0: **
andre@0: **  PRUint16 port       The port number to be assigned in the structure.
andre@0: **
andre@0: ** OUTPUTS:
andre@0: **  PRNetAddr *addr     The address to be manipulated.
andre@0: **
andre@0: ** RETURN:
andre@0: **  PRStatus            To indicate success or failure. If the latter, the
andre@0: **                      reason for the failure can be retrieved by calling
andre@0: **                      PR_GetError();
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRStatus) PR_SetNetAddr(
andre@0:     PRNetAddrValue val, PRUint16 af, PRUint16 port, PRNetAddr *addr);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_IsNetAddrType()
andre@0: ** Determine if the network address is of the specified type.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  const PRNetAddr *addr   A network address.
andre@0: **  PRNetAddrValue          The type of network address 
andre@0: **
andre@0: ** RETURN:
andre@0: **  PRBool                  PR_TRUE if the network address is of the
andre@0: **                          specified type, else PR_FALSE.
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRBool) PR_IsNetAddrType(const PRNetAddr *addr, PRNetAddrValue val);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_ConvertIPv4AddrToIPv6()
andre@0: ** Convert an IPv4 addr to an (IPv4-mapped) IPv6 addr
andre@0: **
andre@0: ** INPUTS:
andre@0: **  PRUint32 	v4addr		IPv4 address
andre@0: **
andre@0: ** OUTPUTS:
andre@0: **  PRIPv6Addr *v6addr      The converted IPv6 address
andre@0: **
andre@0: ** RETURN:
andre@0: **  void
andre@0: **                       
andre@0: ***********************************************************************/
andre@0: NSPR_API(void) PR_ConvertIPv4AddrToIPv6(PRUint32 v4addr, PRIPv6Addr *v6addr);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** MACRO:	
andre@0: ** DESCRIPTION:	PR_NetAddrFamily()
andre@0: ** Get the 'family' field of a PRNetAddr union.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  const PRNetAddr *addr   A network address.
andre@0: **
andre@0: ** RETURN:
andre@0: **  PRUint16                The 'family' field of 'addr'.
andre@0: ***********************************************************************/
andre@0: #define PR_NetAddrFamily(addr) ((addr)->raw.family)
andre@0: 
andre@0: /***********************************************************************
andre@0: ** MACRO:	
andre@0: ** DESCRIPTION:	PR_NetAddrInetPort()
andre@0: ** Get the 'port' field of a PRNetAddr union.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  const PRNetAddr *addr   A network address.
andre@0: **
andre@0: ** RETURN:
andre@0: **  PRUint16                The 'port' field of 'addr'.
andre@0: ***********************************************************************/
andre@0: #define PR_NetAddrInetPort(addr) \
andre@0:     ((addr)->raw.family == PR_AF_INET6 ? (addr)->ipv6.port : (addr)->inet.port)
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_GetProtoByName()
andre@0: ** Lookup a protocol entry based on protocol's name
andre@0: **
andre@0: ** INPUTS:
andre@0: **  char *protocolname  Character string of the protocol's name.
andre@0: **  char *buf           A scratch buffer for the runtime to return result.
andre@0: **                      This buffer is allocated by the caller.
andre@0: **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
andre@0: **                      use is PR_NETDB_BUF_SIZE.
andre@0: ** OUTPUTS:
andre@0: **  PRHostEnt *PRProtoEnt
andre@0: **                      This structure is filled in by the runtime if
andre@0: **                      the function returns PR_SUCCESS. This structure
andre@0: **                      is allocated by the caller.
andre@0: ** RETURN:
andre@0: **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
andre@0: **                      the result will be PR_FAILURE and the reason
andre@0: **                      for the failure can be retrieved by PR_GetError().
andre@0: ***********************************************************************/
andre@0: 
andre@0: typedef struct PRProtoEnt {
andre@0:     char *p_name;       /* official protocol name */
andre@0:     char **p_aliases;   /* alias list */
andre@0: #ifdef WIN32
andre@0:     PRInt16 p_num;      /* protocol # */
andre@0: #else
andre@0:     PRInt32 p_num;      /* protocol # */
andre@0: #endif
andre@0: } PRProtoEnt;
andre@0: 
andre@0: NSPR_API(PRStatus) PR_GetProtoByName(
andre@0:     const char* protocolname, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:	
andre@0: ** DESCRIPTION:	PR_GetProtoByNumber()
andre@0: ** Lookup a protocol entry based on protocol's number
andre@0: **
andre@0: ** INPUTS:
andre@0: **  PRInt32 protocolnumber
andre@0: **                      Number assigned to the protocol.
andre@0: **  char *buf           A scratch buffer for the runtime to return result.
andre@0: **                      This buffer is allocated by the caller.
andre@0: **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
andre@0: **                      use is PR_NETDB_BUF_SIZE.
andre@0: ** OUTPUTS:
andre@0: **  PRHostEnt *PRProtoEnt
andre@0: **                      This structure is filled in by the runtime if
andre@0: **                      the function returns PR_SUCCESS. This structure
andre@0: **                      is allocated by the caller.
andre@0: ** RETURN:
andre@0: **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
andre@0: **                      the result will be PR_FAILURE and the reason
andre@0: **                      for the failure can be retrieved by PR_GetError().
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRStatus) PR_GetProtoByNumber(
andre@0:     PRInt32 protocolnumber, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:
andre@0: ** DESCRIPTION: PR_GetAddrInfoByName()
andre@0: **  Look up a host by name. Equivalent to getaddrinfo(host, NULL, ...) of
andre@0: **  RFC 3493.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  char *hostname      Character string defining the host name of interest
andre@0: **  PRUint16 af         May be PR_AF_UNSPEC or PR_AF_INET.
andre@0: **  PRIntn flags        May be either PR_AI_ADDRCONFIG or
andre@0: **                      PR_AI_ADDRCONFIG | PR_AI_NOCANONNAME. Include
andre@0: **                      PR_AI_NOCANONNAME to suppress the determination of
andre@0: **                      the canonical name corresponding to hostname.
andre@0: ** RETURN:
andre@0: **  PRAddrInfo*         Handle to a data structure containing the results
andre@0: **                      of the host lookup. Use PR_EnumerateAddrInfo to
andre@0: **                      inspect the PRNetAddr values stored in this object.
andre@0: **                      When no longer needed, this handle must be destroyed
andre@0: **                      with a call to PR_FreeAddrInfo.  If a lookup error
andre@0: **                      occurs, then NULL will be returned.
andre@0: ***********************************************************************/
andre@0: typedef struct PRAddrInfo PRAddrInfo;
andre@0: 
andre@0: NSPR_API(PRAddrInfo*) PR_GetAddrInfoByName(
andre@0:     const char *hostname, PRUint16 af, PRIntn flags);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:
andre@0: ** DESCRIPTION: PR_FreeAddrInfo()
andre@0: **  Destroy the PRAddrInfo handle allocated by PR_GetAddrInfoByName().
andre@0: **
andre@0: ** INPUTS:
andre@0: **  PRAddrInfo *addrInfo
andre@0: **                      The handle resulting from a successful call to
andre@0: **                      PR_GetAddrInfoByName().
andre@0: ** RETURN:
andre@0: **  void
andre@0: ***********************************************************************/
andre@0: NSPR_API(void) PR_FreeAddrInfo(PRAddrInfo *addrInfo);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:
andre@0: ** DESCRIPTION: PR_EnumerateAddrInfo()
andre@0: **  A stateless enumerator over a PRAddrInfo handle acquired from
andre@0: **  PR_GetAddrInfoByName() to inspect the possible network addresses.
andre@0: **
andre@0: ** INPUTS:
andre@0: **  void *enumPtr       Index pointer of the enumeration. The enumeration
andre@0: **                      starts and ends with a value of NULL.
andre@0: **  const PRAddrInfo *addrInfo
andre@0: **                      The PRAddrInfo handle returned by a successful
andre@0: **                      call to PR_GetAddrInfoByName().
andre@0: **  PRUint16 port       The port number to be assigned as part of the
andre@0: **                      PRNetAddr.
andre@0: ** OUTPUTS:
andre@0: **  PRNetAddr *result   A pointer to an address structure that will be
andre@0: **                      filled in by the call to the enumeration if the
andre@0: **                      result of the call is not NULL.
andre@0: ** RETURN:
andre@0: **  void*               The value that should be used for the next call
andre@0: **                      of the enumerator ('enumPtr'). The enumeration
andre@0: **                      is ended if this value is NULL.
andre@0: ***********************************************************************/
andre@0: NSPR_API(void *) PR_EnumerateAddrInfo(
andre@0:     void *enumPtr, const PRAddrInfo *addrInfo, PRUint16 port, PRNetAddr *result);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTION:
andre@0: ** DESCRIPTION: PR_GetCanonNameFromAddrInfo()
andre@0: **  Extracts the canonical name of the hostname passed to
andre@0: **  PR_GetAddrInfoByName().
andre@0: **
andre@0: ** INPUTS:
andre@0: **  const PRAddrInfo *addrInfo 
andre@0: **                      The PRAddrInfo handle returned by a successful
andre@0: **                      call to PR_GetAddrInfoByName().
andre@0: ** RETURN:
andre@0: **  const char *        A const pointer to the canonical hostname stored
andre@0: **                      in the given PRAddrInfo handle. This pointer is
andre@0: **                      invalidated once the PRAddrInfo handle is destroyed
andre@0: **                      by a call to PR_FreeAddrInfo().
andre@0: ***********************************************************************/
andre@0: NSPR_API(const char *) PR_GetCanonNameFromAddrInfo(
andre@0:     const PRAddrInfo *addrInfo);
andre@0: 
andre@0: /***********************************************************************
andre@0: ** FUNCTIONS: PR_ntohs, PR_ntohl, PR_ntohll, PR_htons, PR_htonl, PR_htonll
andre@0: **
andre@0: ** DESCRIPTION: API entries for the common byte ordering routines.
andre@0: **
andre@0: **      PR_ntohs        16 bit conversion from network to host
andre@0: **      PR_ntohl        32 bit conversion from network to host
andre@0: **      PR_ntohll       64 bit conversion from network to host
andre@0: **      PR_htons        16 bit conversion from host to network
andre@0: **      PR_htonl        32 bit conversion from host to network
andre@0: **      PR_ntonll       64 bit conversion from host to network
andre@0: **
andre@0: ***********************************************************************/
andre@0: NSPR_API(PRUint16) PR_ntohs(PRUint16);
andre@0: NSPR_API(PRUint32) PR_ntohl(PRUint32);
andre@0: NSPR_API(PRUint64) PR_ntohll(PRUint64);
andre@0: NSPR_API(PRUint16) PR_htons(PRUint16);
andre@0: NSPR_API(PRUint32) PR_htonl(PRUint32);
andre@0: NSPR_API(PRUint64) PR_htonll(PRUint64);
andre@0: 
andre@0: PR_END_EXTERN_C
andre@0: 
andre@0: #endif /* prnetdb_h___ */