NSPR Reference: Chapter 11 Network Addresses
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

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

Recommended size to use when specifying a scratch buffer for `PR_GetHostByName`, `PR_GetHostByAddr`, `PR_GetProtoByName`, or `PR_GetProtoByNumber`.

##### 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);

##### Parameters

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

The function returns one of the following values:

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

`PR_InitializeNetAddr` allows the assignment of special network address values and the port number, while also setting the state that indicates the version of the address being used.

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

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
| A buffer that will hold the converted string on output.
    size
| The size of the result buffer (`string`).

##### 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. If `addr` is an IPv4 address, `size` needs to be at least 16. If `addr` is an IPv6 address, `size` needs to be at least 46.

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

Previous Contents Next

Last Updated May 18, 2001