/gecko_api/include/prnetdb.h
C++ Header | 499 lines | 89 code | 34 blank | 376 comment | 5 complexity | a119650cd64db1f80d817160e7aae467 MD5 | raw file
1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2/* ***** BEGIN LICENSE BLOCK ***** 3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 * 5 * The contents of this file are subject to the Mozilla Public License Version 6 * 1.1 (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * http://www.mozilla.org/MPL/ 9 * 10 * Software distributed under the License is distributed on an "AS IS" basis, 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 * for the specific language governing rights and limitations under the 13 * License. 14 * 15 * The Original Code is the Netscape Portable Runtime (NSPR). 16 * 17 * The Initial Developer of the Original Code is 18 * Netscape Communications Corporation. 19 * Portions created by the Initial Developer are Copyright (C) 1998-2000 20 * the Initial Developer. All Rights Reserved. 21 * 22 * Contributor(s): 23 * 24 * Alternatively, the contents of this file may be used under the terms of 25 * either the GNU General Public License Version 2 or later (the "GPL"), or 26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 27 * in which case the provisions of the GPL or the LGPL are applicable instead 28 * of those above. If you wish to allow use of your version of this file only 29 * under the terms of either the GPL or the LGPL, and not to allow others to 30 * use your version of this file under the terms of the MPL, indicate your 31 * decision by deleting the provisions above and replace them with the notice 32 * and other provisions required by the GPL or the LGPL. If you do not delete 33 * the provisions above, a recipient may use your version of this file under 34 * the terms of any one of the MPL, the GPL or the LGPL. 35 * 36 * ***** END LICENSE BLOCK ***** */ 37 38#ifndef prnetdb_h___ 39#define prnetdb_h___ 40 41#include "prtypes.h" 42#include "prio.h" 43 44PR_BEGIN_EXTERN_C 45 46 47/* 48 ********************************************************************* 49 * Translate an Internet address to/from a character string 50 ********************************************************************* 51 */ 52NSPR_API(PRStatus) PR_StringToNetAddr( 53 const char *string, PRNetAddr *addr); 54 55NSPR_API(PRStatus) PR_NetAddrToString( 56 const PRNetAddr *addr, char *string, PRUint32 size); 57 58/* 59** Structures returned by network data base library. All addresses are 60** supplied in host order, and returned in network order (suitable for 61** use in system calls). 62*/ 63/* 64** Beware that WINSOCK.H defines h_addrtype and h_length as short. 65** Client code does direct struct copies of hostent to PRHostEnt and 66** hence the ifdef. 67*/ 68typedef struct PRHostEnt { 69 char *h_name; /* official name of host */ 70 char **h_aliases; /* alias list */ 71#if defined(WIN32) || defined(WIN16) 72 PRInt16 h_addrtype; /* host address type */ 73 PRInt16 h_length; /* length of address */ 74#else 75 PRInt32 h_addrtype; /* host address type */ 76 PRInt32 h_length; /* length of address */ 77#endif 78 char **h_addr_list; /* list of addresses from name server */ 79} PRHostEnt; 80 81/* A safe size to use that will mostly work... */ 82#if (defined(AIX) && defined(_THREAD_SAFE)) || defined(OSF1) 83#define PR_NETDB_BUF_SIZE sizeof(struct protoent_data) 84#else 85#define PR_NETDB_BUF_SIZE 1024 86#endif 87 88/*********************************************************************** 89** FUNCTION: 90** DESCRIPTION: PR_GetHostByName() 91** Lookup a host by name. 92** 93** INPUTS: 94** char *hostname Character string defining the host name of interest 95** char *buf A scratch buffer for the runtime to return result. 96** This buffer is allocated by the caller. 97** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to 98** use is PR_NETDB_BUF_SIZE. 99** OUTPUTS: 100** PRHostEnt *hostentry 101** This structure is filled in by the runtime if 102** the function returns PR_SUCCESS. This structure 103** is allocated by the caller. 104** RETURN: 105** PRStatus PR_SUCCESS if the lookup succeeds. If it fails 106** the result will be PR_FAILURE and the reason 107** for the failure can be retrieved by PR_GetError(). 108***********************************************************************/ 109NSPR_API(PRStatus) PR_GetHostByName( 110 const char *hostname, char *buf, PRIntn bufsize, PRHostEnt *hostentry); 111 112/*********************************************************************** 113** FUNCTION: 114** DESCRIPTION: PR_GetIPNodeByName() 115** Lookup a host by name. Equivalent to getipnodebyname(AI_DEFAULT) 116** of RFC 2553. 117** 118** INPUTS: 119** char *hostname Character string defining the host name of interest 120** PRUint16 af Address family (either PR_AF_INET or PR_AF_INET6) 121** PRIntn flags Specifies the types of addresses that are searched 122** for and the types of addresses that are returned. 123** The only supported flag is PR_AI_DEFAULT. 124** char *buf A scratch buffer for the runtime to return result. 125** This buffer is allocated by the caller. 126** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to 127** use is PR_NETDB_BUF_SIZE. 128** OUTPUTS: 129** PRHostEnt *hostentry 130** This structure is filled in by the runtime if 131** the function returns PR_SUCCESS. This structure 132** is allocated by the caller. 133** RETURN: 134** PRStatus PR_SUCCESS if the lookup succeeds. If it fails 135** the result will be PR_FAILURE and the reason 136** for the failure can be retrieved by PR_GetError(). 137***********************************************************************/ 138 139 140#define PR_AI_ALL 0x08 141#define PR_AI_V4MAPPED 0x10 142#define PR_AI_ADDRCONFIG 0x20 143#define PR_AI_NOCANONNAME 0x8000 144#define PR_AI_DEFAULT (PR_AI_V4MAPPED | PR_AI_ADDRCONFIG) 145 146NSPR_API(PRStatus) PR_GetIPNodeByName( 147 const char *hostname, 148 PRUint16 af, 149 PRIntn flags, 150 char *buf, 151 PRIntn bufsize, 152 PRHostEnt *hostentry); 153 154/*********************************************************************** 155** FUNCTION: 156** DESCRIPTION: PR_GetHostByAddr() 157** Lookup a host entry by its network address. 158** 159** INPUTS: 160** char *hostaddr IP address of host in question 161** char *buf A scratch buffer for the runtime to return result. 162** This buffer is allocated by the caller. 163** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to 164** use is PR_NETDB_BUF_SIZE. 165** OUTPUTS: 166** PRHostEnt *hostentry 167** This structure is filled in by the runtime if 168** the function returns PR_SUCCESS. This structure 169** is allocated by the caller. 170** RETURN: 171** PRStatus PR_SUCCESS if the lookup succeeds. If it fails 172** the result will be PR_FAILURE and the reason 173** for the failure can be retrieved by PR_GetError(). 174***********************************************************************/ 175NSPR_API(PRStatus) PR_GetHostByAddr( 176 const PRNetAddr *hostaddr, char *buf, PRIntn bufsize, PRHostEnt *hostentry); 177 178/*********************************************************************** 179** FUNCTION: PR_EnumerateHostEnt() 180** DESCRIPTION: 181** A stateless enumerator over a PRHostEnt structure acquired from 182** PR_GetHostByName() PR_GetHostByAddr() to evaluate the possible 183** network addresses. 184** 185** INPUTS: 186** PRIntn enumIndex Index of the enumeration. The enumeration starts 187** and ends with a value of zero. 188** 189** PRHostEnt *hostEnt A pointer to a host entry struct that was 190** previously returned by PR_GetHostByName() or 191** PR_GetHostByAddr(). 192** 193** PRUint16 port The port number to be assigned as part of the 194** PRNetAddr. 195** 196** OUTPUTS: 197** PRNetAddr *address A pointer to an address structure that will be 198** filled in by the call to the enumeration if the 199** result of the call is greater than zero. 200** 201** RETURN: 202** PRIntn The value that should be used for the next call 203** of the enumerator ('enumIndex'). The enumeration 204** is ended if this value is returned zero. 205** If a value of -1 is returned, the enumeration 206** has failed. The reason for the failure can be 207** retrieved by calling PR_GetError(). 208***********************************************************************/ 209NSPR_API(PRIntn) PR_EnumerateHostEnt( 210 PRIntn enumIndex, const PRHostEnt *hostEnt, PRUint16 port, PRNetAddr *address); 211 212/*********************************************************************** 213** FUNCTION: PR_InitializeNetAddr(), 214** DESCRIPTION: 215** Initialize the fields of a PRNetAddr, assigning well known values as 216** appropriate. 217** 218** INPUTS 219** PRNetAddrValue val The value to be assigned to the IP Address portion 220** of the network address. This can only specify the 221** special well known values that are equivalent to 222** INADDR_ANY and INADDR_LOOPBACK. 223** 224** PRUint16 port The port number to be assigned in the structure. 225** 226** OUTPUTS: 227** PRNetAddr *addr The address to be manipulated. 228** 229** RETURN: 230** PRStatus To indicate success or failure. If the latter, the 231** reason for the failure can be retrieved by calling 232** PR_GetError(); 233***********************************************************************/ 234typedef enum PRNetAddrValue 235{ 236 PR_IpAddrNull, /* do NOT overwrite the IP address */ 237 PR_IpAddrAny, /* assign logical INADDR_ANY to IP address */ 238 PR_IpAddrLoopback, /* assign logical INADDR_LOOPBACK */ 239 PR_IpAddrV4Mapped /* IPv4 mapped address */ 240} PRNetAddrValue; 241 242NSPR_API(PRStatus) PR_InitializeNetAddr( 243 PRNetAddrValue val, PRUint16 port, PRNetAddr *addr); 244 245/*********************************************************************** 246** FUNCTION: PR_SetNetAddr(), 247** DESCRIPTION: 248** Set the fields of a PRNetAddr, assigning well known values as 249** appropriate. This function is similar to PR_InitializeNetAddr 250** but differs in that the address family is specified. 251** 252** INPUTS 253** PRNetAddrValue val The value to be assigned to the IP Address portion 254** of the network address. This can only specify the 255** special well known values that are equivalent to 256** INADDR_ANY and INADDR_LOOPBACK. 257** 258** PRUint16 af The address family (either PR_AF_INET or PR_AF_INET6) 259** 260** PRUint16 port The port number to be assigned in the structure. 261** 262** OUTPUTS: 263** PRNetAddr *addr The address to be manipulated. 264** 265** RETURN: 266** PRStatus To indicate success or failure. If the latter, the 267** reason for the failure can be retrieved by calling 268** PR_GetError(); 269***********************************************************************/ 270NSPR_API(PRStatus) PR_SetNetAddr( 271 PRNetAddrValue val, PRUint16 af, PRUint16 port, PRNetAddr *addr); 272 273/*********************************************************************** 274** FUNCTION: 275** DESCRIPTION: PR_IsNetAddrType() 276** Determine if the network address is of the specified type. 277** 278** INPUTS: 279** const PRNetAddr *addr A network address. 280** PRNetAddrValue The type of network address 281** 282** RETURN: 283** PRBool PR_TRUE if the network address is of the 284** specified type, else PR_FALSE. 285***********************************************************************/ 286NSPR_API(PRBool) PR_IsNetAddrType(const PRNetAddr *addr, PRNetAddrValue val); 287 288/*********************************************************************** 289** FUNCTION: 290** DESCRIPTION: PR_ConvertIPv4AddrToIPv6() 291** Convert an IPv4 addr to an (IPv4-mapped) IPv6 addr 292** 293** INPUTS: 294** PRUint32 v4addr IPv4 address 295** 296** OUTPUTS: 297** PRIPv6Addr *v6addr The converted IPv6 address 298** 299** RETURN: 300** void 301** 302***********************************************************************/ 303NSPR_API(void) PR_ConvertIPv4AddrToIPv6(PRUint32 v4addr, PRIPv6Addr *v6addr); 304 305/*********************************************************************** 306** MACRO: 307** DESCRIPTION: PR_NetAddrFamily() 308** Get the 'family' field of a PRNetAddr union. 309** 310** INPUTS: 311** const PRNetAddr *addr A network address. 312** 313** RETURN: 314** PRUint16 The 'family' field of 'addr'. 315***********************************************************************/ 316#define PR_NetAddrFamily(addr) ((addr)->raw.family) 317 318/*********************************************************************** 319** MACRO: 320** DESCRIPTION: PR_NetAddrInetPort() 321** Get the 'port' field of a PRNetAddr union. 322** 323** INPUTS: 324** const PRNetAddr *addr A network address. 325** 326** RETURN: 327** PRUint16 The 'port' field of 'addr'. 328***********************************************************************/ 329#define PR_NetAddrInetPort(addr) \ 330 ((addr)->raw.family == PR_AF_INET6 ? (addr)->ipv6.port : (addr)->inet.port) 331 332/*********************************************************************** 333** FUNCTION: 334** DESCRIPTION: PR_GetProtoByName() 335** Lookup a protocol entry based on protocol's name 336** 337** INPUTS: 338** char *protocolname Character string of the protocol's name. 339** char *buf A scratch buffer for the runtime to return result. 340** This buffer is allocated by the caller. 341** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to 342** use is PR_NETDB_BUF_SIZE. 343** OUTPUTS: 344** PRHostEnt *PRProtoEnt 345** This structure is filled in by the runtime if 346** the function returns PR_SUCCESS. This structure 347** is allocated by the caller. 348** RETURN: 349** PRStatus PR_SUCCESS if the lookup succeeds. If it fails 350** the result will be PR_FAILURE and the reason 351** for the failure can be retrieved by PR_GetError(). 352***********************************************************************/ 353 354typedef struct PRProtoEnt { 355 char *p_name; /* official protocol name */ 356 char **p_aliases; /* alias list */ 357#if defined(WIN32) || defined(WIN16) 358 PRInt16 p_num; /* protocol # */ 359#else 360 PRInt32 p_num; /* protocol # */ 361#endif 362} PRProtoEnt; 363 364NSPR_API(PRStatus) PR_GetProtoByName( 365 const char* protocolname, char* buffer, PRInt32 bufsize, PRProtoEnt* result); 366 367/*********************************************************************** 368** FUNCTION: 369** DESCRIPTION: PR_GetProtoByNumber() 370** Lookup a protocol entry based on protocol's number 371** 372** INPUTS: 373** PRInt32 protocolnumber 374** Number assigned to the protocol. 375** char *buf A scratch buffer for the runtime to return result. 376** This buffer is allocated by the caller. 377** PRIntn bufsize Number of bytes in 'buf'. A recommnded value to 378** use is PR_NETDB_BUF_SIZE. 379** OUTPUTS: 380** PRHostEnt *PRProtoEnt 381** This structure is filled in by the runtime if 382** the function returns PR_SUCCESS. This structure 383** is allocated by the caller. 384** RETURN: 385** PRStatus PR_SUCCESS if the lookup succeeds. If it fails 386** the result will be PR_FAILURE and the reason 387** for the failure can be retrieved by PR_GetError(). 388***********************************************************************/ 389NSPR_API(PRStatus) PR_GetProtoByNumber( 390 PRInt32 protocolnumber, char* buffer, PRInt32 bufsize, PRProtoEnt* result); 391 392/*********************************************************************** 393** FUNCTION: 394** DESCRIPTION: PR_GetAddrInfoByName() 395** Lookup a host by name. Equivalent to getaddrinfo(host, NULL, ...) of 396** RFC 3493. 397** 398** INPUTS: 399** char *hostname Character string defining the host name of interest 400** PRUint16 af May be PR_AF_UNSPEC or PR_AF_INET. 401** PRIntn flags May be either PR_AI_ADDRCONFIG or 402** PR_AI_ADDRCONFIG | PR_AI_NOCANONNAME. Include 403** PR_AI_NOCANONNAME to suppress the determination of 404** the canonical name corresponding to hostname. 405** RETURN: 406** PRAddrInfo* Handle to a data structure containing the results 407** of the host lookup. Use PR_EnumerateAddrInfo to 408** inspect the PRNetAddr values stored in this object. 409** When no longer needed, this handle must be destroyed 410** with a call to PR_FreeAddrInfo. If a lookup error 411** occurs, then NULL will be returned. 412***********************************************************************/ 413typedef struct PRAddrInfo PRAddrInfo; 414 415NSPR_API(PRAddrInfo*) PR_GetAddrInfoByName( 416 const char *hostname, PRUint16 af, PRIntn flags); 417 418/*********************************************************************** 419** FUNCTION: 420** DESCRIPTION: PR_FreeAddrInfo() 421** Destroy the PRAddrInfo handle allocated by PR_GetAddrInfoByName(). 422** 423** INPUTS: 424** PRAddrInfo *addrInfo 425** The handle resulting from a successful call to 426** PR_GetAddrInfoByName(). 427** RETURN: 428** void 429***********************************************************************/ 430NSPR_API(void) PR_FreeAddrInfo(PRAddrInfo *addrInfo); 431 432/*********************************************************************** 433** FUNCTION: 434** DESCRIPTION: PR_EnumerateAddrInfo() 435** A stateless enumerator over a PRAddrInfo handle acquired from 436** PR_GetAddrInfoByName() to inspect the possible network addresses. 437** 438** INPUTS: 439** void *enumPtr Index pointer of the enumeration. The enumeration 440** starts and ends with a value of NULL. 441** PRAddrInfo *addrInfo 442** The PRAddrInfo handle returned by a successful 443** call to PR_GetAddrInfoByName(). 444** PRUint16 port The port number to be assigned as part of the 445** PRNetAddr. 446** OUTPUTS: 447** PRNetAddr *result A pointer to an address structure that will be 448** filled in by the call to the enumeration if the 449** result of the call is greater than zero. 450** RETURN: 451** void* The value that should be used for the next call 452** of the enumerator ('enumPtr'). The enumeration 453** is ended if this value is returned NULL. 454***********************************************************************/ 455NSPR_API(void *) PR_EnumerateAddrInfo( 456 void *enumPtr, const PRAddrInfo *addrInfo, PRUint16 port, PRNetAddr *result); 457 458/*********************************************************************** 459** FUNCTION: 460** DESCRIPTION: PR_GetCanonNameFromAddrInfo() 461** Extracts the canonical name of the hostname passed to 462** PR_GetAddrInfoByName(). 463** 464** INPUTS: 465** PRAddrInfo *addrInfo 466** The PRAddrInfo handle returned by a successful 467** call to PR_GetAddrInfoByName(). 468** RETURN: 469** const char * A const pointer to the canonical hostname stored 470** in the given PRAddrInfo handle. This pointer is 471** invalidated once the PRAddrInfo handle is destroyed 472** by a call to PR_FreeAddrInfo(). 473***********************************************************************/ 474NSPR_API(const char *) PR_GetCanonNameFromAddrInfo( 475 const PRAddrInfo *addrInfo); 476 477/*********************************************************************** 478** FUNCTIONS: PR_ntohs, PR_ntohl, PR_ntohll, PR_htons, PR_htonl, PR_htonll 479** 480** DESCRIPTION: API entries for the common byte ordering routines. 481** 482** PR_ntohs 16 bit conversion from network to host 483** PR_ntohl 32 bit conversion from network to host 484** PR_ntohll 64 bit conversion from network to host 485** PR_htons 16 bit conversion from host to network 486** PR_htonl 32 bit conversion from host to network 487** PR_ntonll 64 bit conversion from host to network 488** 489***********************************************************************/ 490NSPR_API(PRUint16) PR_ntohs(PRUint16); 491NSPR_API(PRUint32) PR_ntohl(PRUint32); 492NSPR_API(PRUint64) PR_ntohll(PRUint64); 493NSPR_API(PRUint16) PR_htons(PRUint16); 494NSPR_API(PRUint32) PR_htonl(PRUint32); 495NSPR_API(PRUint64) PR_htonll(PRUint64); 496 497PR_END_EXTERN_C 498 499#endif /* prnetdb_h___ */