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

<chapter id='CPLMessage'>
	<title>
		Class CPLMessage
		</title>
	<section id="CPLMessage-class">
		<title>
			Introduction
			</title>
		<para>
			This class implements a lookup table for Atheros vendor-specific management messages and their error codes.
			</para>
		<para>
			Messages types are stored in the <varname>MMTYPE</varname> field of all HomePlug AV management messages. This class can be used to convert any HomePlug AV message type, including Atheros vendor-specific message types, to the formal mnemonic (name) for that message type. This can be used for debugging and event logging purposes.
			</para>
		<para>
			Error codes are stored in the <varname>MSTATUS</varname> field of many Atheros vendor-specific confirmation messages. This class can be used to obtain the message text for any valid combination of Atheros vendor-specific message type and error code found in a confirmation message frame. This can be used to report powerline management error conditions in human-friendly format.
			</para>
		<para>
			In addition, this class can be used to print <acronym>CVS</acronym> or <acronym>HTML</acronym> tables of message mnemonics, message types, error codes and error text. This optional feature may be useful for application and system developers who must frequently diagnose software and hardware problems using hex dumps.
			</para>
		<para>
			This class is declared in <ulink url='CPLMessage.hpp.html'>CPLMessage.hpp</ulink> and defined in <ulink url='CPLMessage.cpp.html'>CPLMessage.cpp</ulink>.
			</para>
		<section id="CPLMessage-inheritance">
			<title>
				Inheritance
				</title>
			<para>
				None.
				</para>
			</section>
		<section id="CPLMessage-dependence">
			<title>
				Dependence
				</title>
			<para>
				None.
				</para>
			</section>
		</section>
	<section id="CPLMessage-properties">
		<title>
			Properties
			</title>
		<para>
			None.
			</para>
		</section>
	<section id="CPLMessage-methods">
		<title>
			Methods
			</title>
		<para>
			</para>
		<section id="CPLMessage-CSV">
			<title>
				CPLMessage::CSV
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLMessage &amp; <function>CSV</function></funcdef>
   					<paramdef>void</paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Print a CSV formatted file on stdout. The output lists the mnemonic, <varname>MMTYPE</varname>, <varname>MSTATUS</varname> and message text of every Atheros vendor-specific management message error recognized by the firmware. The output is suitable for inclusion in a spreadsheet or for processing by another program. The object instance is returned as the method value.
				</para>
			</section>
		<section id="CPLMessage-HTML">
			<title>
				CPLMessage::HTML
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>CPLMessage &amp; <function>HTML</function></funcdef>
  					<paramdef>void</paramdef> 
 					</funcprototype>
				</funcsynopsis>
			<para>
				Print a HTML formatted file on stdout. The output c the name, <varname>MMTYPE</varname>, <varname>MSTATUS</varname> and message text of every Atheros vendor-specific management message error recognized by the firmware. The output is organized as a table and is suitable for inclusion in an ordinary webpage. The object instance is returned as the method value.
				</para>
			</section>
		<section id="CPLMessage-MessageErrorText">
			<title>
				CPLMessage::MessageText
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>MessageErrorText</function></funcdef>
    					<paramdef>uint16_t <parameter>type</parameter></paramdef> 
   					<paramdef>uint8_t <parameter>code</parameter></paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the error message text for a given Atheros vendor-specific management message type and error code as a constant character string or <constant>"Failed"</constant> for an invalid combination of the two. Argument <varname>type</varname> is the <varname>MMTYPE</varname> field and <varname>code</varname> is the <varname>MSTATUS</varname> field described in the <citetitle>Atheros Firmware Technical Reference Manual</citetitle>. For this method, <varname>type</varname> must be a confirmation message type. 
				</para>
			</section>
		<section id="CPLMessage-MessageMode">
			<title>
				CPLMessage::MessageMode
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>MessageMode</function></funcdef>
    					<paramdef>uint16_t <parameter>type</parameter></paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the variant of a given message <varname>type</varname> as a const character string. The four possible variants are <constant>"REQ"</constant>, <constant>"CNF"</constant>, <constant>"IND"</constant> and <constant>"RSP"</constant> to indicate a request, confirmation,  indication or response. This method examines only the lower two bits of <varname>type</varname> and ingnores the remainder.  See the <citetitle>HomePlug AV Specification</citetitle> for more information on message variants.
				</para>
			</section>
		<section id="CPLMessage-MessageName">
			<title>
				CPLMessage::MessageName
				</title>
			<funcsynopsis>
				<funcprototype>
  					<funcdef>char const * <function>MessageName</function></funcdef>
    					<paramdef>uint16_t <parameter>type</parameter></paramdef> 
					</funcprototype>
				</funcsynopsis>
			<para>
				Return the formal HomePlug AV or Atheros vendor-specific mnemonic (name) for a given management message type as a constant character string or <constant>"UNKNOWN_MME"</constant> for an invalid message type. Argument <varname>type</varname> is the <varname>MMTYPE</varname> field as described in the <citetitle>HomePlug AV Specification</citetitle> or <citetitle>Atheros Firmware Technical Reference Manual</citetitle>. The lower order two bits of <varname>type</varname> are ignored during lookup so that request, confirmation, indication or response message variants all return the same string.
				</para>
			</section>
		</section>
	<section id="CPLMessage-operators">
		<title>
			Operators
			</title>
		<para>
			None.
			</para>
		</section>
	<section id="CPLMessage-constructors">
		<title>
			Constructors
			</title>
		<para>
			</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef><function>CPLMessage</function></funcdef>
				<paramdef>void</paramdef>
				</funcprototype>
			</funcsynopsis>
		<para>
			</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef><function>CPLMessage</function></funcdef>
				<paramdef>void</paramdef>
				</funcprototype>
			</funcsynopsis>
		<para>
			</para>
		</section>
	<section id="CPLMessage-examples">
		<title>
			Examples
			</title>
		<para>
			To be written.
			</para>
		<example>
			<title>
				Display Message Name
				</title>
<programlisting>
	CPLMessage <varname>message</varname>;
	uint16_t <varname>mmtype</varname> = <constant>0xA001</constant>; 
	std::cout "Message type is " &lt;&lt; <varname>message</varname>.<function>MessageName</function> (<varname>mmtype</varname>) &lt;&lt; "." &lt;&lt; <varname>message</varname>.<function>MessageMode</function> (<varname>mmtype</varname>) &lt;&lt; std::endl;   
</programlisting>
			<para>
				This example uses methods <function>MessageName</function> and <function>MessageMode</function> to lookup then print the full mnemonic for Atheros vendor-specific message type <constant>0xA001</constant> on stdout. The output looks like ...
				</para>
<screen>
Message type is VS_SW_VER.CNF
</screen>
			</example>
		</section>
	</chapter>