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___ */ 493
