This class implements the low-level, Layer 2 Ethernet interface for powerline network device management. A typical sequence of management events involves selecting the host interface, discovering local and remote powerline network bridges and exchanging messages with them. This class includes most properties and methods needed to perform Layer 2 Ethernet communications. Class defaults are set for Atheros vendor specific management messages. The application must allocate, encode and decode the Ethernet frames that are sent and received using this class. The application must also derive the powerline network topology from the Bridges and Neighbors methods which are included for convenience. This class includes a template Ethernet header. Experience has shown that outgoing frame headers are basically static, except for the peer address. The host address and protocol do not change often and both these values are used to filter incoming frames. To minimize duplication of information, the values are all co-located here. This takes some getting-used-to but it makes logistical sense. This class is declared in CPLChannel.hpp and defined in CPLChannel.cpp.

This class inherits the oflagword class to implement the channel flagword. All public flagword properties and methods are accessible to applications. This class inherits the oethernet class to implemment a template Ethernet header. All public Ethernet header properties and methods are accessible to applications. This class inherits the ointerface class to implement the channel Ethernet interface. All public class properties and methods are accessible to applications.

This class references static class omemory to print outgoing and incoming frames. This class references static class oerror to report errors.

Class properties include all oflagword, oethernet and ointerface properties plus those described below.

unsigned Timeout void Return the channel timeout value.

Class methods include all oflagword, oethernet and ointerface methods plus those described below.

signed Bridges void * memory size_t extent Encode memory with a list of local stations connected directly to the channel interface over Ethernet. Return the number of bridge stations detected. Detected stations are stored in memory as a series of consecutive Ethernet hardware addresses where each address is ETHER_ADDR_LEN bytes. Argument extent specifies the size of memory in bytes. The return value is the number of consecutive addresses stored in memory. A return value of -1 indicates insufficient memory to store all detected bridge stations.

signed Neighbors void * memory size_t extent Encode memory with a list of stations connected to some reference station over powerline or coax. Return the number of neighbor stations detected. The reference station is identified by the instance PeerAddress property when this method is called. The reference station is excluded from the list. Detected stations are stored in memory as a series of consecutive Ethernet hardware addresses where each address is ETHER_ADDR_LEN bytes. Argument extent specifies the size of memory in bytes. The return value is the number of consecutive addresses stored in memory. A return value of -1 indicates insufficient memory to store all detected neighbor stations. This method is provided in this class for convenience. Use the CPLNetwork class to obtain detailed information about local and remote network bridges.

signed ReadMessage void const * memory signed extent Receive an Ethernet frame through the channel interface. Return the number of bytes received. Return -1 on error, 0 on timeout. On success, the return value will often be less than extent. Incoming frames are filtered. Only valid HomePlug AV frames that are addressed to the host will be returned by this method.

signed SendMessage void const * memory signed extent Transmit an Ethernet frame through the channel interface. Return the number of bytes transmitted. Return -1 on error, 0 on timeout. On success, the return value will equal extent. Outgoing frames are not filtered. Any valid Ethernet frame may be passed to this method.

CPLChannel unsigned ifindex Open a raw Ethernet socket, bind it to the numbered interface and activate packet filters. Terminate the application if the socket cannot be opened or the interface does not exist or cannot be accessed. Do not use this constructor unless you are sure that the interface exists and is available. The socket is closed and the interface is released by the class destructor. CPLChannel const char * ifname Open a raw Ethernet socket, bind it to the named interface and activate packet filters. Terminate the application if the socket cannot be opended or the interface does not exist or cannot be accessed. Do not use this constructor unless you are sure that the interface exists. The socket is closed and the interface is released by the class destructor.

CPLChannel channel ("eth2"); byte bridgelist [255][ETHER_ADDR_LEN]; signed bridges = channel.Bridges (bridgelist, sizeof (bridgelist)); signed bridge = 0; while (bridge < bridges) { do something with bridgelist [bridge]; bridge++; } This example instantiates channel with interface name "eth2". It then allocates bridgelist to allow a maximum of 255 possible hardware device addresses. Integer bridges is initialized to the number of detected bridges by the Bridges method. Integer bridge is the used to iterate through bridgelist. Normally there will be one powerline bridge connected to a given host interface but there could be more connected through a network switch or hub. Each local bridge can support an seperate powerline network consisting of other, remote powerline bridges. Consequently, we must ask each local bridge, in turn, to list any remote powerline devices. CPLChannel channel (3); byte bridgelist [255][ETHER_ADDR_LEN]; byte devicelist [255][ETHER_ADDR_LEN] signed bridges = channel.Bridges (bridgelist, sizeof (bridgelist)); signed devices; signed bridge = 0; signed device = 0; while (bridge < bridges) { channel.ImportPeerAddress (bridgelist [bridge]) devices = channel.Neighbors (devicelist, sizeof(devicelist)); while (device < devices) { do something with devicelist [device]; device++; } bridge++; } The example above instantiates channel with interface number 3, this time. It allocates bridgelist and devicelist to allow a maximum of 255 possible hardware device addresses each. Integer bridges is initialized and bridgelist is searched (as before). The ImportPeerAddress method is called to establish each bridge as the destination address before calling the Neighbors method to find neighboring powerline devices. The list of all channel bridges and their neighbors forms a complete list of powerline devices that are accessible via the channel interface. Such a list can be used to populate drop-down menus for GUI applications. The two operations of finding bridges and finding neighbors are kept seperate for reasons that may not be obvious at first.