1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prnetdb.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,467 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prnetdb_h___
1.10 +#define prnetdb_h___
1.11 +
1.12 +#include "prtypes.h"
1.13 +#include "prio.h"
1.14 +
1.15 +PR_BEGIN_EXTERN_C
1.16 +
1.17 +
1.18 +/*
1.19 + *********************************************************************
1.20 + * Translate an Internet address to/from a character string
1.21 + *********************************************************************
1.22 + */
1.23 +NSPR_API(PRStatus) PR_StringToNetAddr(
1.24 + const char *string, PRNetAddr *addr);
1.25 +
1.26 +NSPR_API(PRStatus) PR_NetAddrToString(
1.27 + const PRNetAddr *addr, char *string, PRUint32 size);
1.28 +
1.29 +/*
1.30 +** Structures returned by network data base library. All addresses are
1.31 +** supplied in host order, and returned in network order (suitable for
1.32 +** use in system calls).
1.33 +*/
1.34 +/*
1.35 +** Beware that WINSOCK.H defines h_addrtype and h_length as short.
1.36 +** Client code does direct struct copies of hostent to PRHostEnt and
1.37 +** hence the ifdef.
1.38 +*/
1.39 +typedef struct PRHostEnt {
1.40 + char *h_name; /* official name of host */
1.41 + char **h_aliases; /* alias list */
1.42 +#ifdef WIN32
1.43 + PRInt16 h_addrtype; /* host address type */
1.44 + PRInt16 h_length; /* length of address */
1.45 +#else
1.46 + PRInt32 h_addrtype; /* host address type */
1.47 + PRInt32 h_length; /* length of address */
1.48 +#endif
1.49 + char **h_addr_list; /* list of addresses from name server */
1.50 +} PRHostEnt;
1.51 +
1.52 +/* A safe size to use that will mostly work... */
1.53 +#if (defined(AIX) && defined(_THREAD_SAFE)) || defined(OSF1)
1.54 +#define PR_NETDB_BUF_SIZE sizeof(struct protoent_data)
1.55 +#else
1.56 +#define PR_NETDB_BUF_SIZE 1024
1.57 +#endif
1.58 +
1.59 +/***********************************************************************
1.60 +** FUNCTION:
1.61 +** DESCRIPTION: PR_GetHostByName()
1.62 +** Lookup a host by name.
1.63 +**
1.64 +** INPUTS:
1.65 +** char *hostname Character string defining the host name of interest
1.66 +** char *buf A scratch buffer for the runtime to return result.
1.67 +** This buffer is allocated by the caller.
1.68 +** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
1.69 +** use is PR_NETDB_BUF_SIZE.
1.70 +** OUTPUTS:
1.71 +** PRHostEnt *hostentry
1.72 +** This structure is filled in by the runtime if
1.73 +** the function returns PR_SUCCESS. This structure
1.74 +** is allocated by the caller.
1.75 +** RETURN:
1.76 +** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
1.77 +** the result will be PR_FAILURE and the reason
1.78 +** for the failure can be retrieved by PR_GetError().
1.79 +***********************************************************************/
1.80 +NSPR_API(PRStatus) PR_GetHostByName(
1.81 + const char *hostname, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
1.82 +
1.83 +/***********************************************************************
1.84 +** FUNCTION:
1.85 +** DESCRIPTION: PR_GetIPNodeByName()
1.86 +** Lookup a host by name. Equivalent to getipnodebyname(AI_DEFAULT)
1.87 +** of RFC 2553.
1.88 +**
1.89 +** INPUTS:
1.90 +** char *hostname Character string defining the host name of interest
1.91 +** PRUint16 af Address family (either PR_AF_INET or PR_AF_INET6)
1.92 +** PRIntn flags Specifies the types of addresses that are searched
1.93 +** for and the types of addresses that are returned.
1.94 +** The only supported flag is PR_AI_DEFAULT.
1.95 +** char *buf A scratch buffer for the runtime to return result.
1.96 +** This buffer is allocated by the caller.
1.97 +** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
1.98 +** use is PR_NETDB_BUF_SIZE.
1.99 +** OUTPUTS:
1.100 +** PRHostEnt *hostentry
1.101 +** This structure is filled in by the runtime if
1.102 +** the function returns PR_SUCCESS. This structure
1.103 +** is allocated by the caller.
1.104 +** RETURN:
1.105 +** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
1.106 +** the result will be PR_FAILURE and the reason
1.107 +** for the failure can be retrieved by PR_GetError().
1.108 +***********************************************************************/
1.109 +
1.110 +
1.111 +#define PR_AI_ALL 0x08
1.112 +#define PR_AI_V4MAPPED 0x10
1.113 +#define PR_AI_ADDRCONFIG 0x20
1.114 +#define PR_AI_NOCANONNAME 0x8000
1.115 +#define PR_AI_DEFAULT (PR_AI_V4MAPPED | PR_AI_ADDRCONFIG)
1.116 +
1.117 +NSPR_API(PRStatus) PR_GetIPNodeByName(
1.118 + const char *hostname,
1.119 + PRUint16 af,
1.120 + PRIntn flags,
1.121 + char *buf,
1.122 + PRIntn bufsize,
1.123 + PRHostEnt *hostentry);
1.124 +
1.125 +/***********************************************************************
1.126 +** FUNCTION:
1.127 +** DESCRIPTION: PR_GetHostByAddr()
1.128 +** Lookup a host entry by its network address.
1.129 +**
1.130 +** INPUTS:
1.131 +** char *hostaddr IP address of host in question
1.132 +** char *buf A scratch buffer for the runtime to return result.
1.133 +** This buffer is allocated by the caller.
1.134 +** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
1.135 +** use is PR_NETDB_BUF_SIZE.
1.136 +** OUTPUTS:
1.137 +** PRHostEnt *hostentry
1.138 +** This structure is filled in by the runtime if
1.139 +** the function returns PR_SUCCESS. This structure
1.140 +** is allocated by the caller.
1.141 +** RETURN:
1.142 +** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
1.143 +** the result will be PR_FAILURE and the reason
1.144 +** for the failure can be retrieved by PR_GetError().
1.145 +***********************************************************************/
1.146 +NSPR_API(PRStatus) PR_GetHostByAddr(
1.147 + const PRNetAddr *hostaddr, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
1.148 +
1.149 +/***********************************************************************
1.150 +** FUNCTION: PR_EnumerateHostEnt()
1.151 +** DESCRIPTION:
1.152 +** A stateless enumerator over a PRHostEnt structure acquired from
1.153 +** PR_GetHostByName() PR_GetHostByAddr() to evaluate the possible
1.154 +** network addresses.
1.155 +**
1.156 +** INPUTS:
1.157 +** PRIntn enumIndex Index of the enumeration. The enumeration starts
1.158 +** and ends with a value of zero.
1.159 +**
1.160 +** PRHostEnt *hostEnt A pointer to a host entry struct that was
1.161 +** previously returned by PR_GetHostByName() or
1.162 +** PR_GetHostByAddr().
1.163 +**
1.164 +** PRUint16 port The port number to be assigned as part of the
1.165 +** PRNetAddr.
1.166 +**
1.167 +** OUTPUTS:
1.168 +** PRNetAddr *address A pointer to an address structure that will be
1.169 +** filled in by the call to the enumeration if the
1.170 +** result of the call is greater than zero.
1.171 +**
1.172 +** RETURN:
1.173 +** PRIntn The value that should be used for the next call
1.174 +** of the enumerator ('enumIndex'). The enumeration
1.175 +** is ended if this value is returned zero.
1.176 +** If a value of -1 is returned, the enumeration
1.177 +** has failed. The reason for the failure can be
1.178 +** retrieved by calling PR_GetError().
1.179 +***********************************************************************/
1.180 +NSPR_API(PRIntn) PR_EnumerateHostEnt(
1.181 + PRIntn enumIndex, const PRHostEnt *hostEnt, PRUint16 port, PRNetAddr *address);
1.182 +
1.183 +/***********************************************************************
1.184 +** FUNCTION: PR_InitializeNetAddr(),
1.185 +** DESCRIPTION:
1.186 +** Initialize the fields of a PRNetAddr, assigning well known values as
1.187 +** appropriate.
1.188 +**
1.189 +** INPUTS
1.190 +** PRNetAddrValue val The value to be assigned to the IP Address portion
1.191 +** of the network address. This can only specify the
1.192 +** special well known values that are equivalent to
1.193 +** INADDR_ANY and INADDR_LOOPBACK.
1.194 +**
1.195 +** PRUint16 port The port number to be assigned in the structure.
1.196 +**
1.197 +** OUTPUTS:
1.198 +** PRNetAddr *addr The address to be manipulated.
1.199 +**
1.200 +** RETURN:
1.201 +** PRStatus To indicate success or failure. If the latter, the
1.202 +** reason for the failure can be retrieved by calling
1.203 +** PR_GetError();
1.204 +***********************************************************************/
1.205 +typedef enum PRNetAddrValue
1.206 +{
1.207 + PR_IpAddrNull, /* do NOT overwrite the IP address */
1.208 + PR_IpAddrAny, /* assign logical INADDR_ANY to IP address */
1.209 + PR_IpAddrLoopback, /* assign logical INADDR_LOOPBACK */
1.210 + PR_IpAddrV4Mapped /* IPv4 mapped address */
1.211 +} PRNetAddrValue;
1.212 +
1.213 +NSPR_API(PRStatus) PR_InitializeNetAddr(
1.214 + PRNetAddrValue val, PRUint16 port, PRNetAddr *addr);
1.215 +
1.216 +/***********************************************************************
1.217 +** FUNCTION: PR_SetNetAddr(),
1.218 +** DESCRIPTION:
1.219 +** Set the fields of a PRNetAddr, assigning well known values as
1.220 +** appropriate. This function is similar to PR_InitializeNetAddr
1.221 +** but differs in that the address family is specified.
1.222 +**
1.223 +** INPUTS
1.224 +** PRNetAddrValue val The value to be assigned to the IP Address portion
1.225 +** of the network address. This can only specify the
1.226 +** special well known values that are equivalent to
1.227 +** INADDR_ANY and INADDR_LOOPBACK.
1.228 +**
1.229 +** PRUint16 af The address family (either PR_AF_INET or PR_AF_INET6)
1.230 +**
1.231 +** PRUint16 port The port number to be assigned in the structure.
1.232 +**
1.233 +** OUTPUTS:
1.234 +** PRNetAddr *addr The address to be manipulated.
1.235 +**
1.236 +** RETURN:
1.237 +** PRStatus To indicate success or failure. If the latter, the
1.238 +** reason for the failure can be retrieved by calling
1.239 +** PR_GetError();
1.240 +***********************************************************************/
1.241 +NSPR_API(PRStatus) PR_SetNetAddr(
1.242 + PRNetAddrValue val, PRUint16 af, PRUint16 port, PRNetAddr *addr);
1.243 +
1.244 +/***********************************************************************
1.245 +** FUNCTION:
1.246 +** DESCRIPTION: PR_IsNetAddrType()
1.247 +** Determine if the network address is of the specified type.
1.248 +**
1.249 +** INPUTS:
1.250 +** const PRNetAddr *addr A network address.
1.251 +** PRNetAddrValue The type of network address
1.252 +**
1.253 +** RETURN:
1.254 +** PRBool PR_TRUE if the network address is of the
1.255 +** specified type, else PR_FALSE.
1.256 +***********************************************************************/
1.257 +NSPR_API(PRBool) PR_IsNetAddrType(const PRNetAddr *addr, PRNetAddrValue val);
1.258 +
1.259 +/***********************************************************************
1.260 +** FUNCTION:
1.261 +** DESCRIPTION: PR_ConvertIPv4AddrToIPv6()
1.262 +** Convert an IPv4 addr to an (IPv4-mapped) IPv6 addr
1.263 +**
1.264 +** INPUTS:
1.265 +** PRUint32 v4addr IPv4 address
1.266 +**
1.267 +** OUTPUTS:
1.268 +** PRIPv6Addr *v6addr The converted IPv6 address
1.269 +**
1.270 +** RETURN:
1.271 +** void
1.272 +**
1.273 +***********************************************************************/
1.274 +NSPR_API(void) PR_ConvertIPv4AddrToIPv6(PRUint32 v4addr, PRIPv6Addr *v6addr);
1.275 +
1.276 +/***********************************************************************
1.277 +** MACRO:
1.278 +** DESCRIPTION: PR_NetAddrFamily()
1.279 +** Get the 'family' field of a PRNetAddr union.
1.280 +**
1.281 +** INPUTS:
1.282 +** const PRNetAddr *addr A network address.
1.283 +**
1.284 +** RETURN:
1.285 +** PRUint16 The 'family' field of 'addr'.
1.286 +***********************************************************************/
1.287 +#define PR_NetAddrFamily(addr) ((addr)->raw.family)
1.288 +
1.289 +/***********************************************************************
1.290 +** MACRO:
1.291 +** DESCRIPTION: PR_NetAddrInetPort()
1.292 +** Get the 'port' field of a PRNetAddr union.
1.293 +**
1.294 +** INPUTS:
1.295 +** const PRNetAddr *addr A network address.
1.296 +**
1.297 +** RETURN:
1.298 +** PRUint16 The 'port' field of 'addr'.
1.299 +***********************************************************************/
1.300 +#define PR_NetAddrInetPort(addr) \
1.301 + ((addr)->raw.family == PR_AF_INET6 ? (addr)->ipv6.port : (addr)->inet.port)
1.302 +
1.303 +/***********************************************************************
1.304 +** FUNCTION:
1.305 +** DESCRIPTION: PR_GetProtoByName()
1.306 +** Lookup a protocol entry based on protocol's name
1.307 +**
1.308 +** INPUTS:
1.309 +** char *protocolname Character string of the protocol's name.
1.310 +** char *buf A scratch buffer for the runtime to return result.
1.311 +** This buffer is allocated by the caller.
1.312 +** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
1.313 +** use is PR_NETDB_BUF_SIZE.
1.314 +** OUTPUTS:
1.315 +** PRHostEnt *PRProtoEnt
1.316 +** This structure is filled in by the runtime if
1.317 +** the function returns PR_SUCCESS. This structure
1.318 +** is allocated by the caller.
1.319 +** RETURN:
1.320 +** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
1.321 +** the result will be PR_FAILURE and the reason
1.322 +** for the failure can be retrieved by PR_GetError().
1.323 +***********************************************************************/
1.324 +
1.325 +typedef struct PRProtoEnt {
1.326 + char *p_name; /* official protocol name */
1.327 + char **p_aliases; /* alias list */
1.328 +#ifdef WIN32
1.329 + PRInt16 p_num; /* protocol # */
1.330 +#else
1.331 + PRInt32 p_num; /* protocol # */
1.332 +#endif
1.333 +} PRProtoEnt;
1.334 +
1.335 +NSPR_API(PRStatus) PR_GetProtoByName(
1.336 + const char* protocolname, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
1.337 +
1.338 +/***********************************************************************
1.339 +** FUNCTION:
1.340 +** DESCRIPTION: PR_GetProtoByNumber()
1.341 +** Lookup a protocol entry based on protocol's number
1.342 +**
1.343 +** INPUTS:
1.344 +** PRInt32 protocolnumber
1.345 +** Number assigned to the protocol.
1.346 +** char *buf A scratch buffer for the runtime to return result.
1.347 +** This buffer is allocated by the caller.
1.348 +** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to
1.349 +** use is PR_NETDB_BUF_SIZE.
1.350 +** OUTPUTS:
1.351 +** PRHostEnt *PRProtoEnt
1.352 +** This structure is filled in by the runtime if
1.353 +** the function returns PR_SUCCESS. This structure
1.354 +** is allocated by the caller.
1.355 +** RETURN:
1.356 +** PRStatus PR_SUCCESS if the lookup succeeds. If it fails
1.357 +** the result will be PR_FAILURE and the reason
1.358 +** for the failure can be retrieved by PR_GetError().
1.359 +***********************************************************************/
1.360 +NSPR_API(PRStatus) PR_GetProtoByNumber(
1.361 + PRInt32 protocolnumber, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
1.362 +
1.363 +/***********************************************************************
1.364 +** FUNCTION:
1.365 +** DESCRIPTION: PR_GetAddrInfoByName()
1.366 +** Look up a host by name. Equivalent to getaddrinfo(host, NULL, ...) of
1.367 +** RFC 3493.
1.368 +**
1.369 +** INPUTS:
1.370 +** char *hostname Character string defining the host name of interest
1.371 +** PRUint16 af May be PR_AF_UNSPEC or PR_AF_INET.
1.372 +** PRIntn flags May be either PR_AI_ADDRCONFIG or
1.373 +** PR_AI_ADDRCONFIG | PR_AI_NOCANONNAME. Include
1.374 +** PR_AI_NOCANONNAME to suppress the determination of
1.375 +** the canonical name corresponding to hostname.
1.376 +** RETURN:
1.377 +** PRAddrInfo* Handle to a data structure containing the results
1.378 +** of the host lookup. Use PR_EnumerateAddrInfo to
1.379 +** inspect the PRNetAddr values stored in this object.
1.380 +** When no longer needed, this handle must be destroyed
1.381 +** with a call to PR_FreeAddrInfo. If a lookup error
1.382 +** occurs, then NULL will be returned.
1.383 +***********************************************************************/
1.384 +typedef struct PRAddrInfo PRAddrInfo;
1.385 +
1.386 +NSPR_API(PRAddrInfo*) PR_GetAddrInfoByName(
1.387 + const char *hostname, PRUint16 af, PRIntn flags);
1.388 +
1.389 +/***********************************************************************
1.390 +** FUNCTION:
1.391 +** DESCRIPTION: PR_FreeAddrInfo()
1.392 +** Destroy the PRAddrInfo handle allocated by PR_GetAddrInfoByName().
1.393 +**
1.394 +** INPUTS:
1.395 +** PRAddrInfo *addrInfo
1.396 +** The handle resulting from a successful call to
1.397 +** PR_GetAddrInfoByName().
1.398 +** RETURN:
1.399 +** void
1.400 +***********************************************************************/
1.401 +NSPR_API(void) PR_FreeAddrInfo(PRAddrInfo *addrInfo);
1.402 +
1.403 +/***********************************************************************
1.404 +** FUNCTION:
1.405 +** DESCRIPTION: PR_EnumerateAddrInfo()
1.406 +** A stateless enumerator over a PRAddrInfo handle acquired from
1.407 +** PR_GetAddrInfoByName() to inspect the possible network addresses.
1.408 +**
1.409 +** INPUTS:
1.410 +** void *enumPtr Index pointer of the enumeration. The enumeration
1.411 +** starts and ends with a value of NULL.
1.412 +** const PRAddrInfo *addrInfo
1.413 +** The PRAddrInfo handle returned by a successful
1.414 +** call to PR_GetAddrInfoByName().
1.415 +** PRUint16 port The port number to be assigned as part of the
1.416 +** PRNetAddr.
1.417 +** OUTPUTS:
1.418 +** PRNetAddr *result A pointer to an address structure that will be
1.419 +** filled in by the call to the enumeration if the
1.420 +** result of the call is not NULL.
1.421 +** RETURN:
1.422 +** void* The value that should be used for the next call
1.423 +** of the enumerator ('enumPtr'). The enumeration
1.424 +** is ended if this value is NULL.
1.425 +***********************************************************************/
1.426 +NSPR_API(void *) PR_EnumerateAddrInfo(
1.427 + void *enumPtr, const PRAddrInfo *addrInfo, PRUint16 port, PRNetAddr *result);
1.428 +
1.429 +/***********************************************************************
1.430 +** FUNCTION:
1.431 +** DESCRIPTION: PR_GetCanonNameFromAddrInfo()
1.432 +** Extracts the canonical name of the hostname passed to
1.433 +** PR_GetAddrInfoByName().
1.434 +**
1.435 +** INPUTS:
1.436 +** const PRAddrInfo *addrInfo
1.437 +** The PRAddrInfo handle returned by a successful
1.438 +** call to PR_GetAddrInfoByName().
1.439 +** RETURN:
1.440 +** const char * A const pointer to the canonical hostname stored
1.441 +** in the given PRAddrInfo handle. This pointer is
1.442 +** invalidated once the PRAddrInfo handle is destroyed
1.443 +** by a call to PR_FreeAddrInfo().
1.444 +***********************************************************************/
1.445 +NSPR_API(const char *) PR_GetCanonNameFromAddrInfo(
1.446 + const PRAddrInfo *addrInfo);
1.447 +
1.448 +/***********************************************************************
1.449 +** FUNCTIONS: PR_ntohs, PR_ntohl, PR_ntohll, PR_htons, PR_htonl, PR_htonll
1.450 +**
1.451 +** DESCRIPTION: API entries for the common byte ordering routines.
1.452 +**
1.453 +** PR_ntohs 16 bit conversion from network to host
1.454 +** PR_ntohl 32 bit conversion from network to host
1.455 +** PR_ntohll 64 bit conversion from network to host
1.456 +** PR_htons 16 bit conversion from host to network
1.457 +** PR_htonl 32 bit conversion from host to network
1.458 +** PR_ntonll 64 bit conversion from host to network
1.459 +**
1.460 +***********************************************************************/
1.461 +NSPR_API(PRUint16) PR_ntohs(PRUint16);
1.462 +NSPR_API(PRUint32) PR_ntohl(PRUint32);
1.463 +NSPR_API(PRUint64) PR_ntohll(PRUint64);
1.464 +NSPR_API(PRUint16) PR_htons(PRUint16);
1.465 +NSPR_API(PRUint32) PR_htonl(PRUint32);
1.466 +NSPR_API(PRUint64) PR_htonll(PRUint64);
1.467 +
1.468 +PR_END_EXTERN_C
1.469 +
1.470 +#endif /* prnetdb_h___ */
