home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / nspr30-e.zip / nspr30-e / include / prnetdb.h < prev    next >
C/C++ Source or Header  |  1998-07-21  |  13KB  |  296 lines
  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 Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  * 
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  * 
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. #ifndef prnetdb_h___
  20. #define prnetdb_h___
  21.  
  22. #include "prtypes.h"
  23. #include "prio.h"
  24.  
  25. PR_BEGIN_EXTERN_C
  26.  
  27.  
  28. /*
  29.  *********************************************************************
  30.  *  Translate an Internet address to/from a character string
  31.  *********************************************************************
  32.  */
  33. PR_EXTERN(PRStatus) PR_StringToNetAddr(
  34.     const char *string, PRNetAddr *addr);
  35.  
  36. PR_EXTERN(PRStatus) PR_NetAddrToString(
  37.     const PRNetAddr *addr, char *string, PRUint32 size);
  38.  
  39. /*
  40. ** Structures returned by network data base library.  All addresses are
  41. ** supplied in host order, and returned in network order (suitable for
  42. ** use in system calls).
  43. */
  44. /*
  45. ** Beware that WINSOCK.H defines h_addrtype and h_length as short.
  46. ** Client code does direct struct copies of hostent to PRHostEnt and
  47. ** hence the ifdef.
  48. */
  49. typedef struct PRHostEnt {
  50.     char *h_name;       /* official name of host */
  51.     char **h_aliases;   /* alias list */
  52. #if defined(WIN32) || defined(WIN16)
  53.     PRInt16 h_addrtype; /* host address type */
  54.     PRInt16 h_length;   /* length of address */
  55. #else
  56.     PRInt32 h_addrtype; /* host address type */
  57.     PRInt32 h_length;   /* length of address */
  58. #endif
  59.     char **h_addr_list; /* list of addresses from name server */
  60. } PRHostEnt;
  61.  
  62. /* A safe size to use that will mostly work... */
  63. #if (defined(AIX) && defined(_THREAD_SAFE)) || defined(OSF1)
  64. #define PR_NETDB_BUF_SIZE sizeof(struct protoent_data)
  65. #else
  66. #define PR_NETDB_BUF_SIZE 1024
  67. #endif
  68.  
  69. /***********************************************************************
  70. ** FUNCTION:    
  71. ** DESCRIPTION:    PR_GetHostByName()
  72. ** Lookup a host by name.
  73. **
  74. ** INPUTS:
  75. **  char *hostname      Character string defining the host name of interest
  76. **  char *buf           A scratch buffer for the runtime to return result.
  77. **                      This buffer is allocated by the caller.
  78. **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
  79. **                      use is PR_NETDB_BUF_SIZE.
  80. ** OUTPUTS:
  81. **  PRHostEnt *hostentry
  82. **                      This structure is filled in by the runtime if
  83. **                      the function returns PR_SUCCESS. This structure
  84. **                      is allocated by the caller.
  85. ** RETURN:
  86. **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
  87. **                      the result will be PR_FAILURE and the reason
  88. **                      for the failure can be retrieved by PR_GetError().
  89. ***********************************************************************/
  90. PR_EXTERN(PRStatus) PR_GetHostByName(
  91.     const char *hostname, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
  92.  
  93. /***********************************************************************
  94. ** FUNCTION:    
  95. ** DESCRIPTION:    PR_GetHostByAddr()
  96. ** Lookup a host entry by its network address.
  97. **
  98. ** INPUTS:
  99. **  char *hostaddr      IP address of host in question
  100. **  char *buf           A scratch buffer for the runtime to return result.
  101. **                      This buffer is allocated by the caller.
  102. **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
  103. **                      use is PR_NETDB_BUF_SIZE.
  104. ** OUTPUTS:
  105. **  PRHostEnt *hostentry
  106. **                      This structure is filled in by the runtime if
  107. **                      the function returns PR_SUCCESS. This structure
  108. **                      is allocated by the caller.
  109. ** RETURN:
  110. **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
  111. **                      the result will be PR_FAILURE and the reason
  112. **                      for the failure can be retrieved by PR_GetError().
  113. ***********************************************************************/
  114. PR_EXTERN(PRStatus) PR_GetHostByAddr(
  115.     const PRNetAddr *hostaddr, char *buf, PRIntn bufsize, PRHostEnt *hostentry);
  116.  
  117. /***********************************************************************
  118. ** FUNCTION:    PR_EnumerateHostEnt()    
  119. ** DESCRIPTION:
  120. **  A stateless enumerator over a PRHostEnt structure acquired from
  121. **  PR_GetHostByName() PR_GetHostByAddr() to evaluate the possible
  122. **  network addresses.
  123. **
  124. ** INPUTS:
  125. **  PRIntn  enumIndex   Index of the enumeration. The enumeration starts
  126. **                      and ends with a value of zero.
  127. **
  128. **  PRHostEnt *hostEnt  A pointer to a host entry struct that was
  129. **                      previously returned by PR_GetHostByName() or
  130. **                      PR_GetHostByAddr().
  131. **
  132. **  PRUint16 port       The port number to be assigned as part of the
  133. **                      PRNetAddr.
  134. **
  135. ** OUTPUTS:
  136. **  PRNetAddr *address  A pointer to an address structure that will be
  137. **                      filled in by the call to the enumeration if the
  138. **                      result of the call is greater than zero.
  139. **
  140. ** RETURN:
  141. **  PRIntn              The value that should be used for the next call
  142. **                      of the enumerator ('enumIndex'). The enumeration
  143. **                      is ended if this value is returned zero.
  144. **                      If a value of -1 is returned, the enumeration
  145. **                      has failed. The reason for the failure can be
  146. **                      retrieved by calling PR_GetError().
  147. ***********************************************************************/
  148. PR_EXTERN(PRIntn) PR_EnumerateHostEnt(
  149.     PRIntn enumIndex, const PRHostEnt *hostEnt, PRUint16 port, PRNetAddr *address);
  150.  
  151. /***********************************************************************
  152. ** FUNCTION: PR_InitializeNetAddr(), 
  153. ** DESCRIPTION:
  154. **  Initialize the fields of a PRNetAddr, assigning well known values as
  155. **  appropriate.
  156. **
  157. ** INPUTS
  158. **  PRNetAddrValue val  The value to be assigned to the IP Address portion
  159. **                      of the network address. This can only specify the
  160. **                      special well known values that are equivalent to
  161. **                      INADDR_ANY and INADDR_LOOPBACK.
  162. **
  163. **  PRUInt16 port       The port number to be assigned in the structure.
  164. **
  165. ** OUTPUTS:
  166. **  PRNetAddr *addr     The address to be manipulated.
  167. **
  168. ** RETURN:
  169. **  PRStatus            To indicate success or failure. If the latter, the
  170. **                      reason for the failure can be retrieved by calling
  171. **                      PR_GetError();
  172. ***********************************************************************/
  173. typedef enum PRNetAddrValue
  174. {
  175.     PR_IpAddrNull,      /* do NOT overwrite the IP address */
  176.     PR_IpAddrAny,       /* assign logical INADDR_ANY to IP address */
  177.     PR_IpAddrLoopback   /* assign logical INADDR_LOOPBACK */
  178. } PRNetAddrValue;
  179.  
  180. PR_EXTERN(PRStatus) PR_InitializeNetAddr(
  181.     PRNetAddrValue val, PRUint16 port, PRNetAddr *addr);
  182.  
  183. /***********************************************************************
  184. ** FUNCTION:    
  185. ** DESCRIPTION:    PR_GetProtoByName()
  186. ** Lookup a protocol entry based on protocol's name
  187. **
  188. ** INPUTS:
  189. **  char *protocolname  Character string of the protocol's name.
  190. **  char *buf           A scratch buffer for the runtime to return result.
  191. **                      This buffer is allocated by the caller.
  192. **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
  193. **                      use is PR_NETDB_BUF_SIZE.
  194. ** OUTPUTS:
  195. **  PRHostEnt *PRProtoEnt
  196. **                      This structure is filled in by the runtime if
  197. **                      the function returns PR_SUCCESS. This structure
  198. **                      is allocated by the caller.
  199. ** RETURN:
  200. **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
  201. **                      the result will be PR_FAILURE and the reason
  202. **                      for the failure can be retrieved by PR_GetError().
  203. ***********************************************************************/
  204.  
  205. typedef struct PRProtoEnt {
  206.     char *p_name;       /* official protocol name */
  207.     char **p_aliases;   /* alias list */
  208. #if defined(WIN32) || defined(WIN16)
  209.     PRInt16 p_num;      /* protocol # */
  210. #else
  211.     PRInt32 p_num;      /* protocol # */
  212. #endif
  213. } PRProtoEnt;
  214.  
  215. PR_EXTERN(PRStatus) PR_GetProtoByName(
  216.     const char* protocolname, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
  217.  
  218. /***********************************************************************
  219. ** FUNCTION:    
  220. ** DESCRIPTION:    PR_GetProtoByNumber()
  221. ** Lookup a protocol entry based on protocol's number
  222. **
  223. ** INPUTS:
  224. **  PRInt32 protocolnumber
  225. **                      Number assigned to the protocol.
  226. **  char *buf           A scratch buffer for the runtime to return result.
  227. **                      This buffer is allocated by the caller.
  228. **  PRIntn bufsize      Number of bytes in 'buf'. A recommnded value to
  229. **                      use is PR_NETDB_BUF_SIZE.
  230. ** OUTPUTS:
  231. **  PRHostEnt *PRProtoEnt
  232. **                      This structure is filled in by the runtime if
  233. **                      the function returns PR_SUCCESS. This structure
  234. **                      is allocated by the caller.
  235. ** RETURN:
  236. **  PRStatus            PR_SUCCESS if the lookup succeeds. If it fails
  237. **                      the result will be PR_FAILURE and the reason
  238. **                      for the failure can be retrieved by PR_GetError().
  239. ***********************************************************************/
  240. PR_EXTERN(PRStatus) PR_GetProtoByNumber(
  241.     PRInt32 protocolnumber, char* buffer, PRInt32 bufsize, PRProtoEnt* result);
  242.  
  243. /***********************************************************************
  244. ** FUNCTION:    
  245. ** DESCRIPTION:    PR_SetIPv6Enable()
  246. **  Enable IPv6 capability on a platform that supports the architecture.
  247. **
  248. **  Note: IPv6 must first be enabled for the host platform. If it is not,
  249. **        the function will always return PR_FAILURE on any attempt to
  250. **        change the setting.
  251. **
  252. ** INPUTS:
  253. **  PRBool itIs
  254. **                      Assign it a value of PR_TRUE to turn on IPv6
  255. **                      addressing, PR_FALSE to turn it off.
  256. ** RETURN:
  257. **  PRStatus            PR_SUCCESS if the IPv6 is enabled for this particular
  258. **                      host. Otherwise it will return failure and GetError()
  259. **                      will confirm the result by indicating that the
  260. **                      protocol is not supported
  261. **                      (PR_PROTOCOL_NOT_SUPPORTED_ERROR) 
  262. ***********************************************************************/
  263. PR_EXTERN(PRStatus) PR_SetIPv6Enable(PRBool itIs);
  264.  
  265. /***********************************************************************
  266. ** FUNCTIONS: PR_ntohs, PR_ntohl, PR_ntohll, PR_htons, PR_htonl, PR_htonll
  267. **
  268. ** DESCRIPTION: API entries for the common byte ordering routines.
  269. **
  270. **      PR_ntohs        16 bit conversion from network to host
  271. **      PR_ntohl        32 bit conversion from network to host
  272. **      PR_ntohll       64 bit conversion from network to host
  273. **      PR_htons        16 bit conversion from host to network
  274. **      PR_htonl        32 bit conversion from host to network
  275. **      PR_ntonll       64 bit conversion from host to network
  276. **
  277. ***********************************************************************/
  278. PR_EXTERN(PRUint16) PR_ntohs(PRUint16);
  279. PR_EXTERN(PRUint32) PR_ntohl(PRUint32);
  280. PR_EXTERN(PRUint64) PR_ntohll(PRUint64);
  281. PR_EXTERN(PRUint16) PR_htons(PRUint16);
  282. PR_EXTERN(PRUint32) PR_htonl(PRUint32);
  283. PR_EXTERN(PRUint64) PR_htonll(PRUint64);
  284.  
  285. /***********************************************************************
  286. ** FUNCTION: PR_FamilyInet
  287. **
  288. ** DESCRIPTION: Routine to get value of address family for Internet Protocol
  289. **
  290. ***********************************************************************/
  291. PR_EXTERN(PRUint16) PR_FamilyInet(void);
  292.  
  293. PR_END_EXTERN_C
  294.  
  295. #endif /* prnetdb_h___ */
  296.