NSPR 2.0: Network Addresses

The Mozilla Organization
	At A Glance
	Feedback
	Get Involved
	Newsgroups
	License Terms
	Newsbot

Developer Docs
	Roadmap
	Projects
	Ports
	Module Owners
	Hacking
	Get the Source
	Build It

Testing
	Download
	Bugzilla
	Bug Writing

Tools
	View Source
	Tree Status
	New Checkins
	Submit A Bug

FAQ
Search

[Contents] [Previous] [Next] [Last]

Chapter 11
Network Addresses

This chapter describes the NSPR types and functions used to manipulate network addresses.

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
PRProtoEnt
PR_NETDB_BUF_SIZE

PRHostEnt

A structure that defines a list of network addresses. This structure is output from PR_GetHostByName and PR_GetHostByAddr and passed to PR_EnumerateHostEnt. Clients should avoid directly accessing any of the structure's fields.

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

The structure has the following 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

This structure is used by many of the network address functions. All addresses are passed in host order and returned in network order (suitable for use in system calls).

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.

NOTE: WINSOCK.H defines h_addrtype and h_length as a 16-bit field, whereas other platforms treat it as a 32-bit field. The #ifdef in the structure allows direct assignment of the PRHostEnt structure.

PRProtoEnt

Protocol entry returned by PR_GetProtoByName and PR_GetProtoByNumber.

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

The structure has the following 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
Converting Between a String and a Network Address
Getting Host Names and Addresses
Getting Protocol Entries
Enabling IP v6

Initializing a Network Address

PR_InitializeNetAddr facilitates the use of PRNetAddr, the basic network address structure, in a polymorphic manner. By using these functions with other network address functions, clients can support either version 4 or version 6 of the Internet Protocol transparently.

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

PR_InitializeNetAddr

Initializes or reinitializes a network address. The storage for the network address structure is allocated by, and remains the responsibility of, the calling client.

Syntax

#include <prnetdb.h>

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

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 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 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

Converts a character string to a network address.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following parameters:

string
The string to be converted.

addr
On output, the equivalent network address.

Returns

The function returns one of the following values:

If successful, PR_SUCCESS.

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

Description

For IPv4 addresses, the input string represents numbers in the Internet standard "." notation. IPv6 addresses are indicated as strings using ":" characters separating octets, with numerous caveats for shortcutting (see RFC #1884). If the NSPR library and the host are configured to support IPv6, both formats are supported. Otherwise, use of anything other than IPv4 dotted notation results in an error.

PR_NetAddrToString

Converts a network address to a character string.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following parameters:

addr
A pointer to the network address to be converted.

string
On output, a pointer to the equivalent string.

size
The size of the network address to be converted.

Returns

The function returns one of the following values:

If successful, PR_SUCCESS.

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

Description

The network address to be converted (addr) may be either an IPv4 or IPv6 address structure, assuming that the NSPR library and the host system are both configured to utilize IPv6 addressing.

Getting Host Names and Addresses

PR_GetHostByName
PR_GetHostByAddr
PR_EnumerateHostEnt

PR_GetHostByName

Looks up a host by name.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following 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

The function returns one of the following values:

If successful, PR_SUCCESS.

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

PR_GetHostByAddr

Looks up a host entry by its network address.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following 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

The function returns one of the following values:

If successful, PR_SUCCESS.

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

Description

PR_GetHostByAddr is used to perform reverse lookups of network addresses. That is, given a valid network address (of type PRNetAddr), PR_GetHostByAddr discovers the address' primary name, any aliases, and any other network addresses for the same host.

PR_EnumerateHostEnt

Evaluates each of the possible addresses of a PRHostEnt structure, acquired from PR_GetHostByName or PR_GetHostByAddr.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following 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

The function returns one of the following values:

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

PR_EnumerateHostEnt is a stateless enumerator. The principle input, the PRHostEnt structure, is not modified.

Getting Protocol Entries

PR_GetProtoByName

Looks up a protocol entry based on the protocol's name.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following 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

The function returns one of the following values:

If successful, PR_SUCCESS.

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

PR_GetProtoByNumber

Looks up a protocol entry based on protocol's number.

Syntax

#include <prnetdb.h>

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

Parameters

The function has the following 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

The function returns one of the following values:

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

Enables or disables IPv6 capability on a platform that supports the architecture.

Syntax

#include <prnetdb.h>

PRStatus PR_SetIPv6Enable(PRBool itIs);

Parameter

The function has the following parameter:

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

Returns

The function returns one of the following values:

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

For PR_SetIPv6Enable to succeed, IPv6 must first be enabled for the host platform. If IPv6 is not enabled for the host platform, PR_SetIPv6Enable returns PR_FAILURE on any attempt to change the setting.

[Contents] [Previous] [Next] [Last]

Last Updated: Mon Jul 13 18:11:48 PDT 1998

Chapter 11 Network Addresses

Fields

PRProtoEnt

Fields

Network Address Functions

Parameters

Description

PR_StringToNetAddr

Parameters

Description

Parameters

Description

Parameters

PR_GetHostByAddr

Parameters

Description

Parameters

Description

PR_GetProtoByName

Parameters

PR_GetProtoByNumber

Parameters

Enabling IP v6

PR_SetIPv6Enable

Parameter

Description

Chapter 11
Network Addresses