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

<chapter id='oethernet'>
	<title>
		Class oethernet
		</title>
	<section id="oethernet-class" >
		<title>
			Introduction
			</title>
		<para>
			This class implements an Ethernet header encoder/decoder. When instantiated, it provides access to Ethernet header source,  destination and protocol fields in binary and string format. Class methods may be used to encode/decode or import/export a complete Ethernet header or individual header fields that are stored in external memory in network byte order. This is the base class for the <link linkend='ohomeplug'>ohomeplug</link> and <link linkend='ointellon'>ointellon</link> classes.
			</para>
		<para>
			Encode and export methods write class properties to external memory in network byte order. Decode and import methods read class properties from external memory in network byte order. Encode and decode methods always return the next unencoded or undecoded memory byte. Import and Export methods always return the object instance reference allowing class methods to be chained. 
			</para>
		<para>
			The <link linkend='oethernet-Protocol'>Protocol</link> property and <link linkend='oethernet-SetProtocol'>SetProtocol</link> method perform implicit integer host-to-network and network-to-host byte ordering. 
			</para>
		<para>
			This class is declared in <ulink url='oethernet.hpp.html'>oethernet.hpp</ulink> and defined in <ulink url='oethernet.cpp.html'>oethernet.cpp</ulink>.
			</para>
		<section id="oethernet-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				None.
				</para>
			</section>
		<section id="oethernet-dependence">
			<title>
				Dependence
				</title>
			<para>
				This class references static class <link linkend='omemory'>omemory</link> to manipulate memory.
				</para>
			<para>
				This class references Ethernet related constants defined in header file <filename>net/ethernet.h</filename> which should be available on most systems. An abridged version is provided in <ulink url='ethernet.h.html'>VisualStudioNET/include/net/ethernet.h</ulink> for systems that may not have it.
				</para>
			</section>
		</section>
	<section id="oethernet-properties">
		<title>
			Properties
			</title>
		<para>
			</para>
		<section id="oethernet-BroadcastAddress">
			<title>
				oethernet::BroadcastAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>const uint8_t * <function>BroadcastAddress</function></funcdef>
    					<paramdef></paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the standard Ethernet broadcast address as a constant 48-bit integer in network byte order. The value is <constant>FF:FF:FF:FF:FF:FF</constant> and the length is <constant>ETHER_ADDR_LEN</constant> bytes. Although shown here as a property, this is implemented as a constant. Parentheses are omitted when referencing it.
				</para>
			</section>
		<section id="oethernet-HeaderLength">
			<title>
				oethernet::HeaderLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>HeaderLength</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the Ethernet header length in bytes. The header length is the sum of the Ethernet <link linkend='oethernet-PeerAddress'>PeerAddress</link>, <link linkend='oethernet-HostAddress'>HostAddress</link> and <link linkend='oethernet-Protocol'>Protocol</link> lengths. For practical purposes, this property is a constant but should the <acronym>VLAN</acronym> tag be added then the length will change. Use this property to allocate buffer space in application programs.  
				</para>
			</section>
		<section id="oethernet-HostAddress">
			<title>
				oethernet::HostAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>const uint8_t * <function>HostAddress</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the host hardware address as a byte array in network byte order. The length is <constant>ETHER_ADDR_LEN</constant> bytes. The host hardware address is the same as the <varname>OSA</varname> field described in the <citetitle>HomePlug AV Specification</citetitle> and <citetitle>Firmware Technical Reference Manual</citetitle>. On instantiation, this property contains zeros. 
				</para>
			</section>
		<section id="oethernet-HostAddressString">
			<title>
				oethernet::HostAddressString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>const char * <function>HostAddressString</function></funcdef>
					<paramdef>void</paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the host hardware address as a string. The length is <constant>ETHER_ADDR_LEN</constant>*<constant>3</constant> characters long including the <constant>NUL</constant> terminator. It may be used anywhere a <constant>NUL</constant> terminated string is expected. The string is formatted as a colon-separated, hexadecimal octets, as in <quote>00:B0:52:BA:BE:15</quote>.
				</para>
			</section>
		<section id="oethernet-PeerAddress">
			<title>
				oethernet::PeerAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>const uint8_t * <function>PeerAddress</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the peer hardware address as a byte array in network byte order. The length is in <constant>ETHER_ADDR_LEN</constant> bytes. The peer hardware address is the same as the <varname>ODA</varname> field described in the <citetitle>HomePlug AV Specification</citetitle> and <citetitle>Firmware Technical Reference Manual</citetitle>. On instantiation, this property contains zeros. 
				</para>
			</section>
		<section id="oethernet-PeerAddressString">
			<title>
				oethernet::PeerAddressString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>const char * <function>PeerAddressString</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the peer address as a string. The length is <constant>ETHER_ADDR_LEN</constant>*<constant>3</constant> characters long including the <constant>NUL</constant> terminator. It may be used anywhere a <constant>NUL</constant> terminated string is expected. The string is formatted as a colon-separated, hexadecimal octets, as in <quote>00:B0:52:DE:AD:99</quote>.
				</para>
			</section>
		<section id="oethernet-Protocol">
			<title>
				oethernet::Protocol
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>uint16_t <function>Protocol</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the Ethernet protocol as a 16-bit integer in host byte order. The Ethernet protocol is the same as the <varname>MTYPE</varname> field described in the <citetitle>HomePlug AV Specification</citetitle> and <citetitle>Firmware Technical Reference Manual</citetitle>. On instantiation, this property is <constant>0x0000</constant>. 
				</para>
			</section>
		<section id="oethernet-ProtocolString">
			<title>
				oethernet::ProtocolString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>ProtocolString</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the Ethernet protocol as a string. The length is <constant>ETHER_TYPE_LEN</constant>*<constant>3</constant> characters long including the <constant>NUL</constant> terminator. It is formatted as colon-seperated, hexadecimal octets, as in <constant>88:E1</constant>. 
				</para>
			</section>
		</section>
	<section id="oethernet-methods">
		<title>
			Methods
			</title>
		<para>
			</para>
		<section id="oethernet-ExportHeader">
			<title>
				oethernet::ExportHeader
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void * <function>ExportHeader</function></funcdef>
   					<paramdef>void * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Encode external memory with an Ethernet header and return the address of the next unencoded memory byte.  No length argument is required. The number of bytes encoded will be <link linkend='oethernet-HeaderLength'>HeaderLength</link>. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent export operations. The encoded header will include the <link linkend='oethernet-PeerAddress'>PeerAddress</link>, <link linkend='oethernet-HostAddress'>HostAddress</link> and <link linkend='oethernet-Protocol'>Protocol</link>. Instance properties are not modified by this operation. 
				</para>
			</section>
		<section id="oethernet-ExportHostAddress">
			<title>
				oethernet::ExportHostAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void * <function>EncodeHostAddress</function></funcdef>
   					<paramdef>void * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the host hardware address to external memory in binary format. Return the address of the next uncopied memory byte. No length argument is required. The host hardware address is <constant>ETHER_ADDR_LEN</constant> bytes. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent export operations. 
				</para>
			</section>
		<section id="oethernet-ExportPeerAddress">
			<title>
				oethernet::ExportPeerAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void * <function>ExportPeerAddress</function></funcdef>
   					<paramdef>void * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the peer hardware address to external memory in binary format. Return the address of the next uncopied memory byte. No length argument is required. The peer hardware address is <constant>ETHER_ADDR_LEN</constant> bytes. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent export operations.  
				</para>
			</section>
		<section id="oethernet-ExportProtocol">
			<title>
				oethernet::ExportProtocol
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void * <function>ExportProtocol</function></funcdef>
   					<paramdef>void * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the Ethernet protocol to external memory in network byte order. Return the address of the next uncopied byte. No length argument is required. The Ethernet protocol is <constant>ETHER_TYPE_LEN</constant> bytes. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent export operations. 
				</para>
			</section>
		<section id="oethernet-ImportHeader">
			<title>
				oethernet::ImportHeader
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void const * <function>ImportHeader</function></funcdef>
   					<paramdef>void const * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Decode external memory containing an Ethernet header. Return the address of the next undecoded memory byte. No length argument is needed. The number of bytes decoded will be <link linkend='oethernet-HeaderLength'>HeaderLength</link>. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent import operations. External memory is unpacked and stored in the <link linkend='oethernet-PeerAddress'>PeerAddress</link>, <link linkend='oethernet-HostAddress'>HostAddress</link> and <link linkend='oethernet-Protocol'>Protocol</link> properties. External memory is not modified by this operation. 			
				</para>
			</section>
		<section id="oethernet-ImportHostAddress">
			<title>
				oethernet::ImportHostAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void const * <function>ImportHostAddress</function></funcdef>
   					<paramdef>void const * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the host hardware address from external memory in binary format. Return the address of the next uncopied memory byte. No length argument is needed. The host hardware address is <constant>ETHER_ADDR_LEN</constant> bytes. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent import operations. 
				</para>
			</section>
		<section id="oethernet-ImportPeerAddress">
			<title>
				oethernet::ImportPeerAddress
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void const * <function>ImportPeerAddress</function></funcdef>
   					<paramdef>void const * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the peer hardware address from external memory in binary format. Return the address of the next uncopied memory byte. No length argument is required. The host hardware address is <constant>ETHER_ADDR_LEN</constant> bytes. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent import operations.
				</para>
			</section>
		<section id="oethernet-ImportProtocol">
			<title>
				oethernet::ImportProtocol
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void const * <function>ImportProtocol</function></funcdef>
   					<paramdef>void * <parameter>memory</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Copy the Ethernet protocol from external memory in binary format. Return the address of the next uncopied memory byte. No length argument is required. The Ethernet protocol is <constant>ETHER_TYPE_LEN</constant> bytes. The <varname>memory</varname> address is incremented by that amount and returned as the method value for use in subsequent import operations.
				</para>
			</section>
		<section id="oethernet-Print">
			<title>
				oethernet::Print
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oethernet &amp; <function>Print</function></funcdef>
   					<paramdef>void</paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Print the Ethernet header on stdout in human-friendly format.
				</para>
			</section>
		<section id="oethernet-SetProtocol">
			<title>
				oethernet::SetProtocol
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>oethernet &amp; <function>SetProtocol</function></funcdef>
   					<paramdef>uint16_t <parameter>protocol</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Specify the Ethernet protocol as an integer in host byte order. The protocol is stored internally in network byte order.
				</para>
			</section>
		</section>
	<section id="oethernet-constructors">
		<title>
			Constructors
			</title>
		<funcsynopsis>
			<funcprototype>
  				<funcdef><function>oethernet</function></funcdef>
   				<paramdef>void</paramdef>
   				</funcprototype>
			</funcsynopsis>
		<para>
			Initialize all properties to <constant>0</constant>.
			</para>
		<funcsynopsis>
			<funcprototype>
  				<funcdef><function>oethernet</function></funcdef>
   				<paramdef>uint16_t <parameter>protocol</parameter></paramdef>
   				</funcprototype>
			</funcsynopsis>
		<para>
			Initialize the <link linkend='oethernet-PeerAddress'>PeerAddress</link> and <link linkend='oethernet-HostAddress'>HostAddress</link> properties to <constant>0</constant> and the <link linkend='oethernet-Protocol'>Protocol</link> property to <varname>protocol</varname>.
			</para>
		</section>
	<section id="oethernet-examples">
		<title>
			Examples
			</title>
		<para>
			There are several ways to use this class. One way is to set class properties and then export them to external memory. The other way is to import class properties from external memory and inspect them.
			</para>
		<example>
			<title>
				Encoding an Ethernet Header
				</title>
<programlisting>
oethernet <varname>header</varname>; 
byte <varname>hostaddress </varname>[] = { 0x00, 0xC7, 0x43, 0xDE, 0xAD, 0x02 }
byte <varname>framebuffer</varname> [<constant>ETHER_MAX_LEN</constant>];
byte <varname>framepointer</varname>; 
<varname>header</varname>.<function>ImportHostAddress </function>(oethernet::<constant>BroadcastAddress</constant>); 
<varname>header</varname>.<function>ImportPeerAddress </function>(<varname>hostaddress</varname>);
<varname>framepointer</varname> = <varname>header</varname>.<function>ExportHeader </function>(<varname>framebuffer</varname>); 
</programlisting>
			<para>
				This example instantiates an oethernet <varname>header</varname> and allocates a <varname>hostaddress</varname> buffer and an empty Ethernet <varname>framebuffer</varname>. It then invokes the class <link linkend='oethernet-ImportHostAddress'>ImportHostAddress</link> method to copy class constant <link linkend='oethernet-BroadcastAddress'>Broadcast</link> into the header source address property and the <link linkend='oethernet-ImportPeerAddress'>ImportPeerAddress</link> method to copy the <varname>hostaddress</varname> value into the header destination address property. Finally, it invokes the <link linkend='oethernet-ExportHeader'>ExportHeader</link> method to encode the <varname>framebuffer</varname> with a complete Ethernet header. The <varname>framepointer</varname> now points to the next unencode <varname>framebuffer</varname> address which is the start of the Ethernet frame body.
				</para>
			</example>
		<example>
			<title>
				Decoding an Ethernet Header
				</title>
<programlisting>
oethernet <varname>header</varname>; 
byte <varname>framebuffer</varname> [<constant>ETHER_MAX_LEN</constant>];
...
(fill the frame buffer with a valid Ethernet frame)
...
<varname>header</varname>.<function>Print</function> (); 
<varname>header</varname>.<function>ImportHeader</function> (<varname>framebuffer</varname>); 
<varname>header</varname>.<function>Print</function>(); 
</programlisting>
		<para>
			This example instantiates an oethernet <varname>header</varname> and allocates a <varname>framebuffer</varname>. Assuming that <varname>framebuffer</varname> contains a valid Ethernet frame from somewhere, it invokes the class <link linkend='oethernet-Print'>Print</link> method to print the contents of <varname>header</varname> then invokes the <link linkend='oethernet-ImportHeader'>ImportHeader</link> methoc to load the header portion of <varname>framebuffer</varname> in <varname>framebuffer</varname> then invokes the <link linkend='oethernet-Print'>Print</link> method again. This gives us a <quote>before</quote> and <quote>after</quote> picture of <varname>header</varname> content which illustrates frame decode functionality.
			</para>
			</example>
		</section>
	</chapter>