Mozilla

Network Address Types and Constants
Network Address Functions

The API described in this chapter recognizes the emergence of Internet Protocol Version 6 (IPv6). To facilitate the transition to IPv6, it is recommended that clients treat all structures containing network addresses as transparent objects and use the functions documented here to manipulate the information.

If used consistently, this API also eliminates the need to deal with the byte ordering of network addresses. Typically, the only numeric declarations required are the well-known port numbers that are part of the PRNetAddr structure.

Network Address Types and Constants

PRHostEnt

Syntax

#include <prnetdb.h>

typedef struct PRHostEnt {
   char *h_name;
   char **h_aliases;
#if defined(_WIN32)
   PRInt16 h_addrtype;
   PRInt16 h_length;
#else
   PRInt32 h_addrtype;
   PRInt32 h_length;
#endif
   char **h_addr_list;
} PRHostEnt;

Fields

h_name	Pointer to the official name of host.
h_aliases	Pointer to a pointer to list of aliases. The list is terminated with a NULL entry.
h_addrtype	Host address type. For valid NSPR usage, this field must have a value indicating either an IPv4 or an IPv6 address.
h_length	Length of internal representation of the address in bytes. All of the addresses in the list are of the same type and therefore of the same length.
h_addr_list	Pointer to a pointer to a list of addresses from name server. The list is terminated with a NULL entry.

Description

Use the network address functions to manipulate the PRHostEnt structure. To make the transition to IP version 6 easier, it's best to treat PRHostEnt as an opaque structure.

PRProtoEnt

Syntax

#include <prnetdb.h>

typedef struct PRProtoEnt {
   char *p_name; 
   char **p_aliases;
#if defined(_WIN32)
   PRInt16 p_num;
#else
   PRInt32 p_num;
#endif
} PRProtoEnt;

Fields

p_name	Pointer to official protocol name.
p_aliases	Pointer to a pointer to a list of aliases. The list is terminated with a NULL entry.
p_num	Protocol number.

PR_NETDB_BUF_SIZE

Syntax

#include <prnetdb.h>

#if defined(AIX) || defined(OSF1)
   #define PR_NETDB_BUF_SIZE sizeof(struct protoent_data)
#else
   #define PR_NETDB_BUF_SIZE 1024
#endif

Network Address Functions

Initializing a Network Address

All NSPR functions that require PRNetAddr as an argument accept either an IPv4 or IPv6 version of the address.

PR_InitializeNetAddr

Syntax

#include <prnetdb.h> 

PRStatus PR_InitializeNetAddr(
   PRNetAddrValue val, 
   PRUint16 port, 
   PRNetAddr *addr);

Parameters

val	The value to be assigned to the IP Address portion of the network address. This must be PR_IpAddrNull, PR_IpAddrAny, or PR_IpAddrLoopback.
port	The port number to be assigned in the network address structure. The value is specified in host byte order.
addr	A pointer to the PRNetAddr structure to be manipulated.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. This may occur, for example, if the value of val is not within the ranges defined by PRNetAddrValue. You can retrieve the reason for the failure by calling PR_GetError.

Description

The special network address values are identified by the enum PRNetAddrValue:

typedef enum PRNetAddrValue{
   PR_IpAddrNull,
   PR_IpAddrAny,
   PR_IpAddrLoopback
} PRNetAddrValue;

The enum has the following enumerators:

PR_IpAddrNull	Do not overwrite the IP address. This allows the caller to change the network address' port number assignment without affecting the host address.
PR_IpAddrAny	Assign logical PR_INADDR_ANY to IP address. This wildcard value is typically used to establish a socket on which to listen for incoming connection requests.
PR_IpAddrLoopback	Assign logical PR_INADDR_LOOPBACK. A client can use this value to connect to itself without knowing the host's network address.

Converting Between a String and a Network Address

PR_StringToNetAddr

Syntax

#include <prnetdb.h> 

PRStatus PR_StringToNetAddr(
   const char *string,
   PRNetAddr *addr);

Parameters

string	The string to be converted.
addr	On output, the equivalent network address.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError.

Description

PR_NetAddrToString

Syntax

#include <prnetdb.h> 

PRStatus PR_NetAddrToString(
   const PRNetAddr *addr, 
   char *string, 
   PRUint32 size);

Parameters

addr	A pointer to the network address to be converted.
string	A buffer that will hold the converted string on output.
size	The size of the result buffer (string).

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError.

Description

Getting Host Names and Addresses

PR_GetHostByName

Syntax

#include <prnetdb.h> 

PRStatus PR_GetHostByName(
   const char *hostname, 
   char *buf, 
   PRIntn bufsize, 
   PRHostEnt *hostentry);

Parameters

hostname	The character string defining the host name of interest.
buf	A pointer to a buffer, allocated by the caller, that is filled in with host data on output. All of the pointers in the hostentry structure point to data saved in this buffer. This buffer is referenced by the runtime during a call to PR_EnumerateHostEnt.
bufsize	Number of bytes in the buf parameter. The buffer must be at least PR_NETDB_BUF_SIZE bytes.
hostentry	This structure is allocated by the caller. On output, this structure is filled in by the runtime if the function returns PR_SUCCESS.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError.

PR_GetHostByAddr

Syntax

#include <prnetdb.h> 

PRStatus PR_GetHostByAddr(
   const PRNetAddr *hostaddr, 
   char *buf, 
   PRIntn bufsize, 
   PRHostEnt *hostentry);

Parameters

hostaddr	A pointer to the IP address of host in question.
buf	A pointer to a buffer, allocated by the caller, that is filled in with host data on output. All of the pointers in the hostentry structure point to data saved in this buffer. This buffer is referenced by the runtime during a call to PR_EnumerateHostEnt.
bufsize	Number of bytes in the buf parameter. The buffer must be at least PR_NETDB_BUF_SIZE bytes.
hostentry	This structure is allocated by the caller. On output, this structure is filled in by the runtime if the function returns PR_SUCCESS.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError.

Description

PR_EnumerateHostEnt

Syntax

#include <prnetdb.h> 

PRIntn PR_EnumerateHostEnt(
   PRIntn enumIndex, 
   const PRHostEnt *hostEnt, 
   PRUint16 port, 
   PRNetAddr *address);

Parameters

enumIndex	The index of the enumeration. To begin an enumeration, this argument is set to zero. To continue an enumeration (thereby getting successive addresses from the host entry structure), the value should be set to the function's last returned value. The enumeration is complete when a value of zero is returned.
hostEnt	A pointer to a PRHostEnt structure obtained from PR_GetHostByName or PR_GetHostByAddr.
port	The port number to be assigned as part of the PRNetAddr structure. This parameter is not checked for validity.
address	On input, a pointer to a PRNetAddr structure. On output, this structure is filled in by the runtime if the result of the call is greater than 0.

Returns

• If successful, the function returns the value you should specify in the enumIndex parameter for the next call of the enumerator. If the function returns 0, the enumeration is ended.

• If unsuccessful, the function returns -1. You can retrieve the reason for the failure by calling PR_GetError.

Description

Getting Protocol Entries

PR_GetProtoByName

Syntax

#include <prnetdb.h> 

PRStatus PR_GetProtoByName(
   const char* protocolname, 
   char* buffer, 
   PRInt32 bufsize, 
   PRProtoEnt* result);

Parameters

protocolname	A pointer to the character string of the protocol's name.
buffer	A pointer to a scratch buffer for the runtime to return result.This buffer is allocated by the caller.
bufsize	Number of bytes in the buffer parameter. The buffer must be at least PR_NETDB_BUF_SIZE bytes.
result	On input, a pointer to a PRProtoEnt structure. On output, this structure is filled in by the runtime if the function returns PR_SUCCESS.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError.

PR_GetProtoByNumber

Syntax

#include <prnetdb.h> 

PRStatus PR_GetProtoByNumber(
   PRInt32 protocolnumber, 
   char* buffer, 
   PRInt32 bufsize, 
   PRProtoEnt* result);

Parameters

protocolnumber	The number assigned to the protocol.
buffer	A pointer to a scratch buffer for a temporary work area. This buffer is allocated by the caller.
bufsize	Number of bytes in the buffer parameter. You should specify PR_NETDB_BUF_SIZE.
result	On input, a pointer to a PRNetAddr structure. On output, this structure is filled in by the runtime if the function returns PR_SUCCESS.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError.

Enabling IP v6

PR_SetIPv6Enable

Syntax

#include <prnetdb.h> 

PRStatus PR_SetIPv6Enable(PRBool itIs);

Parameter

itIs	PR_TRUE to turn on IPv6 addressing, PR_FALSE to turn it off.

Returns

• If successful, PR_SUCCESS.

• If unsuccessful, PR_FAILURE. You can retrieve the reason for the failure by calling PR_GetError. The error PR_PROTOCOL_NOT_SUPPORTED_ERROR indicates that the protocol is not supported.

Description