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

<chapter id='ohomeplug'>
	<title>
		Class ohomeplug
		</title>
	<section id="ohomeplug-class">
		<title>
			Introduction
			</title>
		<para>
			This class implements a HomePlug AV message header encoder/decoder. When instantiated, it provides access the Ethernet header plus the HomePlug AV version and message type field. Class methods may be used to encode/decode or import/export a complete header or individual header fields stored in external memory in proper byte order. 
			</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='ohomeplug-MessageType'>MessageType</link> property and <link linkend='ointellon-SetMessageType'>SetMessageType</link> method perform implicit integer host-to-little-endian and little-endian-to-host conversion. 
			</para>
		<para>
			This class is declared in <ulink url='ohomeplug.hpp.html'>ohomeplug.hpp</ulink> and defined in <ulink url='ohomeplug.cpp.html'>ohomeplug.cpp</ulink>.
			</para>
		<section id="ohomeplug-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				This class inherits the <link linkend='oethernet'>oethernet</link> class to implement the ethernet header portion of the message.
				</para>
			</section>
		<section id="ohomeplug-dependence">
			<title>
				Dependence
				</title>
			<para>
				This class references static class <link linkend='omemory'>omemory</link> to manipulate memory.
				</para>
			</section>
		</section>
	<section id="ohomeplug-properties">
		<title>
			Properties
			</title>
		<para>
			Class properties include all <link linkend='oethernet-properties'>oethernet</link> properties plus those described below.
			</para>
		<section id="ohomeplug-HeaderLength">
			<title>
				ohomeplug::HeaderLength
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>unsigned <function>HeaderLength</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return HomePlug AV header length in bytes. The header length includes the Ethernet <link linkend='oethernet-HeaderLength'>HeaderLength</link> plus the HomePlug <link linkend='ohomeplug-MessageVersion'>MessageVersion</link> and <link linkend='ohomeplug-MessageType'>MessageType</link> lengths. Use this property to allocate buffer space in application programs. 
				</para>
			</section>
		<section id="ohomeplug-MessageType">
			<title>
				ohomeplug::MessageType
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>uint16_t <function>MessageType</function></funcdef>
					<paramdef>void</paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the HomePlug AV message type as an integer in host byte order. This property is the same as the <varname>MMTYPE</varname> field described in the <citetitle>HomePlug AV Specification</citetitle>. On instantiation, this property contains <constant>oHOMEPLUG_MMTYPE</constant>, as defined in <ulink url='ohomeplug.hpp.html'>ohomeplug.hpp</ulink>. 

				</para>
			</section>
		<section id="ohomeplug-MessageTypeString">
			<title>
				ohomeplug::MessageTypeString
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>uint16_t <function>MessageTypeString</function></funcdef>
					<paramdef>void</paramdef>
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the HomePlug AV message type as a string. The string is <constant>6</constant> characters long including the <constant>NUL</constant> terminator. 
				</para>
			</section>
		<section id="ohomeplug-MessageVersion">
			<title>
				ohomeplug::MessageVersion
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>uint8_t <function>MessageVersion</function></funcdef>
    					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the HomePlug AV message version as an integer. The message version indicates the revision of the <citetitle>HomePlug AV Specification</citetitle> that describes the message format. On instantiation, this property contains <constant>oHOMEPLUG_MMV</constant>,  as defined in header file <ulink url='ohomeplug.hpp'>ohomeplug.hpp</ulink>. 
				</para>
			</section>
		</section>
	<section id="ohomeplug-methods">
		<title>
			Methods
			</title>
		<para>
			Class methods include all <link linkend='oethernet-methods'>oethernet</link> methods plus those described below.
			</para>
		<section id="ohomeplug-ImportHeader">
			<title>
				ohomeplug::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 and HomePlug AV specific header. Return the address of the next undecoded memory byte. Header fields are unpacked and stored in their respective properties. External memory is not changed by this operation.
 The number of bytes decoded will equal the <link linkend='ohomeplug-HeaderLength'>HeaderLength</link> property. Consequently, the memory address returned will be incremented by that amount and may be used for subsequent decoding operations. 
				</para>
			</section>
		<section id="ohomeplug-ExportHeader">
			<title>
				ohomeplug::ExportHeader
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>void * <function>ExportHeader</function></funcdef>
   					<paramdef>void * <parameter>memory</parameter> </paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Encode external memory with a complete HomePlug AV header. Return the address of the next unencoded byte.  The encoded memory will contain the Ethernet header plus the HomePlug AV specific <link linkend='ohomeplug-MessageVersion'>MessageVersion</link> and <link linkend='ohomeplug-MessageType'>MessageType</link>. Instance property values are not changed by the operation. The number of bytes encoded will equal the <link linkend='ohomeplug-HeaderLength'>HeaderLength</link> property. Consequently, the memory address returned will incremented by that amount and may be used for subsequent encoding operations. 
				</para>
			</section>
		<section id="ohomeplug-SetMessageVersion">
			<title>
				ohomeplug::SetMessageVersion
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>ohomeplug &amp; <function>SetMessageVersion</function></funcdef>
   					<paramdef>uint8_t <parameter>version</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Assign a new value to the message version.
				</para>
			</section>
		<section id="ohomeplug-SetMessageType">
			<title>
				ohomeplug::SetMessageType
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>ohomeplug &amp; <function>SetMessageType</function></funcdef>
   					<paramdef>uint16_t <parameter>message</parameter></paramdef>
   					</funcprototype>
				</funcsynopsis>
			<para>
				Specify the HomePlug AV message type as an integer in host byte order. The message type is stored internally in little-endian order. Valid HomePlug AV message types are <constant>0x0000</constant> through <constant>0x9FFC</constant> but this method does not validate the argument so any 16-bit value is permitted. 
				</para>
			</section>
		<section id="ohomeplug-Print">
			<title>
				ohomeplug::Print
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>ohomeplug &amp; <function>Print</function></funcdef>
					<paramdef>void</paramdef>
					</funcprototype>
					</funcsynopsis>
			<para>
				Print the HomePlug AV header on stdout in human-friendly format.
				</para>
			</section>
		</section>
	</chapter>