synopsis.
The "internet address object ( internet_address_o ) is an object that acts basically as a container to hold a version 4 IP (Internet Protocol) address. No additional function is [currently] offered. This class in the past was the base class for the e-mail address object (), but it was decided that an e-mail address is not really a kind-of IP address. The two classes are [now] siblings, both subclassed from address_o .

The current implementation supports the IPv4 model.

Besides the class we have here 2 layer-2 supporting functions:

1. z_str_lookslike_IPaddr() - tells if a string's contents is of the format nnn.nnn.nnn.nnn;
2. z_IPaddress_to_hostname() - takes an IP address (in a string object) and looks up the actual host computer name associated with it.

description.
This object model IPv4 address, which use 32-bit (four-byte) addresses. This limits the address space to 4294967296 (232) addresses. Since this class sub-classes from address_o, which is orthodox, an internet_address_o can be retrieved from and saved to a database. The dbtable schema for this object is this:

"internet_address
(
  columns
  [
<name     type qual nulls_ok is_uniq ref_table ref_column default check>
<octet0    smallint \"\"  YES       NO      \"\"      \"\" \"\"   \"\" >
<octet1    smallint \"\"  YES       NO      \"\"      \"\" \"\"   \"\" >
<octet2    smallint \"\"  YES       NO      \"\"      \"\" \"\"   \"\" >
<octet3    smallint \"\"  YES       NO      \"\"      \"\" \"\"   \"\" >
<note         char   40   YES       NO      \"\"      \"\" \"\"   \"\" >
<location     char   40   YES       NO      \"\"      \"\" \"\"   \"\" >
<options      char    5   YES       NO      \"\"      \"\" \"\"   \"\" >
<free_text    char   90   YES       NO      \"\"      \"\" \"\"   \"\" >
  ]
  indexes
  (
  )
  primary_key < >
)

member functions (primary)

internet_address_o()
SIGNATURE: internet_address_o ()
SYNOPSIS: instantiaate a internet address instance. The object will initially have no internal value.
 

internet_address_o(internet_address_o)
SIGNATURE: internet_address_o (const internet_address_o &rhs)
SYNOPSIS:
makes an exact copy of the RHS object, 'rhs'. If the copied object is uninitialized, the current object will be uninitialized also.
 

internet_address_o(<args>)
SIGNATURE: internet_address_o (const string_o &x)
SYNOPSIS:
creates a new internet address instance and sets its value to the value given in 'x'. The variable 'x' must be of valid IPv4 syntax, else the object will be in an "uninitialized" state.
 

operator = (internet_address_o)
SIGNATURE: const internet_address_o &operator = (const internet_address_o &rhs)
SYNOPSIS: copies exactly the RHS object 'rhs'; any previous contents is lost.
RETURNS: a reference (eg, a handle) to the current object ("*this").
 

destructor
SIGNATURE: ~internet_address_o ()
SYNOPSIS: destructor. the object's internal contents is wiped out.
 

operator = (internet_address_o)
SIGNATURE: const internet_address_o &operator = (const string_o &x)
SYNOPSIS: assigns the object's value (eg the IP address) to that of 'x'. This value need not actually be an existing IP address.
RETURNS: a reference (eg a handle) to the current object ("*this").
 

is_set()
SIGNATURE: boolean is_set () const
SYNOPSIS:
this returns a simple TRUE/FALSE flag value indicating whether the object has been asigned a value - that is, if the address has been set.
TRAITS: this is a simple, inline function.
 

show_options()
SIGNATURE: boolean show_options () const
SYNOPSIS:
tells if options will be added during 'print()' operation. This simply maps onto the value of internal variable 'my_opts'.
TRAITS: this is a simple, inline function.
 

is_bad()
SIGNATURE: boolean is_bad () const
SYNOPSIS: tells if the "is bad" flag ('my_bad') is set.
DESCRIPTION:
this member function applies to print() operations. if the flag is set, and if "is bad" is TRUE, the lexeme "{bad}" will be appended to the IP address.
TRAITS: this is a simple, inline function.
 

is_odd()
SIGNATURE: boolean is_odd () const
SYNOPSIS: tells if the "is odd" flag ('my_odd') is set.
DESCRIPTION:
this member function applies to print() operations. if the flag is set, and if the address "is odd", the lexeme "{?}" will be appended to the IP address.
TRAITS: this is a simple, inline function.
 

do_avoid()
SIGNATURE: boolean do_avoid () const
SYNOPSIS: tells if the "is odd" flag ('my_odd') is set.
DESCRIPTION:
this member function applies to print() operations. if the flag is set, and if the address "is odd", the lexeme "{?}" will be appended to the IP address.
TRAITS: this is a simple, inline function.
 

do_ignore()
SIGNATURE: boolean do_ignore () const
SYNOPSIS: tells if the "is odd" flag ('my_odd') is set.
DESCRIPTION:
this member function applies to print() operations. if the flag is set, and if the address "is odd", the lexeme "{?}" will be appended to the IP address.
TRAITS: this is a simple, inline function.
 

location()
SIGNATURE: const string_o &location() const
SYNOPSIS: returns any "location" note attached to the object.
DESCRIPTION:
this member function applies to print() operations. if the location internal variable is non-empty, the value of internal variable 'my_loc' will be appended to the IP address. the format of the result is thus:

{loc: [text]}

TRAITS: this is a simple, inline function.
 

note()
SIGNATURE: const string_o ¬e() const
SYNOPSIS: returns any note attached to the object.
DESCRIPTION:
this member function applies to print() operations. if the 'my_note' internal variable is non-empty, the value of internal variable 'my_note' will be appended to the IP address. the format of the result is thus:

{note: [text]}

TRAITS: this is a simple, inline function.
 

operator !=()
SIGNATURE: int operator != (const internet_address_o &rhs) const
SYNOPSIS: test for equality. if each octet is the same as that of 'rhs', this returns 0.
TRAITS: this is a simple, inline function. It is the converse of operator == ().
 

operator ==()
SIGNATURE: int operator == (const internet_address_o &rhs) const
SYNOPSIS: tests for equality between the current object and 'rhs'.
 

octet()
SIGNATURE: const string_o &octet (count_t i, int *pi = NULL) const
SYNOPSIS: returns the desired "octect", as a string. object must be set to an address and i must be in bounds.
PARAMETERS

• i: index for the specific octect. must be in the range [0..4]. if not, 'pi' is set to a non-zero error code and the returned value is garbage.
• pi: [output] error indicator variable. Its values:
  0: all ok; item found and returned
  zErr_Param_BadVal: i out of bounds (not in [0..4])
  zErr_NotInitialized: object was not set

RETURNS:
[string] contains the string form of the number for the desired octect
[bad string] a reference (eg, handle) to "string_o::bad_reference()", if an error ocurred, such as the object not being set to an address or 'i' out of bounds.
 

print()
SIGNATURE: string_o print () const
SYNOPSIS: "prints" the IP address as text, returns a string
RETURNS: returns a string object containing the address. If no address was set, the returned string is empty ("").
 

options()
SIGNATURE: string_o options () const
SYNOPSIS: prints the option list for the IP address as text. returns a string containing a concatenated list.
 

operator <<()
SIGNATURE: std::ostream &operator << (std::ostream &ost, const internet_address_o &ia)
SYNOPSIS: "prints" the object to the given ostream.
TRAITS: this is a "friend" [global-scope] subroutine
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: resets the object. the internal contents are wiped out. the object address becomes uninitialized.
 

clone()
SIGNATURE: internet_address_o *clone () const
SYNOPSIS: makes a copy of the current object.
RETURNS: returns a pointer to the newly-created object.
 

set_octet()
SIGNATURE: int set_octet (count_t idx, u_int val, int *pi = NULL)
SYNOPSIS: set a single "octet" of the IP address
PARAMETERS

• idx: index, directing which octet is to be set. Must be in the range [0..4] in order for this function to succeed.
• val: value to set the octet to. Must be in the range [0.. 255]
• pi: [output] error indicator variable. Its values:
  0: all ok; item set
  zErr_Param_BadVal: i out of bounds (not in [0..4]), or 'val' is out of bounds (256+).

RETURNS:
0: success
-1: error ocurred (see value of 'pi')
 

copy()
SIGNATURE: int copy (const internet_address_o &rhs)
SYNOPSIS: copies the contents of 'rhs' into the current object.
PARAMETERS

rhs: object to be copied.

TRAITS: not intended for public consumption. This is used by other "copy" type operators.
 

z_IPaddress_to_hostname()
SIGNATURE: string_o z_IPaddress_to_hostname (const string_o &s, int style = 0, int *pi = NULL)
SYNOPSIS:
looks up the IP address given in 's', and returns the corresponding computer name (if one is found that matches the address).
PARAMETERS

• s: string containing an IP address.
• style: if there are multiple names for the computer, this parameter determines which criteria to use for the winning selection:
  0: use the fullest qualified name (e.g, with the domain attached);
  1: use the first answer that comes back;
  2: use the shortest (e.g, "brick.vettrasoft.com" would come back as "brick");
  3: get an alternate name (anything beyond the first entry)
• pi: [output] error indicator variable. Its possible values:
  0: all ok; host name found and returned
  zErr_Param_NotSet: input string 'strip' is empty
  zErr_Param_BadFormat: 'strip' not of the form a.b.c.d
  zErr_NoMatch: given address is unknown
  zErr_Param_BadVal: 'style' not in [0..3]
  1: no alternate name (only for style == 3)

 

z_str_lookslike_IPaddr()
SIGNATURE: boolean z_str_lookslike_IPaddr (const string_o &s)
SYNOPSIS:
returns TRUE, if the string 's' contains a valid IP address (ie, the format is like "nnn.nnn.nnn.nnn" - a sequence of four numbers separated by dots).
RETURNS:
TRUE: string 's' contains text like "nnn.nnn.nnn.nnn", where "n" is a digit;
FALSE; otherwise
 

note.
IP version 4 addresses have historically been assigned to users and businesses over the years. The number of unassigned addresses decreased to 0 on February 3, 2011 ("IPv4 address exhaustion"). However, since IPv4 is universally accepted, this object reflects that protocol. Alghough IPv4 addresses may be written in any notation expressing a 32-bit integer value, it is customary to use the dot-decimal notation, eg, 74.50.60.177. Here is a comparision of common and alternative notations:

Although the database contains columns for note, location, and options, currently there is no facility for accessing these [unused] locations.

examples.
There is really not much interesting code available for this object.

bugs.
currently there is no provision for IPv6.

history.

Fri 03/20/1998: {7:38 pm} added: notes, location, badness, parsing
Sat 07/04/1998: {18:19:31 EDT} moved to layer 8, from layer 3
Sat 07/18/1998: started to phase in "orthodox" implementation
Sun 07/19/1998: {19:40:18 EDT} disconnected the "orthodox" stuff
Sun 10/06/2002: operator = (string_o) changed, input must be IP address
Sun 07/15/2012: name change for "z_str_looks_like_IPaddr()"