Updated README

1 files changed, 139 insertions, 1 deletions

diff --git a/README b/README
index 86ea416..1180854 100644
--- a/README
+++ b/README
@@ -62,6 +62,11 @@ to be scrapped. Please configure these channels in the plugin setup menu.
 Additionally you can trigger that your already existing recordings are 
 scrapped, so that also for this recordings metadata is available.
 
+With a "make install" the file "override.conf" which provides the
+possibility to define scraping behaviour manually (see description
+below) is created in <PLGCFGDIR>. An existing override.conf will
+not be overwritten.
+
 The plugins uses a sqlite3 database to store the necessary information. 
 If /dev/shm/ is available, the database is kept in memory during runtime 
 which improves performance. In the configured plugin basedir only a 
@@ -82,4 +87,137 @@ are kept to avoid unnecessary traffic for the web services, because the
 propability that this data is needed in the future again is rather high. 
 
 If a running recording is detected, the plugin marks the corresponding movie 
-meta data so that the information for this movie will be kept permanentely.
\ No newline at end of file
+meta data so that the information for this movie will be kept permanentely.
+
+Usage of override.conf: even if tvscraper tries to do everything correct on
+it's own, in some cases scraping delivers wrong results. Some EPG Events are
+not reasonable to scrap, because they reoccur constantly but deliver wrong 
+results everytime, or tvscraper searchs for a movie instead of a series 
+(for instance german "Tatort"). In such cases it is possible to use 
+<PLGCFGDIR>/override.conf to adjust the scraping behaviour. Each line in
+this file has to start either with "ignore", "settype" or "substitute":
+
+- Ignore specific EPG Events or recordings: just create a line in the format
+  ignore;string
+  to ignore "string". 
+- Set scrap type for specific EPG Event or recording: 
+  settype;string;type
+  "string" defines the name of the event or recording to set the type manually, 
+  "type" can be either "series" or "movie"
+- Substitute Search String:
+  substitute;string;substitution
+  "string" is replaced by "substitution" in every search.
+
+Service Interface
+-----------------
+
+Other Plugins can request information about meta data from tvscraper via
+a call to the provided service interface. 
+
+In general each call expects a pointer to a cEvent object as input variable 
+inside the struct passed to the call . This event object can either originate 
+directly from EPG data or from a recording. In this case the event object can 
+be retreived by Recording->Info()->GetEvent()).
+
+As output variables tvscraper provides media info via the "tvMedia" struct:
+
+struct tvMedia {
+    std::string path;
+    int width
+    int height
+};
+
+and actors information via the "tvActor" struct:
+
+struct tvActor {
+    std::string name;
+    std::string role;
+    tvMedia thumb
+};
+
+The service interface offers the following calls:
+
+- TVScraperGetPosterOrBanner
+  
+  With this call, a poster for a movie or a banner for a series which belongs
+  to a specific event can be retreived. 
+  
+  // Data structure for service "TVScraper-GetPosterOrBanner"
+  struct TVScraperGetPosterOrBanner
+  {
+  // in
+  const cEvent *event;             // search image for this event
+  //out
+  tvMediaType type;                //typeSeries or typeMovie
+  tvMedia media;                   //banner or poster
+  };
+
+  Example:
+
+  static cPlugin *pTVScraper = cPluginManager::GetPlugin("tvscraper");
+  if (pTVScraper) {
+    TVScraperGetPosterOrBanner call;
+    call.event = Event;			//provide Event here
+    if (pTVScraper->Service("TVScraperGetPosterOrBanner", &call)) {
+    	... further processing of call.media and call.type
+    }
+  }
+
+- TVScraperGetPoster
+
+  Retreive poster for specified event.
+
+  // Data structure for service "TVScraper-GetPoster"
+  struct TVScraperGetPoster
+  {
+  // in
+  const cEvent *event;             // search image for this event
+  bool isRecording;                // search in current EPG or recordings
+  //out
+  tvMedia media;                   //poster
+  };
+
+    Example:
+
+    static cPlugin *pTVScraper = cPluginManager::GetPlugin("tvscraper");
+    if (pTVScraper) {
+      TVScraperGetPoster call;
+      call.event = Event;                 //provide Event here
+      call.isRecording = true/false	  //recording or live EPG
+      if (pTVScraper->Service("TVScraperGetPoster", &call)) {
+          ... further processing of call.media
+      }
+    }
+
+
+- TVScraperGetFullInformation
+
+  Retreive all available information about given event.
+
+  /* Data structure for service "TVScraper-GetFullEPGInformation"
+  if type == typeMovie a poster and a fanart image is delivered
+  if type == typeSeries a banner and up to three posters and fanarts are delivered
+  */
+  struct TVScraperGetFullInformation
+  {
+  // in
+  const cEvent *event;             // search all media for this event
+  bool isRecording;                // search in current EPG or recordings
+  //out
+  tvMediaType type;
+  tvMedia banner;
+  std::vector<tvMedia> posters;
+  std::vector<tvMedia> fanart;
+  std::vector<tvActor> actors;
+  std::string description;
+  };
+
+  static cPlugin *pTVScraper = cPluginManager::GetPlugin("tvscraper");
+  if (pTVScraper) {
+    TVScraperGetFullInformation call;
+    call.event = Event;                 //provide Event here
+    call.isRecording = true/false       //recording or live EP
+    if (pTVScraper->Service("TVScraperGetFullInformation", &call)) {
+        ... further processing ...
+    }
+