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

<chapter id='CPLNetwork'>
	<title>
		Class CPLNetwork
		</title>
	<section id="CPLNetwork-class">
		<title>
			Introduction
			</title>
		<para>
			This class implements a HomePlug AV network as a collection of powerline stations. The network is characterized by interrogating a reference station with a <varname>VS_NW_INFO</varname> message then interrogating each network neighbor with a <varname>VS_SW_VER</varname> message. Class properties, methods and operators are used to iterate through the collection and obtain copies of individual station instances. Station instances are implemented using the <link linkend='CPLStation'>CPLStation</link> class.
			</para>
		<para>
			The <citetitle>HomePlug AV Specification</citetitle> assigns special meaning to the term <quote>station</quote> but this class considers all powerline devices to be stations. The central coordinator and proxy coordinator is merely a special kind of station.  
			</para>
		<para>
			The first station in the collection is always the one specified by the <link linkend='CPLChannel'>CPLChannel</link> instance used to instantiate the <link linkend='CPLNetwork-constructors'>CPLNetwork</link> instance. The remaining stations can appear in any order. Applications must iterate through the network to locate the local device or the central coordinator by examining station <link linkend='CPLStation-LinkType'>LinkType</link> and the <link linkend='CPLStation-RoleType'>RoleType</link> properties. 
			</para>
		<para>
			This class is declared in <ulink url='CPLNetwork.hpp.html'>CPLNetwork.hpp</ulink> and defined in <ulink url='CPLNetwork.cpp.html'>CPLNetwork.cpp</ulink>.
			</para>
		<section id="CPLNetwork-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				None.
				</para>
			</section>
		<section id="CPLNetwork-dependence">
			<title>
				Dependence
				</title>
			<para>
				This class uses class <link linkend='CPLChannel'>CPLChannel</link> to identifiy the host interface and powerline device to be interrogated.
				</para>
			<para>
				This class uses class <link linkend='CPLStation'>CPLStation</link> to represent individual powerline devices found on the powerline network.
				</para>
			</section>
		</section>
	<section id="CPLNetwork-properties">
		<title>
			Properties
			</title>
		<para>
			</para>
		<section id="CPLNetwork-Count">
			<title>
				CPLNetwork::Count
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>unsigned <function>Count</function></funcdef>
  					<paramdef>void</paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Return the number of powerline stations detected on the network. This property does not change over the instance lifetime and is the upper bound when iterating through network stations.
				</para>
			</section>
		<section id="CPLNetwork-Empty">
			<title>
				CPLNetwork::Empty
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>bool <function>Empty</function></funcdef>
    					<paramdef>void</paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Return logical <constant>true</constant> if the collection is empty. The collection is empty only if the <link linkend='ointerfaces-Count'>Count</link> property is <constant>0</constant>. An empty collection may indicate that the class was instantiated with an incorrect channel <link linkend='oethernet-PeerAddress'>PeerAddress</link>.
				</para>
			</section>
		<section id="CPLNetwork-End">
			<title>
				CPLNetwork::End
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>bool <function>End</function></funcdef>
    					<paramdef>void</paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Return logical <constant>true</constant> if the collection is exhausted. The collection is exhausted if the <link linkend='CPLNetwork-Index'>Index</link> property equals or exceeds the <link linkend='CPLNetwork-Count'>Count</link> property.
				</para>
			</section>
		<section id="CPLNetwork-Index">
			<title>
				CPLNetwork::Index
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>Index</function></funcdef>
    					<paramdef>void</paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the index of the selected interface. The index ranges from <constant>0</constant> up to (but excluding) the value the <link linkend='CPLNetwork-Count'>Count</link> property. Class <link linkend='CPLNetwork-methods'>methods</link> and <link linkend='CPLNetwork-operators'>operators</link> may be used to alter the value of this property. 				
				</para>
			</section>
		<section id="CPLNetwork-Selected">
			<title>
				CPLNetwork::Selected
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLStation &amp; <function>Selected</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the selected <link linkend='CPLStation'>CPLStation</link> object instance. The selected instance is determined by the <link linkend='CPLNetwork-Index'>Index</link> property. All <link linkend='CPLStation'>CPLStation</link> class constants,  properties, methods and operators are available to the application through this instance.  
				</para>
			</section>
		<section id="CPLNetwork-Station">
			<title>
				CPLNetwork::Station
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLStation &amp; <function>Station</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the selected <link linkend='CPLStation'>CPLStation</link> object instance. This property is the same as the <link linkend='CPLNetwork-Selected'>Selected</link> property.
				</para>
			</section>
		</section>
	<section id="CPLNetwork-methods">
		<title>
			Methods
			</title>
		<para>
			</para>
		<section id="CPLNetwork-Enumerate">
			<title>
				CPLNetwork::Enumerate
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>Enumerate</function></funcdef>
 					<paramdef>void</paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Enumerate network powerline stations on <varname>stdout</varname>. This is equivalent to calling the <link linkend='CPLStation-Print'>Print</link> method for each station in the collection.
				</para>
			</section>
		<section id="CPLNetwork-Select">
			<title>
				CPNetworkn::Select
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>Select</function></funcdef>
   					<paramdef>unsigned <parameter>index</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Select a station by <varname>index</varname>. This sets the <link linkend='CPLNetwork-Index'>Index</link> property and determines the station that will be returned by the <link linkend='CPLNetwork-Selected'>Selected</link> and <link linkend='CPLNetwork-Station'>Station</link> properties. 
				</para>
			</section>
		<section id="CPLNetwork-SelectFirst">
			<title>
				CPLNetwork::SelectFirst
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>SelectFirst</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Set the <link linkend='CPLNetwork-Index'>Index</link> property to <constant>0</constant>.								</para>
			</section>
		<section id="CPLNetwork-SelectFinal">
			<title>
				CPLNetwork::SelectFinal
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>SelectFinal</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Set the <link linkend='CPLNetwork-Index'>Index</link> property to one less than the <link linkend='CPLNetwork-Count'>Count</link> property.
				</para>
			</section>
		<section id="CPLNetwork-SelectNext">
			<title>
				CPLNetwork::SelectNext
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>SelectNext</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Increment the <link linkend='CPLNetwork-Index'>Index</link> property if it is less than the <link linkend='CPLNetwork-Count'>Count</link> property. 
				</para>
			</section>
		<section id="CPLNetwork-SelectPrev">
			<title>
				CPLNetwork::SelectPrev
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>SelectPrev</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Decrement the <link linkend='CPLNetwork-Index'>Index</link> property if it is greater than <constant>0</constant>. 
				</para>
			</section>
		</section>
	<section id="CPLNetwork-operators">
		<title>
			Operators
			</title>
		<section id="CPLNetwork-member">
			<title>
				CPLNetwork::operator []
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLStation &amp; <function>operator []</function></funcdef>
   					<paramdef>unsigned <parameter>index</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Select a network station by index and return an instance of it. This operator has the same effect as calling the <link linkend='CPLNetwork-Select'>Select</link> method with <varname>index</varname> then reading either the <link linkend='CPLNetwork-Selected'>Selected</link> or the <link linkend='CPLNetwork-Station'>Station</link> property.
				</para>
			</section>
		<section id="CPLNetwork-assign">
			<title>
				CPLNetwork::operator =
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>operator =</function></funcdef>
   					<paramdef>unsigned <parameter>index</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Select a network station by network index. This operator has the same effect as the <link linkend='CPLNetwork-Select'>Select</link> method with <varname>index</varname>.
				</para>
			</section>
		</section>
	<section id="CPLNetwork-constructors">
		<title>
			Constructors
			</title>
		<para>
			</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef><function>CPLNetwork</function></funcdef>
				<paramdef>CPLChannel * <parameter>channel</parameter></paramdef>
				</funcprototype>
			</funcsynopsis>
		<para>
			Instantiate a collection of powerline network stations using the specified <varname>channel</varname>. The <varname>channel</varname> <link linkend='oethernet-PeerAddress'>PeerAddress</link> property must contain the Ethernet hardware address of a powerline station that is accessible through the <varname>channel</varname> interface. The reference station is interrogated and the collection is constructed. The collection includes the reference station and all neighbor stations. Class properties and methods are used to iterate through the collection obtain copies of individual stations.
			</para>
		</section>
	<section id="CPLNetwork-examples">
		<title>
			Examples
			</title>
			<para>
				The following example instantiates the <link linkend='CPLNetwork'>CPLNetwork</link> class and prints information about powerline network stations on <varname>stdout</varname> using the <link linkend='CPLNetwork-Enumerate'>Enumerate</link> method.  Several code variations are shown.
				</para>
		<example>
			<title>
				Enumerate Powerline Network Station Details
				</title>
<programlisting>
#if defined (__APPLE__)
        CPLChannel <varname>channel</varname> (<constant>"en0"</constant>);
#elif defined (WINPCAP)
        CPLChannel <varname>channel</varname> (<constant>2</constant>);
#else
        CPLChannel <varname>channel</varname> (<constant>"eth4"</constant>);
#endif
	 byte <varname>device</varname> [] = { <constant>0x00</constant>, <constant>0xB0</constant>, <constant>0x52</constant>, <constant>0xBA</constant>, <constant>0xBE</constant>, <constant>0x05</constant> }
	 <varname>channel</varname>.<function>ImportPeerAddress</function> (<varname>device</varname>)
        CPLNetwork <varname>network</varname> (&amp;<varname>channel</varname>);
        <varname>network</varname>.<function>Enumerate</function> ();
</programlisting>
		<para>
			This example <link linkend="CPLChannel-constructors">instantiates</link> a <varname>channel</varname> using interface <constant>"en0"</constant> on <productname>MAC OSX</productname> systems, interface number <constant>2</constant> on Windows or interface <constant>"eth4"</constant> on other systems. This creates a raw socket on the named interface then gathers information about the interface and the socket. Static interface assignment, such as this, is not recommended because we have no way of knowing if the named or numbered interface will be available on all systems. 
			</para>
		<para>
			The example goes on to define an arbitrary powerline <varname>device</varname> address and assign it to the <varname>channel</varname> using method <link linkend='oethernet-ImportPeerAddress'>ImportPeerAddress</link>. This defines the default peer address for outgoing Ethernet frames. This address remains the default until it is changed. The <varname>channel</varname> <link linkend='oethernet-PeerAddress'>PeerAddress</link>, together with the <varname>channel</varname> <link linkend='oethernet-HostAddress'>HostAddress</link> and <varname>channel</varname> <link linkend='oethernet-Protocol'>Protocol</link> form a template used by other classes to format Ethernet frame headers. 
			</para>
<screen>
 P/L NET TEI ------ MAC ------ ------ BDA ------  TX  RX CHIPSET FIRMWARE
 LOC CCO 001 00:B0:52:BE:EF:04 00:50:04:A5:D8:98 000 000 INT6000 INT6000-MAC-4-0-4011-01-3431-20090519-FINAL-B
 REM STA 002 00:B0:52:DE:AD:01 FF:FF:FF:FF:FF:FF 145 147 INT6000 INT6000-MAC-4-1-4101-00-3646-20090615-BETA1-B
 REM STA 003 00:0B:3B:7F:78:AA FF:FF:FF:FF:FF:FF 000 000 INT6300 INT6000-MAC-4-1-4102-00-3679-20090724-FINAL-B
</screen>
		<para>
			Assuming the <varname>channel</varname> interface is available and the peer address references some powerline device on that interface, we will have a complete list of stations associated with <varname>device</varname>. Method <link linkend='CPLNetwork-Enumerate'>Enumerate</link> merely prints all <varname>network</varname> station details on <varname>stdout</varname> so we can see them. 
			</para>
		<para>
			The <varname>network</varname> and <varname>channel</varname> will close when these objects go <quote>out-of-scope</quote>.
			</para>
			</example>
		<example>
			<title>
				Enumerate Powerline Network Station Details
				</title>
<programlisting>
	if (<varname>network</varname>.<function>Count</function> ())
	{
		<varname>network</varname>.<function>Select</function> (<constant>0</constant>).<function>Selected</function> ().<function>Title</function> (); 
	}
	for (<varname>network</varname>.<function>SelectFirst</function> (); <varname>network</varname>.<function>Index</function> () &lt; <varname>network</varname>.<function>Count</function> (); <varname>network</varname>.<function>SelectNext</function> ())
	{
		<varname>network</varname>.<function>Selected</function> ().<function>Print</function> ();
	}
</programlisting>
		<para>
			This example produces the same output as above by iterating through the powerline <varname>network</varname> stations. The loop shown is basically the same as that used in the <link linkend='CPLNetwork-Enumerate'>Enumerate</link> method.
			</para>
		<para>
			First, if the <varname>network</varname> is not empty then station <constant>0</constant> is arbitratily selected and the station <link linkend='CPLStation-Preface'>Preface</link> method is called to print a heading. This method is cosmetic and optional.  	
			</para>
<screen>
 P/L NET TEI ------ MAC ------ ------ BDA ------  TX  RX CHIPSET FIRMWARE
</screen>
		<para>
			The example then iterates through each <varname>network</varname> station and calls the station <link linkend='CPLStation-Print'>Print</link> method to output station details on <varname>stdout</varname>.
			</para>
<screen>
 LOC CCO 001 00:B0:52:BE:EF:04 00:50:04:A5:D8:98 000 000 INT6000 INT6000-MAC-4-0-4011-01-3431-20090519-FINAL-B
 REM STA 002 00:B0:52:DE:AD:01 FF:FF:FF:FF:FF:FF 145 147 INT6000 INT6000-MAC-4-1-4101-00-3646-20090615-BETA1-B
 REM STA 003 00:0B:3B:7F:78:AA FF:FF:FF:FF:FF:FF 000 000 INT6300 INT6000-MAC-4-1-4102-00-3679-20090724-FINAL-B
</screen>
			<para>
				If this output is not suitable then you can always access the station properties of interest and either use them or display them as needed.
				</para>
			</example>
		</section>
	</chapter>