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