[ch2901] Added documentation for the '%' template constructs, and doc…

…umented

address_map.h.

docs/cyberprobe.texi

@@ -2615,8 +2615,8 @@ If no mask is specified, then this is an exact match against a single address.
 The @code{liid} attribute defines the LIID which will be applied
 if this
 particular IP address is detected.
-@cindex @code{network} attribute, @file{cyberprobe.cfg}
 
+@cindex @code{network} attribute, @file{cyberprobe.cfg}
 The optional @code{network} attribute
 defines the network (ETSI NetworkElementID), which, if specified,
 will be transmitted in the ETSI stream, and delivered as the JSON
@@ -2625,9 +2625,32 @@ The address must be an IP address, and
 not a hostname. The address can be an IPv6 address if the @code{class}
 attribute is included, and set to @code{ipv6}.
 
-LIIDs can occur in multiple places in the target block, but an IP address
+LIIDs can occur in multiple places in the target block, allowing multiple IP
+addresses to match to the same LIID, but the same IP address/mask specifier
 should only occur once in the target block.
 
+If subnetwork ranges overlap, the longest prefix match applies.
+
+The @code{liid} and @code{network} can contain template constructs:
+
+@table @samp
+
+@item %i
+This is replaced with the IP address which causes a match.
+
+@item %m
+This is replaced with the source MAC address in the header of the packet
+which causes a match.
+
+@item %v
+This is replaced with the VLAN ID in the header of the packet which causes
+a match.
+
+@item %%
+This is replaced with a literal @code{%}.
+
+@end table
+
 @cindex @code{certificate}, cyberprobe configuration option
 @cindex @code{key}, cyberprobe configuration option
 @cindex @code{trusted-ca}, cyberprobe configuration option

src/address_map.h

@@ -1,7 +1,31 @@
 
+// Longest-prefix IP address matching.
+//
+// This header provides a template class address_map<A, T> which
+// is used to map addresses of type A to values of type T.  Address masks
+// are used, so that an address of value 1.2.9.12 will match a key of
+// 1.2.0.0/16.  The longest prefix i.e. most specific address always matches
+// first.
+//
+// The only requirement on A is that it supports the '&' operation so that
+// it provides operator&(unsigned int mask) such that for an address of type
+// A, and an unsigned integer value m, A&m returns an address of type
+// A containing only the first m bits of the address.  All other bits are zered.
+
+// e.g.
+//   tcpip::ip4_address addr1("15.12.8.1");
+//   tcpip::ip4_address addr2 = addr1 & 16;
+//   std::string str;
+//   addr2.to_string(str);
+//   assert(str == "15.12.0.0");
+//
+
 #include <map>
 #include <iostream>
 
+#ifndef ADDRESS_MAP_H
+#define ADDRESS_MAP_H
+
 template <class A, class T>
 class address_map {
 
@@ -15,21 +39,25 @@ class address_map {
 
 public:
 
+    // Adds a key to the map, address 'a', mask 'mask', value 't'.
     void insert(const A& a, unsigned int mask, T t) {
 	m[mask][a & mask] = t;
     }
 
+    // Removes a key from the map, address 'a', mask 'mark'.
     void remove(A a, unsigned int mask) {
 	m[mask].erase(a & mask);
     }
 
+    // Searches the map for address 'a'.  If it exists, returns true and
+    // a pointer to the value is returned in 't'.  Otherwise, returns false,
+    // and t is undefined.
     bool get(const A& a, T*& t) {
 
 	typename mask_map::reverse_iterator it;
 
 	for(it = m.rbegin(); it != m.rend(); it++) {
 
-
 	    typename std::map<A, T>::iterator it2;
 
 	    unsigned int mask = it->first;
@@ -54,3 +82,5 @@ class address_map {
 
 };
 
+#endif
+