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

<chapter id='CPLNetworks'>
	<title>
		Class CPLNetworks
		</title>
	<section id="CPLNetworks-class">
		<title>
			Introduction
			</title>
		<para>
			This class represents the powerline networks detected on a given host Ethernet interface. It is implemented as a collection of <link linkend='CPLNetwork'>CPLNetwork</link> objects each of which is a collection of <link linkend='CPLStation'>CPLStation</link> objects. It defines the complete powerline network topology for the interface in one object instance.
			</para>
		<para>
			This class is declared in <ulink url='CPLNetworks.hpp.html'>CPLNetworks.hpp</ulink> and defined in <ulink url='CPLNetworks.cpp.html'>CPLNetworks.cpp</ulink>.
			</para>
		<section id="CPLNetworks-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				None.
				</para>
			</section>
		<section id="CPLNetworks-dependence">
			<title>
				Dependence
				</title>
			<para>
				This class uses class <link linkend='CPLChannel'>CPLChannel</link> to identifiy the host interface,  detected connected bridges and exchange messgaes with those bridges.
				</para>
			<para>
				This class uses class <link linkend='CPLNetwork'>CPLNetwork</link> to represent detected powerline networks.
				</para>
			</section>
		</section>
	<section id="CPLNetworks-properties">
		<title>
			Properties
			</title>
		<para>
			</para>
		<section id="CPLNetworks-Count">
			<title>
				CPLNetworks::Count
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>unsigned <function>Count</function></funcdef>
  					<paramdef>void</paramdef>
  					</funcprototype>
				</funcsynopsis>
			<para>
				Return the number of detected networks detected on the host interface. This property does not change over the instance lifetime and is the upper bound when iterating through networks.
				</para>
			</section>
		<section id="CPLNetworks-Empty">
			<title>
				CPLNetworks::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="CPLNetworks-End">
			<title>
				CPLNetworks::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='CPLNetworks-Index'>Index</link> property equals or exceeds the <link linkend='CPLNetworks-Count'>Count</link> property.
				</para>
			</section>
		<section id="CPLNetworks-Index">
			<title>
				CPLNetworks::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='CPLNetworks-Count'>Count</link> property. Class <link linkend='CPLNetworks-methods'>methods</link> and <link linkend='CPLNetworks-operators'>operators</link> may be used to alter the value of this property. 				
				</para>
			</section>
		<section id="CPLNetworks-Network">
			<title>
				CPLNetworks::Network
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>Network</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the selected <link linkend='CPLNetwork'>CPLNetwork</link> object instance. This property is the same as the <link linkend='CPLNetworks-Selected'>Selected</link> property.
				</para>
			</section>
		<section id="CPLNetworks-Selected">
			<title>
				CPLNetworks::Selected
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>Selected</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the selected <link linkend='CPLNetwork'>CPLNetwork</link> object instance. The selected instance is determined by the <link linkend='CPLNetworks-Index'>Index</link> property. All <link linkend='CPLNetwork'>CPLNetwork</link> class constants,  properties, methods and operators are available to the application through this instance.  
				</para>
			</section>
		</section>
	<section id="CPLNetworks-methods">
		<title>
			Methods
			</title>
		<para>
			</para>
		<section id="CPLNetworks-Enumerate">
			<title>
				CPLNetworks::Enumerate
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &amp; <function>Enumerate</function></funcdef>
 					<paramdef>void</paramdef>
 					</funcprototype>
				</funcsynopsis>
			<para>
				Enumerate detected networks on <varname>stdout</varname>. This is equivalent to calling the <link linkend='CPLStation-Preface'>Preface</link> method then calling the <link linkend='CPLNetwork-Enumerate'>Enumerate</link> method for each network in the collection.
				</para>
			</section>
		<section id="CPLNetworks-Select">
			<title>
				CPLNetworks::Select
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &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='CPLNetworks-Index'>Index</link> property and determines the station that will be returned by the <link linkend='CPLNetworks-Selected'>Selected</link> and <link linkend='CPLNetworks-Network'>Network</link> properties. 
				</para>
			</section>
		<section id="CPLNetworks-SelectFirst">
			<title>
				CPLNetworks::SelectFirst
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &amp; <function>SelectFirst</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Set the <link linkend='CPLNetworks-Index'>Index</link> property to <constant>0</constant>.								</para>
			</section>
		<section id="CPLNetworks-SelectFinal">
			<title>
				CPLNetworks::SelectFinal
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &amp; <function>SelectFinal</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Set the <link linkend='CPLNetworks-Index'>Index</link> property to one less than the <link linkend='CPLNetworks-Count'>Count</link> property.
				</para>
			</section>
		<section id="CPLNetworks-SelectNext">
			<title>
				CPLNetworks::SelectNext
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &amp; <function>SelectNext</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Increment the <link linkend='CPLNetworks-Index'>Index</link> property if it is less than the <link linkend='CPLNetworks-Count'>Count</link> property. 
				</para>
			</section>
		<section id="CPLNetworks-SelectPrev">
			<title>
				CPLNetworks::SelectPrev
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &amp; <function>SelectPrev</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Decrement the <link linkend='CPLNetworks-Index'>Index</link> property if it is greater than <constant>0</constant>. 
				</para>
			</section>
		</section>
	<section id="CPLNetworks-operators">
		<title>
			Operators
			</title>
		<section id="CPLNetworks-member">
			<title>
				CPLNetworks::operator []
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetwork &amp; <function>operator []</function></funcdef>
   					<paramdef>unsigned <parameter>index</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Select a network station and return an instance of it. This operator has the same effect as calling the <link linkend='CPLNetworks-Select'>Select</link> method with <varname>index</varname> then reading either the <link linkend='CPLNetworks-Selected'>Selected</link> or the <link linkend='CPLNetworks-Network'>Network</link> property.
				</para>
			</section>
		<section id="CPLNetworks-assign">
			<title>
				CPLNetworks::operator =
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLNetworks &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='CPLNetworks-Select'>Select</link> method with <varname>index</varname>.
				</para>
			</section>
		</section>
	<section id="CPLNetworks-constructors">
		<title>
			Constructors
			</title>
		<para>
			</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef><function>CPLNetworks</function></funcdef>
				<paramdef>char const * <parameter>ifname</parameter></paramdef>
				</funcprototype>
			</funcsynopsis>
		<para>
			Instantiate a collection of powerline networks on the named host interface. The interface name,  <varname>ifname</varname>,  can be obtained from any <link linkend='ointerface'>ointerface</link> object or from any operating system function designed for that purpose.
			</para>
		</section>
	<section id="CPLNetworks-examples">
		<title>
			Examples
			</title>
			<para>
				The following example enumerates all stations on all networks on all host interfaces.
				</para>
		<example>
			<title>
				Enumerate All Powerline Networks on all Interface
				</title>
<programlisting>
	ointerfaces <varname>interfaces</varname>;
	while (!<varname>interfaces</varname>.<function>End</function> ())
	{
		CPLNetworks * <varname>networks</varname> = new CPLNetworks (<varname>interfaces</varname>.<function>Interface</function> ().<function>Name</function> ());
		<varname>networks</varname>-><function>Enumerate</function> ();
		while (!<varname>networks</varname>-><function>End</function> ())
		{
			<varname>networks</varname>-><function>Selected</function> ().<function>Enumerate</function> ();
			<varname>networks</varname>-><function>SelectNext</function> ();
		}
		delete <varname>networks</varname>;
		<varname>interfaces</varname>.<function>SelectNext</function> ();
	}
  </programlisting>
			<para>
				Each interface name is used to instantiate a new <varname>networks</varname> which is enumerated in two ways. The networks <link linkend='CPLNetworks-Enumerate'>Enumerate</link> methods is used first then each network is enumerated individually. 
				</para>
			</example>
		</section>
	</chapter>