class ref name: barecomputer
category-group: os
layer: 2
header file: z_barecomp.h

synopsis.
provides information about the host computer, including: name; IP address(es); hard drives; network interfaces

description.
The barecomputer_o class is an object whose purpose is to gather and maintain basic information about a computer, such as its name, IP address, network (ie MAC) address(es), and CPU type. This object represents a "bare" computer, as in bare metal - it does not handle file systems, which require a much higher layer.

There are a variety of ways to get the IP address of the host machine. This is because there can be multiple addresses, one for each MAC (ethernet) device. You can search the devices by interface number, name, or description. Every IP addresses are returned by calling IP_address(). However, you can control the method and specify filters (search criteria) by "flavoring" the object prior to calling IP_address():

  barecomputer_o host;
  host.sync();
  host.set_IPaddr_method(zVal_IPaddr_Adaptor);
  host.set_IPaddr_search_bydescrip("Dell Wireless");
  host.set_IPaddr_search_bynumber(4);
  host.set_nth_IPaddr(0);
  string_o sa = host.IP_address();

In this example, the search for an IP address will done by the implementation that queries each adaptor ("zVal_IPaddr_Adaptor"). This method is the only one that uses the "search_by[xxx]" functions. For example, if your code contains this:

  host.set_IPaddr_method(zVal_IPaddr_Vanilla);
  host.set_IPaddr_search_byname("TAP-Win32");

The "vanilla" method for getting the IP address will ignore search criteria. Also, there are some important characteristics you should know when using search criteria:

1. when using by-name or by-description searches, any partial match will return the IP address of the adaptor. Thus, if the description is "Dell Wireless 1705 802", setting the description search string to "Dell Wireless" or "Dell" will return the IP address of the MAC device.
If using multiple search criteria (eg name+number, number+description, name+description, or all 3), the first device matching any of the criteria will be used to obtain the IP address. - In the example above, a description matching "Dell Wireless" OR an interface #4 will result in the first ethernet device that fits either crieria to be used.
2. If an empty string (for name or description) is used, or an index value of -1 is set, the search criteria is shut off.
3. If there are no search criteria, the first MAC device fetched will be be used.
4. Search criteria apply only to methods that roll thru the MAC devices (currently [2016], this is 'zVal_IPaddr_Adaptor').
5. string-based search criteria are exact match substrings only. no regular expressions. The case is irrelevant (case-insensitive).

Lastly, the function set_nth_IPaddr() defines which IP address to get, if the device has more than 1 associcated with it. It is unusual to use this function under normal cases. If, instead of using '0' as in the example above, the line was this:

  host.set_nth_IPaddr(1);

This would tell the object to get the second IP address of the ethernet device. If there is none (most devices have only one address), an empty string would be returned.

You can also get the DNS address(es) used by the host computer. Given multiple addresses (usually there are 2 - the primary and secondary), you can fetch both like so:

  barecomputer_o host;
  host.sync();
  host.set_nth_IPaddr(0);               // optional - 0 is the default
  string_o dns1 = host.DNS_address();
  host.set_nth_IPaddr(1);
  string_o dns2 = host.DNS_address();
  std::cout << "DNS 1 = " << dns1 << ", DNS 2 = " << dns2 << "\n";

member functions (primary)

barecomputer_o()
SIGNATURE: barecomputer_o ()
SYNOPSIS:
instantiaate a simple barecomputer_o instance. The at-construction state of the object is "not synced". No data members are set at this point (accessing any of the object's information would yield empty strings). Any internal lists at this point are empty.
 

barecomputer_o(barecomputer_o)
SIGNATURE: barecomputer_o (const barecomputer_o &rhs)
SYNOPSIS: makes an exact copy of the "rhs" object.
 

operator = (barecomputer_o)
SIGNATURE: barecomputer_o &operator = (const barecomputer_o &rhs)
SYNOPSIS: copies exactly the RHS object ("rhs"); any previous contents are over-written.
RETURNS: reference [handle] to the current (left-hand side) object
 

destructor
SIGNATURE: ~barecomputer_o ()
SYNOPSIS:
'destroys' the object: all data fields are reset (to empty strings). This should be explicitly called only on pointers to computer objects created via "new".
 

barecomputer_o(<args>)
SIGNATURE: barecomputer_o (const string_o &s_name)
SYNOPSIS: creates a new computer object. the name is set to s_name.
 

name()
SIGNATURE: const string_o &name () const
SYNOPSIS: returns the name of the computer. The value returned is the same as that returned by z_hostame().
 

bios_date()
SIGNATURE: const time_o &bios_date () const
SYNOPSIS:
this provides the date of the computer's BIOS. Currently this is available only on Microsoft platforms. This value is provided by the Registry entry "SystemBiosDate". Resolution is to the day.
RETURNS: BIOS date (if set), as a time object
 

bios_description()
SIGNATURE: const string_o &bios_description () const
SYNOPSIS: returns the object's internal string variable ("bios_descrip") that is set via a sync() operation.
RETURNS: string object, containing text description of BIOS (if set).
 

cpu()
SIGNATURE: const CPU_o &cpu () const
SYNOPSIS:
this member function returns a reference (ie a handle) to the object's internal CPU_o variable. This member function must be used to query information regarding the computer's CPU (call sync() to proparly load the values from the current host, if desired).
 

netdev_list()
SIGNATURE: const vlist_o &netdev_list() const
SYNOPSIS:
this returns a reference to the list of network devices for the current object. This is for applications that prefer to work directly with this list (a simpler interface is provided via member function nth_netdev()). One of these two functions must be used to access this object's network devices.
 

IP_address()
SIGNATURE: const string_o IP_address (count_t n = 0, int *pi = NULL) const
SYNOPSIS: this member function returns the computer's IP address. see the caveats in the "bugs" section on this page.
PARAMETERS

• n: index, indicates whitch IP address to obtain (useful
• only in the case where more than 1 IP address is
• assigned to the host). Use n = 0 to obtain the first
• (primary) IP address.
• pi: an error indicator output 'flag' variable. values:
  0: success; information obtained
  1: sync() not done earlier
  2: service unavailable

RETURNS: [string object] contains host computer IP address, formatted as "nn.nn.nn.nn"
TRAITS:
this member function is currently non-conformant, because it gets the IP address of the underlying current host computer, not the object (to be fixed in future releases).
 

nth_netdev()
SIGNATURE: const net_device_o &nth_netdev (count_t n = 0, int *pi = NULL) const
PARAMETERS

• n: index into list of network devices. First device is accessed with n = 0
• pi: an error indicator output 'flag' variable. values:
  0: success; network (MAC) device retrieved
  1: 'n' out of bounds (exceeds number of devices)

RETURNS:
[net_device_o handle] if successfully retrieved
net_device_o::bad_reference(), if error occurred
 

set_name()
SIGNATURE: int set_name (const string_o &s)
SYNOPSIS: sets the name of the computer to "s"
RETURNS: 0 (always)
 

reset()
SIGNATURE: int reset ()
SYNOPSIS:
resets the computer object to at construction time. the state of the object is set to 'not synced'. all internal data is wiped out.
 

sync()
SIGNATURE: int sync (int *pi = NULL)
SYNOPSIS: syncs the current object with the underlying host computer. all values mapped to that of the host.
PARAMETERS

pi: an error indicator output 'flag' variable. values: 0: ok; all info obtained
1: could not get host name
2: could not get CPU info
3: could not get network device (NIC) info
4: could not get BIOS info (description)
5: could not get BIOS info (date)

RETURNS:
0: successful sync
-1: unrecoverable error occurred. internal values may not be accurate, and object state set to 'not synced'.
 

z_IPaddress_islocal()
SIGNATURE: boolean z_IPaddress_islocal (const barecomputer_o &x, int *pi)
SYNOPSIS: tells if the object's IP address (kept in internal variable "m_IPaddr") is a 'local host adaptor' address.
PARAMETERS

pi: an error indicator output 'flag' variable. values: 0: ok; all info obtained
1: IP address has not been set

RETURNS:
TRUE: address is a 'local' type
FALSE: address is not a 'local' type, or error ocurred
TRAITS: seemingly rather obscure purpose
 

usage.
Usage is a snap:
[1] create an object instance ("barecomputer_o x;");
[2] sync the object to the current host computer ("x.sync();");
[3] call the object's member functions for getting information. There are a few complications:

A computer can have multiple network IP addresses. The member function IP_address(), if called without any arguments, will return the "primary" IP address. In most cases, a computer has only this address. However, one can supply an [optional] index parameter ("i") to get the 'ith' IP address (if it exists).

A computer can have multiple network devices, thus having multiple ethernet addresses (see note section below for discussion on terms and nomenclature). To accomodate this, this object maintains an internal list of net_device objects.

note.
There is varying nomenclature here: a network device was commonly referred to as an ethernet card, and is sometimes called a "network card", even though it may not necessarily reside on a hardware card - or it can exist [nowadays] as purely software. An "ethernet address" is also called a MAC address. We use the terms interchangeably here).

This object uses some layer-2 objects, and hence should logically be in layer 3 [at least]. However, it is required at layer 2, and hence stays there. This requirement has led to the BIOS date function returning a type "time_o" - it would be preferable to use [layer 3] "stime_o". Otherwise, it is up to the client application to format the time into a string.

examples.
Usage of this object is very simple. Assuming you want information about the current host computer, you can do the following:

    void main (int argc, char** argv)
    {
        z_start();
        barecomputer_o x;
        x.sync();
        const CPU_o &r_cpu = x.cpu();
        const time_o &rt = x.bios_date();
std::cout << "CPU NAME .............: " << r_cpu.name()         << std::endl;
std::cout << "CPU DESCRIPTION ......: " << r_cpu.description()  << std::endl;
std::cout << "COMPUTER NAME ........: " << x.name()             << std::endl;
std::cout << "COMPUTER IP ADDRESS ..: " << x.IP_address()       << std::endl;
std::cout << "COMPUTER BIOS ........: " << x.bios_description() << std::endl;
        z_finish();
    }

limitations.
Currently, this object assumes there is 1 CPU object per computer object. this obviously fails to correctly model multi-processor computers. This problem will be addressed in future versions.

bugs.
member function IP_address() may have some problems. The function attempts to avoid returning the 'local host adaptor' address (127.0.0.1); its success is dependent on the underlying OS. Also, getting anything except the default address (n = 0) has not been adequately tested.