-- VDR_EPG messages -----------------------------------------------------------

VDR_EPG_DATA:
  "type: data\n"
  "channel: ", <channel>,  '\n'
  "timeblock: ", <timeblock>, '\n'
  // for regular responses only [optional]:
  "mode: response\n"
  // for update responses only:
  "mode: update\n"
  <empty line>
  <epg data>

VDR_EPG_REQ
  "type: request\n"
  "channel: ", <channel>,  '\n'
  "timeblock: ", <timeblock>, '\n'
  // for update requests only:
  "mode: update\n"


<channel>  as used in channels.conf, cChannel::Parse() and cChannel::ToText()
<timeblock>  time_t as string
<epg data>  similar to the way used in epg.data, but for one channel only (thus
             without 'C ...' and 'c' entries and with mandatory table id and
             version in event entries ['E ...']);
            must not be empty, must end with a newline character;
            unknown entries inside an event description are ignored (an entry
             has exactly one line)

NOTE:  "mode: response" is not implemented, yet!



-- channel identification in the plugin ---------------------------------------

We identify channels by their channel-IDs (as described in vdr(5)), but pass
around the full channel information. I.e. the channel-ID is used when
calculating the DHT node address, getting EPG data from the vdr or storing it.



-- the send queue for pending data message transmission -----------------------

controller::block_send_queue is not a list of 'epgdata' (i.e. the actual EPG
data) but a list of 'blockentry' objects, i.e. just channel/time descriptions.
The data itself is picked immediately before it is sent, this way we merge it
with data, we have already had and allow updates of the data between logging
and sending.



-- miscellaneous --------------------------------------------------------------

requested blocks which have been completed by non-response messages will be
requested for again until a response arrives or the maximum repetition time is
reached or the block is out-dated



-- EPG data in vdr ------------------------------------------------------------

in epg.[ch]:
  cEvent: one piece of EPG data
  cSchedule: all EPG data of one channel (~list of cEvent-s)
  cSchedules: all EPG data (~list of cSchedule-s)

cSchedule is to be kept sorted (not done automatically but expected)
  [key is start time] !
  cSchedule::Sort() is in O(n*log(n))


exclusive access:
  cSchedulesLock SchedulesLock;
  const cSchedules *Schedules = cSchedules::Schedules(SchedulesLock);
    ///< Caller must provide a cSchedulesLock which has to survive the entire
    ///< time the returned cSchedules is accessed. Once the cSchedules is no
    ///< longer used, the cSchedulesLock must be destroyed.
  cSchedulesLock::cSchedulesLock(bool WriteLock = false, int TimeoutMs = 0);
  [-> epg.[ch]]


event id:
  eit.c:
    // XXX TODO log different (non-zero) event IDs for the same event???
    pEvent->SetEventID(SiEitEvent.getEventId()); // unfortunately some stations
    // use different event ids for the same event in different tables :-(
  so it seems that the event id belongs to the EPG data and is broadcasted, too


which EPG data is most up to date?
  see eit.c, lines 53-78 in vdr 1.3.17  [in cEIT::cEIT()]:
  -> cEvent::seen is set each time, the event has been received
  -> cEvent::version and cEvent::tableID:
      If the new event has a higher table ID, let's skip it.
      The lower the table ID, the more "current" the information.
      If the new event comes from the same table and has the same version
      number as the existing one, let's skip it to avoid unnecessary work.
  epg.c: (cEvent::version) "actual version numbers are 0..31"


how is EPG data gathered?
  -> per transponder
  from the vdr wiki:
    "From the "Schedule" menu, the "Green" button opens the "What's on now?"
     menu, which displays all programmes that are currently running on all
     channels that broadcast their programme information on the current
     transponder, or from channels that have been current lately (VDR stores
     all information it gathers in an internal list). The more channels you
     have been switching through lately, the longer this list will be."
