Back to index

lightning-sunbird  0.9+nobinonly
prnetdb.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prnetdb_h___
00039 #define prnetdb_h___
00040 
00041 #include "prtypes.h"
00042 #include "prio.h"
00043 
00044 PR_BEGIN_EXTERN_C
00045 
00046 
00047 /*
00048  *********************************************************************
00049  *  Translate an Internet address to/from a character string
00050  *********************************************************************
00051  */
00052 NSPR_API(PRStatus) PR_StringToNetAddr(
00053     const char *string, PRNetAddr *addr);
00054 
00055 NSPR_API(PRStatus) PR_NetAddrToString(
00056     const PRNetAddr *addr, char *string, PRUint32 size);
00057 
00058 /*
00059 ** Structures returned by network data base library.  All addresses are
00060 ** supplied in host order, and returned in network order (suitable for
00061 ** use in system calls).
00062 */
00063 /*
00064 ** Beware that WINSOCK.H defines h_addrtype and h_length as short.
00065 ** Client code does direct struct copies of hostent to PRHostEnt and
00066 ** hence the ifdef.
00067 */
00068 typedef struct PRHostEnt {
00069     char *h_name;       /* official name of host */
00070     char **h_aliases;   /* alias list */
00071 #if defined(WIN32) || defined(WIN16)
00072     PRInt16 h_addrtype; /* host address type */
00073     PRInt16 h_length;   /* length of address */
00074 #else
00075     PRInt32 h_addrtype; /* host address type */
00076     PRInt32 h_length;   /* length of address */
00077 #endif
00078     char **h_addr_list; /* list of addresses from name server */
00079 } PRHostEnt;
00080 
00081 /* A safe size to use that will mostly work... */
00082 #if (defined(AIX) && defined(_THREAD_SAFE)) || defined(OSF1)
00083 #define PR_NETDB_BUF_SIZE sizeof(struct protoent_data)
00084 #else
00085 #define PR_NETDB_BUF_SIZE 1024
00086 #endif
00087 
00088 /***********************************************************************
00089 ** FUNCTION:  
00090 ** DESCRIPTION:      PR_GetHostByName()
00091 ** Lookup a host by name.
00092 **
00093 ** INPUTS:
00094 **  char *hostname      Character string defining the host name of interest
00095 **  char *buf           A scratch buffer for the runtime to return result.
00096 **                      This buffer is allocated by the caller.
00097 **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
00098 **                      use is PR_NETDB_BUF_SIZE.
00099 ** OUTPUTS:
00100 **  PRHostEnt *hostentry
00101 **                      This structure is filled in by the runtime if
00102 **                      the function returns PR_SUCCESS. This structure
00103 **                      is allocated by the caller.
00104 ** RETURN:
00105 **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
00106 **                      the result will be PR_FAILURE and the reason
00107 **                      for the failure can be retrieved by PR_GetError().
00108 ***********************************************************************/
00109 NSPR_API(PRStatus) PR_GetHostByName(
00110     const char *hostname, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
00111 
00112 /***********************************************************************
00113 ** FUNCTION:  
00114 ** DESCRIPTION:      PR_GetIPNodeByName()
00115 ** Lookup a host by name. Equivalent to getipnodebyname(AI_DEFAULT)
00116 ** of RFC 2553.
00117 **
00118 ** INPUTS:
00119 **  char *hostname      Character string defining the host name of interest
00120 **  PRUint16 af         Address family (either PR_AF_INET or PR_AF_INET6)
00121 **  PRIntn flags        Specifies the types of addresses that are searched
00122 **                      for and the types of addresses that are returned.
00123 **                      The only supported flag is PR_AI_DEFAULT.
00124 **  char *buf           A scratch buffer for the runtime to return result.
00125 **                      This buffer is allocated by the caller.
00126 **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
00127 **                      use is PR_NETDB_BUF_SIZE.
00128 ** OUTPUTS:
00129 **  PRHostEnt *hostentry
00130 **                      This structure is filled in by the runtime if
00131 **                      the function returns PR_SUCCESS. This structure
00132 **                      is allocated by the caller.
00133 ** RETURN:
00134 **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
00135 **                      the result will be PR_FAILURE and the reason
00136 **                      for the failure can be retrieved by PR_GetError().
00137 ***********************************************************************/
00138 
00139 
00140 #define PR_AI_ALL         0x08
00141 #define PR_AI_V4MAPPED    0x10
00142 #define PR_AI_ADDRCONFIG  0x20
00143 #define PR_AI_NOCANONNAME 0x8000
00144 #define PR_AI_DEFAULT     (PR_AI_V4MAPPED | PR_AI_ADDRCONFIG)
00145 
00146 NSPR_API(PRStatus) PR_GetIPNodeByName(
00147     const char *hostname,
00148     PRUint16 af,
00149     PRIntn flags,
00150     char *buf,
00151     PRIntn bufsize,
00152     PRHostEnt *hostentry);
00153 
00154 /***********************************************************************
00155 ** FUNCTION:  
00156 ** DESCRIPTION:      PR_GetHostByAddr()
00157 ** Lookup a host entry by its network address.
00158 **
00159 ** INPUTS:
00160 **  char *hostaddr      IP address of host in question
00161 **  char *buf           A scratch buffer for the runtime to return result.
00162 **                      This buffer is allocated by the caller.
00163 **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
00164 **                      use is PR_NETDB_BUF_SIZE.
00165 ** OUTPUTS:
00166 **  PRHostEnt *hostentry
00167 **                      This structure is filled in by the runtime if
00168 **                      the function returns PR_SUCCESS. This structure
00169 **                      is allocated by the caller.
00170 ** RETURN:
00171 **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
00172 **                      the result will be PR_FAILURE and the reason
00173 **                      for the failure can be retrieved by PR_GetError().
00174 ***********************************************************************/
00175 NSPR_API(PRStatus) PR_GetHostByAddr(
00176     const PRNetAddr *hostaddr, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
00177 
00178 /***********************************************************************
00179 ** FUNCTION:  PR_EnumerateHostEnt()       
00180 ** DESCRIPTION:
00181 **  A stateless enumerator over a PRHostEnt structure acquired from
00182 **  PR_GetHostByName() PR_GetHostByAddr() to evaluate the possible
00183 **  network addresses.
00184 **
00185 ** INPUTS:
00186 **  PRIntn  enumIndex   Index of the enumeration. The enumeration starts
00187 **                      and ends with a value of zero.
00188 **
00189 **  PRHostEnt *hostEnt  A pointer to a host entry struct that was
00190 **                      previously returned by PR_GetHostByName() or
00191 **                      PR_GetHostByAddr().
00192 **
00193 **  PRUint16 port       The port number to be assigned as part of the
00194 **                      PRNetAddr.
00195 **
00196 ** OUTPUTS:
00197 **  PRNetAddr *address  A pointer to an address structure that will be
00198 **                      filled in by the call to the enumeration if the
00199 **                      result of the call is greater than zero.
00200 **
00201 ** RETURN:
00202 **  PRIntn              The value that should be used for the next call
00203 **                      of the enumerator ('enumIndex'). The enumeration
00204 **                      is ended if this value is returned zero.
00205 **                      If a value of -1 is returned, the enumeration
00206 **                      has failed. The reason for the failure can be
00207 **                      retrieved by calling PR_GetError().
00208 ***********************************************************************/
00209 NSPR_API(PRIntn) PR_EnumerateHostEnt(
00210     PRIntn enumIndex, const PRHostEnt *hostEnt, PRUint16 port, PRNetAddr *address);
00211 
00212 /***********************************************************************
00213 ** FUNCTION: PR_InitializeNetAddr(), 
00214 ** DESCRIPTION:
00215 **  Initialize the fields of a PRNetAddr, assigning well known values as
00216 **  appropriate.
00217 **
00218 ** INPUTS
00219 **  PRNetAddrValue val  The value to be assigned to the IP Address portion
00220 **                      of the network address. This can only specify the
00221 **                      special well known values that are equivalent to
00222 **                      INADDR_ANY and INADDR_LOOPBACK.
00223 **
00224 **  PRUint16 port       The port number to be assigned in the structure.
00225 **
00226 ** OUTPUTS:
00227 **  PRNetAddr *addr     The address to be manipulated.
00228 **
00229 ** RETURN:
00230 **  PRStatus            To indicate success or failure. If the latter, the
00231 **                      reason for the failure can be retrieved by calling
00232 **                      PR_GetError();
00233 ***********************************************************************/
00234 typedef enum PRNetAddrValue
00235 {
00236     PR_IpAddrNull,      /* do NOT overwrite the IP address */
00237     PR_IpAddrAny,       /* assign logical INADDR_ANY to IP address */
00238     PR_IpAddrLoopback,  /* assign logical INADDR_LOOPBACK  */
00239     PR_IpAddrV4Mapped   /* IPv4 mapped address */
00240 } PRNetAddrValue;
00241 
00242 NSPR_API(PRStatus) PR_InitializeNetAddr(
00243     PRNetAddrValue val, PRUint16 port, PRNetAddr *addr);
00244 
00245 /***********************************************************************
00246 ** FUNCTION: PR_SetNetAddr(), 
00247 ** DESCRIPTION:
00248 **  Set the fields of a PRNetAddr, assigning well known values as
00249 **  appropriate. This function is similar to PR_InitializeNetAddr
00250 **  but differs in that the address family is specified.
00251 **
00252 ** INPUTS
00253 **  PRNetAddrValue val  The value to be assigned to the IP Address portion
00254 **                      of the network address. This can only specify the
00255 **                      special well known values that are equivalent to
00256 **                      INADDR_ANY and INADDR_LOOPBACK.
00257 **
00258 **  PRUint16 af         The address family (either PR_AF_INET or PR_AF_INET6)
00259 **
00260 **  PRUint16 port       The port number to be assigned in the structure.
00261 **
00262 ** OUTPUTS:
00263 **  PRNetAddr *addr     The address to be manipulated.
00264 **
00265 ** RETURN:
00266 **  PRStatus            To indicate success or failure. If the latter, the
00267 **                      reason for the failure can be retrieved by calling
00268 **                      PR_GetError();
00269 ***********************************************************************/
00270 NSPR_API(PRStatus) PR_SetNetAddr(
00271     PRNetAddrValue val, PRUint16 af, PRUint16 port, PRNetAddr *addr);
00272 
00273 /***********************************************************************
00274 ** FUNCTION:  
00275 ** DESCRIPTION:      PR_IsNetAddrType()
00276 ** Determine if the network address is of the specified type.
00277 **
00278 ** INPUTS:
00279 **  const PRNetAddr *addr   A network address.
00280 **  PRNetAddrValue          The type of network address 
00281 **
00282 ** RETURN:
00283 **  PRBool                  PR_TRUE if the network address is of the
00284 **                          specified type, else PR_FALSE.
00285 ***********************************************************************/
00286 NSPR_API(PRBool) PR_IsNetAddrType(const PRNetAddr *addr, PRNetAddrValue val);
00287 
00288 /***********************************************************************
00289 ** FUNCTION:  
00290 ** DESCRIPTION:      PR_ConvertIPv4AddrToIPv6()
00291 ** Convert an IPv4 addr to an (IPv4-mapped) IPv6 addr
00292 **
00293 ** INPUTS:
00294 **  PRUint32  v4addr        IPv4 address
00295 **
00296 ** OUTPUTS:
00297 **  PRIPv6Addr *v6addr      The converted IPv6 address
00298 **
00299 ** RETURN:
00300 **  void
00301 **                       
00302 ***********************************************************************/
00303 NSPR_API(void) PR_ConvertIPv4AddrToIPv6(PRUint32 v4addr, PRIPv6Addr *v6addr);
00304 
00305 /***********************************************************************
00306 ** MACRO:     
00307 ** DESCRIPTION:      PR_NetAddrFamily()
00308 ** Get the 'family' field of a PRNetAddr union.
00309 **
00310 ** INPUTS:
00311 **  const PRNetAddr *addr   A network address.
00312 **
00313 ** RETURN:
00314 **  PRUint16                The 'family' field of 'addr'.
00315 ***********************************************************************/
00316 #define PR_NetAddrFamily(addr) ((addr)->raw.family)
00317 
00318 /***********************************************************************
00319 ** MACRO:     
00320 ** DESCRIPTION:      PR_NetAddrInetPort()
00321 ** Get the 'port' field of a PRNetAddr union.
00322 **
00323 ** INPUTS:
00324 **  const PRNetAddr *addr   A network address.
00325 **
00326 ** RETURN:
00327 **  PRUint16                The 'port' field of 'addr'.
00328 ***********************************************************************/
00329 #define PR_NetAddrInetPort(addr) \
00330     ((addr)->raw.family == PR_AF_INET6 ? (addr)->ipv6.port : (addr)->inet.port)
00331 
00332 /***********************************************************************
00333 ** FUNCTION:  
00334 ** DESCRIPTION:      PR_GetProtoByName()
00335 ** Lookup a protocol entry based on protocol's name
00336 **
00337 ** INPUTS:
00338 **  char *protocolname  Character string of the protocol's name.
00339 **  char *buf           A scratch buffer for the runtime to return result.
00340 **                      This buffer is allocated by the caller.
00341 **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
00342 **                      use is PR_NETDB_BUF_SIZE.
00343 ** OUTPUTS:
00344 **  PRHostEnt *PRProtoEnt
00345 **                      This structure is filled in by the runtime if
00346 **                      the function returns PR_SUCCESS. This structure
00347 **                      is allocated by the caller.
00348 ** RETURN:
00349 **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
00350 **                      the result will be PR_FAILURE and the reason
00351 **                      for the failure can be retrieved by PR_GetError().
00352 ***********************************************************************/
00353 
00354 typedef struct PRProtoEnt {
00355     char *p_name;       /* official protocol name */
00356     char **p_aliases;   /* alias list */
00357 #if defined(WIN32) || defined(WIN16)
00358     PRInt16 p_num;      /* protocol # */
00359 #else
00360     PRInt32 p_num;      /* protocol # */
00361 #endif
00362 } PRProtoEnt;
00363 
00364 NSPR_API(PRStatus) PR_GetProtoByName(
00365     const char* protocolname, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
00366 
00367 /***********************************************************************
00368 ** FUNCTION:  
00369 ** DESCRIPTION:      PR_GetProtoByNumber()
00370 ** Lookup a protocol entry based on protocol's number
00371 **
00372 ** INPUTS:
00373 **  PRInt32 protocolnumber
00374 **                      Number assigned to the protocol.
00375 **  char *buf           A scratch buffer for the runtime to return result.
00376 **                      This buffer is allocated by the caller.
00377 **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
00378 **                      use is PR_NETDB_BUF_SIZE.
00379 ** OUTPUTS:
00380 **  PRHostEnt *PRProtoEnt
00381 **                      This structure is filled in by the runtime if
00382 **                      the function returns PR_SUCCESS. This structure
00383 **                      is allocated by the caller.
00384 ** RETURN:
00385 **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
00386 **                      the result will be PR_FAILURE and the reason
00387 **                      for the failure can be retrieved by PR_GetError().
00388 ***********************************************************************/
00389 NSPR_API(PRStatus) PR_GetProtoByNumber(
00390     PRInt32 protocolnumber, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
00391 
00392 /***********************************************************************
00393 ** FUNCTION:
00394 ** DESCRIPTION: PR_GetAddrInfoByName()
00395 **  Lookup a host by name. Equivalent to getaddrinfo(host, NULL, ...) of
00396 **  RFC 3493.
00397 **
00398 ** INPUTS:
00399 **  char *hostname      Character string defining the host name of interest
00400 **  PRUint16 af         May be PR_AF_UNSPEC or PR_AF_INET.
00401 **  PRIntn flags        May be either PR_AI_ADDRCONFIG or
00402 **                      PR_AI_ADDRCONFIG | PR_AI_NOCANONNAME. Include
00403 **                      PR_AI_NOCANONNAME to suppress the determination of
00404 **                      the canonical name corresponding to hostname.
00405 ** RETURN:
00406 **  PRAddrInfo*         Handle to a data structure containing the results
00407 **                      of the host lookup. Use PR_EnumerateAddrInfo to
00408 **                      inspect the PRNetAddr values stored in this object.
00409 **                      When no longer needed, this handle must be destroyed
00410 **                      with a call to PR_FreeAddrInfo.  If a lookup error
00411 **                      occurs, then NULL will be returned.
00412 ***********************************************************************/
00413 typedef struct PRAddrInfo PRAddrInfo;
00414 
00415 NSPR_API(PRAddrInfo*) PR_GetAddrInfoByName(
00416     const char *hostname, PRUint16 af, PRIntn flags);
00417 
00418 /***********************************************************************
00419 ** FUNCTION:
00420 ** DESCRIPTION: PR_FreeAddrInfo()
00421 **  Destroy the PRAddrInfo handle allocated by PR_GetAddrInfoByName().
00422 **
00423 ** INPUTS:
00424 **  PRAddrInfo *addrInfo
00425 **                      The handle resulting from a successful call to
00426 **                      PR_GetAddrInfoByName().
00427 ** RETURN:
00428 **  void
00429 ***********************************************************************/
00430 NSPR_API(void) PR_FreeAddrInfo(PRAddrInfo *addrInfo);
00431 
00432 /***********************************************************************
00433 ** FUNCTION:
00434 ** DESCRIPTION: PR_EnumerateAddrInfo()
00435 **  A stateless enumerator over a PRAddrInfo handle acquired from
00436 **  PR_GetAddrInfoByName() to inspect the possible network addresses.
00437 **
00438 ** INPUTS:
00439 **  void *enumPtr       Index pointer of the enumeration. The enumeration
00440 **                      starts and ends with a value of NULL.
00441 **  PRAddrInfo *addrInfo
00442 **                      The PRAddrInfo handle returned by a successful
00443 **                      call to PR_GetAddrInfoByName().
00444 **  PRUint16 port       The port number to be assigned as part of the
00445 **                      PRNetAddr.
00446 ** OUTPUTS:
00447 **  PRNetAddr *result   A pointer to an address structure that will be
00448 **                      filled in by the call to the enumeration if the
00449 **                      result of the call is greater than zero.
00450 ** RETURN:
00451 **  void*               The value that should be used for the next call
00452 **                      of the enumerator ('enumPtr'). The enumeration
00453 **                      is ended if this value is returned NULL.
00454 ***********************************************************************/
00455 NSPR_API(void *) PR_EnumerateAddrInfo(
00456     void *enumPtr, const PRAddrInfo *addrInfo, PRUint16 port, PRNetAddr *result);
00457 
00458 /***********************************************************************
00459 ** FUNCTION:
00460 ** DESCRIPTION: PR_GetCanonNameFromAddrInfo()
00461 **  Extracts the canonical name of the hostname passed to
00462 **  PR_GetAddrInfoByName().
00463 **
00464 ** INPUTS:
00465 **  PRAddrInfo *addrInfo 
00466 **                      The PRAddrInfo handle returned by a successful
00467 **                      call to PR_GetAddrInfoByName().
00468 ** RETURN:
00469 **  const char *        A const pointer to the canonical hostname stored
00470 **                      in the given PRAddrInfo handle. This pointer is
00471 **                      invalidated once the PRAddrInfo handle is destroyed
00472 **                      by a call to PR_FreeAddrInfo().
00473 ***********************************************************************/
00474 NSPR_API(const char *) PR_GetCanonNameFromAddrInfo(
00475     const PRAddrInfo *addrInfo);
00476 
00477 /***********************************************************************
00478 ** FUNCTIONS: PR_ntohs, PR_ntohl, PR_ntohll, PR_htons, PR_htonl, PR_htonll
00479 **
00480 ** DESCRIPTION: API entries for the common byte ordering routines.
00481 **
00482 **      PR_ntohs        16 bit conversion from network to host
00483 **      PR_ntohl        32 bit conversion from network to host
00484 **      PR_ntohll       64 bit conversion from network to host
00485 **      PR_htons        16 bit conversion from host to network
00486 **      PR_htonl        32 bit conversion from host to network
00487 **      PR_ntonll       64 bit conversion from host to network
00488 **
00489 ***********************************************************************/
00490 NSPR_API(PRUint16) PR_ntohs(PRUint16);
00491 NSPR_API(PRUint32) PR_ntohl(PRUint32);
00492 NSPR_API(PRUint64) PR_ntohll(PRUint64);
00493 NSPR_API(PRUint16) PR_htons(PRUint16);
00494 NSPR_API(PRUint32) PR_htonl(PRUint32);
00495 NSPR_API(PRUint64) PR_htonll(PRUint64);
00496 
00497 PR_END_EXTERN_C
00498 
00499 #endif /* prnetdb_h___ */