prnetdb.h (19671B)
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___ */