This is a "plugin" for the Video Disk Recorder (VDR).
Copyright (C) 2007  Winfried Koehler

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA


See the file COPYING for more information.

******************************************************************************






Written by:                  Winfried Koehler <handygewinnspiel AT gmx DOT de>

Project's homepage:          free.pages.at/wirbel4vdr

Latest version available at: http://free.pages.at/wirbel4vdr/exec/index2.html

Licence:                     GPL (GPLv2 or higher versions)

Description:                 executes shell commands inside vdr.






/*************************************************************************************************
 * 0. Introduction
 ************************************************************************************************/
This plugin executes timers by a given time (schedule).
The timers are programmed via SVDRP commands (or with the exec timers menu).
Expired timers (those which start time is already in past and which are single-shot timers)
are deleted afterwards.

Minimum required VDR version: 1.5.7 (1.4.7 may compile, but untested/unsupported)


/*************************************************************************************************
 * 1. SVDRP commands
 ************************************************************************************************/
The examples here use the perl script svdrpsend.pl from the vdr source package. But you may use
also any other script/programm for that purpose, for example the bash shell is able to send
commands directly to vdr or you may use telnet, netcat..
PLEASE READ THIS COMPLETE README BEFORE USING THIS PLUGIN.



1.1. NEWT (New Timer)
/*************************************/
The svdrp command NEWT programmes a new timer. The syntax is


      NEWT <DATE>:<TIME>:<TIMEOUT>:<ACTIVE>:<ACTION>:<WAKEUP>:<DETACH>:<EXECSTRING>



format description:
/*************************************/
-<DATE>:
	a) YYYY-MM-DD	complete date with 4 digits year(1900..9999),
			2 digits month(1..12) and 2 digits day(1..31).
                        10 characters in sum.
		or..
	b) MM-DD	as above, but without year, year is assumed
			to be *this year*
                        5 characters in sum.                   
		or
	c) DD		as above, but month is assumed to be *this month*
			and year to be *this year*.
                        2 characters
		or
	d) -1		date is assumed to be *today*

		or

	e) MTWTFSS	any 7 characters (exactly 7!) long combination of
			"M", "T", "W", "F", "S", "-", this is a repeated timer.

			"-" has the meaning of 'not running this weekday'

			MTWTFSS		every weekday
			MTWTF--		every day, except weekend
			-----SS		weekend only
			--W----		single day, here wednesday
			...		and so on ;)

			NOTE:	first day is monday, last is sunday.


-<TIME>
	a) hhmm		2 digits hour (0..23) and two digits minute (0..59)
		or
	b) -1		*now*
                        NOTE: for repeated timers you have to define time,
                              -1 is NOT accepted this case.

-<TIMEOUT>
	not implemented yet, reserved for future use. Always 0.

-<ACTIVE>
	Is the timer active?
	a)	0:	not active.
	b)	1:	active.

-<ACTION>
	a)	1:	run shell command

	b)	2:	shutdown computer via VDR,
			NOTE: <EXECSTRING> has to be "SHUTDOWN" this case.

	c)	3:	show message in VDR's OSD

	d)	4:	show warning in VDR's OSD

	all other number reserved up to now.

-<WAKEUP>
	wakeup computer, see VDRs INSTALL file, chapter "Automatic shutdown"
	a)	0:	no wakeup.
	b)	1:	wakeup

-<DETACH>
	detach shell process. Does not affect other actions.
	a)	0:	no detach
	b)	1:	detach

-<EXECSTRING>
	This is a string with 1 .. 255 characters which represents either
		a) a shell command (default)
		b) a message string to be displayed in VDR's GUI
		c) a warning string to be displayed in VDR's GUI
		d) "SHUTDOWN" if VDR should shutdown.

        NOTE: EXECSTRING cannot include colons ":" !
	NOTE: min 1 char.
	NOTE: max 255 chars.
	NOTE: the meaning of that string is defined with <ACTION>
	NOTE: Sometimes you need partial quoting "" and full quoting ''.


example:
------------
This example programmes 
 * a single shot timer
 * on the 2007-12-24
 * 5:30 pm
 * with the shell command running in background 'play Chrismas_Song':
 * computer will not wake up.
 * NOTE: partial quoting used here.

  -bash-3.00# svdrpsend.pl plug exec NEWT 2007-12-24:1730:0:1:1:0:0:"play Chrismas_Song"
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 16:29:34 2007
  250 new timer accepted.
  221 TopLap closing connection




1.2. DELT (Delete Timer)
/*************************************/
The svdrp command DELT deletes the timer specified by INDEX. The syntax is
      DELT <INDEX>
Index is running from 0 (first timer) to count-1 (last timer).

  example:
  ------------
  This example deletes the sixt timer in the internal list, see command LSTT:
  -bash-3.00# svdrpsend.pl plug exec DELT 5
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 17:25:08 2007
  250 timer deleted
  221 TopLap closing connection


1.3. RUNT (Run Timer)
/*************************************/
The svdrp command RUNT deletes the timer specified by INDEX. The syntax is
      RUNT <INDEX>
Index is running from 0 (first timer) to count-1 (last timer).

  example:
  ------------
  This example runs the third timer in the internal list, see command LSTT:
  -bash-3.00# svdrpsend.pl plug exec RUNT 2
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 17:25:08 2007
  250 timer started
  221 TopLap closing connection


1.4. LSTT (List Timers)
/*************************************/
The svdrp command LSTT lists all timers. The syntax is
      LSTT

  example:
  ------------
  -bash-3.00# svdrpsend.pl plug exec LSTT
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 16:32:14 2007
  250 2007-12-24:1730:0:1:1:0:0:play Chrismas_Song
  221 TopLap closing connection



1.5. CLRT (Clear Timers)
/*************************************/
The svdrp command CLRT clears the whole timer list. The syntax is
      CLRT

  example:
  ------------
  -bash-3.00# svdrpsend.pl plug exec CLRT
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 17:26:24 2007
  250 list cleared
  221 TopLap closing connection


1.6. NACT (Next ACtive Timer)
/*************************************/
The svdrp command NACT returns the the next active timer. The syntax is
      NACT

  example:
  ------------
  -bash-3.00# svdrpsend.pl plug exec NACT
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 17:29:17 2007
  250 next active timer 2007-12-24:1730:0:1:1:0:0:play Chrismas_Song
  221 TopLap closing connection

1.7. NWUT (Next WakeUp Timer)
/*************************************/
The svdrp command NWUT returns the the next wakeup timer.
A wakeup timer has the MODIFIER FLAG 'wakeup computer' set, see WAKEUP.
The syntax is
      NWUT

  example:
  ------------
  -bash-3.00# svdrpsend.pl plug exec NWUT
  220 TopLap SVDRP VideoDiskRecorder 1.5.9; Sun Sep 23 17:29:17 2007
  250 next wakeup timer 2007-09-23:1900:0:1:1:1:0:update_dvb_driver.sh
  221 TopLap closing connection




/*************************************************************************************************
 * 2. Additional Files
 ************************************************************************************************/
This plugin stores it's timers in the file 

<CONFIGDIR>/plugins/exectimers.conf

This file is automatically generated and will be overwritten without any 
warning if the plugin is running. The file format is exactly the same as described
in chapter 1.1 SVDRP NEWT of this README.

The log file will be saved as /var/log/exec.log.


/*************************************************************************************************
 * 3. Some Remarks
 ************************************************************************************************/

- This plugin is GPL software. See COPYING for details. You may use this source
  code as long the software produced out of it is also GPL'd and its visible where
  it comes from. That means that in this case you have to redistribute your sources.

- The plugin checks only from time to time wether its time to execute; its precision is only one minute.

- Do NOT program timers which might harm your system or may have side effects. It's
  your responsibility to use this software carefully, especially if you're running your VDR as privileged user.

===========================WARNING!!!=====================================================================
  ANY USER WHO HAS THE POSSIBILITY TO PROGRAM EXEC TIMERS IS ABLE TO EXECUTE COMMANDS VIA THIS PLUGIN WITH
  THE PERMISSIONS OF YOUR VDR!
  YOU HAVE TO RESTRICT EITHER THE PERMISSIONS OR THE LOGINS TO YOUR VDR COMPUTER.
==========================================================================================================

- No garantee is given that this software will work as expected. Please submit bugs/wishes/patches to the author.







have phun..
wirbel (see you at http://www.vdr-portal.de)
