csu3_am335x/EVSE/GPL/plc-utils.LNX.2.1.20/source/docbook2/CPLStation.xml

<chapter id='CPLStation'>
	<title>
		Class CPLStation
		</title>
	<section id="CPLStation-class">
		<title>
			Introduction
			</title>
		<para>
			This class implements a single station on a HomePlug AV powerline network. Class instances are instantiated and initialized only by instantiating the <link linkend='CPLNetwork'>CPLNetwork</link> class. Class properties are read-only and class methods are passive.
			</para>
		<para>
			The <citetitle>Firmware Technical Reference Manaual</citetitle> uses terminology that views a powerline network from the <quote>inside-looking-out</quote>. This class uses terminology that views a powerline network from the <quote>outside-looking-in</quote>. For example, here, a <quote>device</quote> is something connected to a powerline <quote>station</quote>, a <quote>network</quote> is a collection of <quote>stations</quote> and every <quote>adapter</quote> is a <quote>station</quote>.
			</para>
		<para>
			This class is declared in <ulink url='CPLStation.hpp.html'>CPLStation.hpp</ulink> and defined in <ulink url='CPLStation.cpp.html'>CPLStation.cpp</ulink>.
			</para>
		<section id="CPLStation-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				None.
				</para>
			</section>
		<section id="CPLStation-dependence">
			<title>
				Dependence
				</title>
			<para>
				This class depends on the <link linkend='CPLNetwork'>CPLNetwork</link> class to instantiate it and inialize all properties. There is no need for an application programs to instantiate this class directly. 
				</para>
			<para>
				This class uses class <link linkend='ointellon'>ointellon</link> to encode and decode vendor specific management message frames.
				</para>
			<para>
				This class uses static class <link linkend='omemory'>omemory</link> to print outgoing and incoming frames.
				</para>
			<para>
				This class uses static class <link linkend='oerror'>oerror</link> to report errors.
				</para>
			</section>
		</section>
	<section id="CPLStation-properties">
		<title>
			Properties
			</title>
		<para>
			This class inherits no properties. Class properties are all read-only and cannot be modified once initialized.
			</para>
		<section id="CPLStation-HardwareType">
			<title>
				CPLStation::HardwareType
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>HardwareType</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the hardware type as an unsigned integer. The hardware type incidates the chipset architecture. The value <constant>0</constant> means an unknown chipset architecture. A value greater than <constant>0</constant> indicates an <productname>INT6000</productname>,  <productname>INT6300</productname>, <productname>INT6400</productname> and so on. The hardware type is the same as the <varname>MDEVICEID</varname> field of the <varname>VS_SW_VER</varname> management message described in the <citetitle>Firmware Technical Reference Manual</citetitle>.
				</para>
			</section>
		<section id="CPLStation-HardwareName">
			<title>
				CPLStation::HardwareName
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>HardwareName</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the hardware name as a <constant>NUL</constant> terminated character string. The hardware name is based on the <link linkend='CPLStation-HardwareType'>HardwareType</link>. The string <constant>"UNSUPPORTED"</constant> means the chipset is not recognized. Normally, the string will be one of <constant>"INT6000"</constant>, <constant>"INT6300"</constant> or <constant>"INT6400"</constant>.  
				</para>
			</section>
		<section id="CPLStation-FirmwareName">
			<title>
				CPLStation::FirmwareName
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>FirmwareName</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the fimware revision as a <constant>NUL</constant> terminated character string.  An example string might look like <constant>"INT6000-MAC-4-0-4011-01-3431-20090519-FINAL-B"</constant>. The firmware revision is the same as the <varname>MVERSION</varname> field of the <varname>VS_SW_VER</varname> management message described in the <citetitle>Firmware Technical Reference Manual</citetitle>.
				</para>
			</section>
		<section id="CPLStation-HostAddress">
			<title>
				CPLStation::HostAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef> byte const * <function>HostAddress</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the first bridged device hardware address. This is the hardware address of the first Ethernet device being supported by the powerline station. The bridged device address is <constant>ETHER_ADDR_LEN</constant> bytes. The host address is the same as the <acronym>BDA</acronym> returned by the <varname>VS_NW_INFO</varname> management message described in the <citetitle>Firwmare Technical Reference Manual</citetitle>.
				</para>
			<para>
				If the host address is the <link linkend='oethernet-BroadcastAddress'>BroadcastAddress</link> then no Ethernet devices are connected to the station. This is a common condition that does not affect the reliability of the other property values.
				</para>
			</section>
		<section id="CPLStation-HostAddressString">
			<title>
				CPLStation::HostAddressString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>HostAddressString</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the <link linkend='CPLStation-HostAddress'>HostAddress</link> property as a <constant>NUL</constant> terminated hexadecimal character string. The string is <constant>ETHER_ADDR_LEN</constant>*<constant>3</constant> characters long including the terminator. 
				</para>
			</section>
		<section id="CPLStation-IsBridge">
			<title>
				CPLStation::IsBridge
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>bool <function>IsBridge</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return logical <constant>true</constant> if this station is a host bridge. This property is a boolean alternative to the <link linkend='CPLStation-LinkType'>LinkType</link> property.
				</para>
			</section>
		<section id="CPLStation-LinkName">
			<title>
				CPLStation::LinkName
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>LinkName</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the relationship between the station and this host as a <constant>NUL</constant> terminated character string. The string <constant>"LOC"</constant> means the station is local and serves as the ethernet-to-powerline bridge for this host. The string <constant>"REM"</constant> means the station is remote as serves as the powerline-to-ethernet bridge for another host. These string are useful when enumerating powerline network devices. 
				</para>
			</section>
		<section id="CPLStation-LinkType">
			<title>
				CPLStation::LinkType
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>LinkType</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the relationship between the station and this host as an unsigned integer. The value <constant>0</constant> means the station is local and serves as the ethernet-to-powerline bridge for this host. The value <constant>1</constant> means the station is remote and serves as the powerline-to-ethernet bridge for another host. 
				</para>
			</section>
		<section id="CPLStation-NodeAddress">
			<title>
				CPLStation::NodeAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef> byte const * <function>NodeAddress</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the station hardware address. This is the address of the powerline station, itself. The station address is <constant>ETHER_ADDR_LEN</constant> bytes. The node address is the same as the <acronym>DA</acronym> field of the <varname>VS_NW_INFO</varname> management message described in the <citetitle>Firwmare Technical Reference Manual</citetitle>.
				</para>
			<para>
				If the node address is the <link linkend='oethernet-BroadcastAddress'>BroadcastAddress</link> then the associated station is no longer connected to the network. Consequently, the instance <link linkend='CPLStation-HostAddress'>HostAddress</link>, <link linkend='CPLStation-TxRate'>TxRate</link> and <link linkend='CPLStation-RxRate'>RxRate</link> properties are unreliable. 
				</para>
			</section>
		<section id="CPLStation-NodeAddressString">
			<title>
				CPLStation::NodeAddressString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>NodeAddressString</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the <link linkend='CPLStation-NodeAddress'>NodeAddress</link> property as a <constant>NUL</constant> terminated hexadecimal character string. The string will be <constant>ETHER_ADDR_LEN</constant>*<constant>3</constant> characters long including the terminator. 
				</para>
			</section>
		<section id="CPLStation-PrefaceString">
			<title>
				CPLStation::PrefaceString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>PrefaceString</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the station preface as a string. The station preface is a single-line title for the output produced printed by the <link linkend='CPLStation-Print'>Print</link> method. The only purpose it serves is to indicate the significance of each output field. Although shwn as a property, the string is implemented as a constant so parenthesis are omitted when referencing it. The string looks like this:
				</para>
<screen>
P/L NET TEI ------ MAC ------ ------ BDA ------  TX  RX CHIPSET FIRMWARE
</screen>
			</section>
		<section id="CPLStation-RoleName">
			<title>
				CPLStation::RoleName
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>RoleName</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the <acronym>AVLN</acronym> station role as a <constant>NUL</constant> terminated character string. The string <constant>"STA"</constant> means the station is an ordinary station. The string <constant>"CCO"</constant> means the station is the Central Co-ordinator. See the <citetitle>HomePlug AV Specification</citetitle> for an explanation of station roles.
				</para>
			</section>
		<section id="CPLStation-RoleType">
			<title>
				CPLStation::RoleType
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>RoleType</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the <acronym>AVLN</acronym> station role as an unsigned integer. The value <constant>0</constant> means the station is an oridnary station (<acronym>STA</acronym>). The value <constant>1</constant> means the station is the Central Co-ordinator (<acronym>CCo</acronym>). See the <citetitle>HomePlug AV Specification</citetitle> for an explanation of station roles.
				</para>
			</section>
		<section id="CPLStation-RxRate">
			<title>
				CPLStation::RxRate
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>RxRate</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the station receive PHY rate in megabits per second as an unsigned integer. The receive rate applies only to traffic transmitted by this station to the reference station. It is the same as the <varname>AVGRX</varname> field in the <varname>VS_NW_INFO</varname> managment message described in the <citetitle>Firmware Technical Reference Manual</citetitle>. 
				</para>
			</section>
		<section id="CPLStation-StationID">
			<title>
				CPLStation::StationID
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>StationID</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the <acronym>AVLN</acronym> station number. The station number is the same as the <varname>TEI</varname> field of the <varname>VS_NW_INFO</varname> management message described in the <citetitle>Firmware Technical Reference Manual</citetitle>. Every station on an <acronym>AVLN</acronym> has a unique station number.
				</para>
			</section>
		<section id="CPLStation-TxRate">
			<title>
				CPLStation::TxRate
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>TxRate</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the station transmit PHY rate in megabits per second as an unsigned integer. The transmit rate applies only to traffic received by this this station from the reference station. It is the same as the <varname>AVGTX</varname> field in the <varname>VS_NW_INFO</varname> managment message described in the <citetitle>Firmware Technical Reference Manual</citetitle>. 
				</para>
			</section>
		</section>
	<section id="CPLStation-methods">
		<title>
			Methods
			</title>
		<para>
			This class inherits no methods.
			</para>
		<section id="CPLStation-Preface">
			<title>
				CPLStation::Preface
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLStation &amp; <function>Preface</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Print the <link linkend='CPLStation-PrefaceString'>PrefaceString</link> on stdout followed by a newline. This method is optional but may be called prior to printing station details. Sample output follows.
				</para>
			</section>
		<section id="CPLStation-Print">
			<title>
				CPLStation::Print
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLStation &amp; <function>Print</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Print class properties in a human readable format on stdout. Example output follows. The fields show local or remote connection,  station or CCo status,  station hardware address,  bridged device hardware address,  transmit PHY rate,  receive PHY rate,  hardware type and firmware revision.
				</para>
<screen>
REM STA 002 00:B0:52:DE:AD:01 00:07:E9:F6:42:51 145 147 INT6000 INT6000-MAC-4-1-4101-00-3646-20090615-BETA1-B
</screen>
			</section>
		</section>
	<section id="CPLStation-Constructors">
		<title>
			Constructors
			</title>
		<para>
			</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef><function>CPLStation</function></funcdef>
				<paramdef>void</paramdef>
				</funcprototype>
			</funcsynopsis>
		<para>
			Instantiates the class as an empty powerline station. Class <link linkend='CPLNetwork'>CPLNetwork</link> instantiates this class and initializes class properties. 
			</para>
		</section>
	<section id="CPLStation-examples">
		<title>
			Examples
			</title>
		<para>
			None.
			</para>
		</section>
	</chapter>