Last updated 2015.04.24 16:42
MediaShow
=========

Plugins - for people who manually code page/magazine/screen files
-----------------------------------------------------------------

Plugins are special DLLs that reside the in same directory
as MediaShow's executable.  They have an .MPI extension
for "Mediashow PlugIn".

To use a plugin in a page or magazine simply add:

	<plugin_name>=[<options>]

in with the other parameters.  The .MPI extension is
usually omitted for the plugin_name.  Not all plugins take
options - see documentation for individual plugins.  The older
syntax was:

	PLUGIN=<plugin_name> [<options>]

but this only permitted one plugin per page.

Knowledgeable users can write plugins.  Here are descriptions
of the sample plugins supplied with MediaShow:
 
Others=<number_of_pages>
    Summary: Only play when there are other pages like me.
    Others assumes that the page has a name in the form of:
    <letters><digits>.pge - "Hello03.pge" for example.
    This plugin will not let a page run until there are <number_of_pages>
    files of the same type.
    For example if page hello07.pge specified "Others=3"
    and there were pages hello08.pge and hello09.pge then it would be
    played.  (Improved 2003Mar23 to handle any number of digits)
    If you want to make sure those other pages are actually valid to
    play look at the AnyPlay plugin.  Others is less CPU intensive
    than AnyPlay since it doesn't look inside the files.

TimeChg={Spring|Fall}
    Summary: Play a page/mag on the day clocks spring forward or fall back.
    TimeCng gets its information from the Windows registry so
    it respects any changes you make with the Control Panel.
    Time changes typically occur at am so you may want to
    use this plugin with a time option to make sure a page/mag
    is played after or before the actual time change.
    A page using the Spring option might say "Hope you didn't
    forget to set your clock an hour forward last night".

Year={Leap|WorldCup|SummerOlympics|WinterOlympics|StartDecade|EndDecade|StartCentury|EndCentury|<year>}
    Summary: Plays a page/mag based on the year.
    The options are:
    Leap: leap years
    WorldCup: years when there is a World Cup
    WinterOlympics: years when there is a Winter Olympics
    StartDecade: first year of a decade (e.g. 2000, 2010)
    EndDecade: last year of a decade (e.g. 1999, 2009)
    StartCentury: first year of a century (e.g. 2000)
    EndCentury: last year of a century (e.g. 1999, 2099)
    <year>: any year (e.g. 1901, 2003)
    
Month={Q1|Q2|Q3|Q4 | Winter|Spring|Summer|Fall | Jan|Feb|Mar...}
    Summary: Plays pages/mags based on the month.
    For business applications Q1 is the first quarter and
    Q2 is the second quarter and so on.  Winter is
    Dec, Jan, Feb.  Spring is the next 3 months, etc.
    Note: the seasons are not astronomically correct.

Date={YYYY.MM.DD|MM.DD|DD} ...
    Summary: Plays a page/mag based on the date
    Where YYYY is the year, MM is the month and DD is the day of the month.
    You may also use "last" for DD.  Multiples are allowed on the command line but
    not supported by the GUI.
    Examples:
	Date=13 - play every month on the 13th
        Date=last - play the last day of each month
    	Date=12.15 - play every year on Christmas
        Date=2010.10.10 - play only on a single date

Occasion=<day>
    Summary: Knows many special occasions.
    Supported <day>s are: NewYearsDay, TeslaDied, HalBirthday, ElvisBirthday, RobbieBurnsDay,
    GroundHogDay, Valentines, LeapDay, PiDay, IdesOfMarch,
    StPats, VernalEquinox, AprilFools, UsTaxDue, CanadaTaxDue,
    EarthDay, CincoDeMayo, BobMarleyDay, JeanBaptisteDay, CanadaDay,
    IndepDay, TelsaBorn, Halloween, RememberanceDay, VeteransDay,
    XmasEve, Xmas, BoxingDay, NewYearsEve, Easter, Friday13.
    If you know of an occasion that occurs
    on the same month and day of month every year that we
    haven't included - let us know.

UN=<day>
    Summary: Play a page/mag on special U.N. days.
    The United Nations has declared certain days as "observances".
    For example, to play a page on World Health Day do this:
    UN=World Health Day.  Of course, our favorite is World
    Television Day.  See the GUI for a full list of observances
    available.  Our source is the U.N. website at
    http://www.un.org/Overview/observ.htm

Once={1|0|yes|no}
    Summary: Rename after playing once.
    Once ensures that a page or magazine will only run once by
    renaming it to <original name>.old after its been
    played.  The option enables or disables the plugin
    ("Once=no" does nothing)

MaxPlay=<max-times-to-play>
    Summary: Limit the number of times a page plays.
    This plugin only works for XML pages.
    The default is one time.
    This plugin ensures a given content of a page will not play more
    than a maximum number of times.  It compares the current content
    (ie the <mom:tag>s) and video file (ie <rt:video><rt:filename>) 
    of the XML page with the content/video file that was in
    previous plays.

Moon=[<day>] [<phase>] [<direction>] [<shape>]
    Summary: Play a page/mag based on the phase of the moon.
    Where:
    <day> is the number of days since a new moon - e.g. "day10"
    <phase> is one of New, FirstQuarter, Full, LastQuarter
    <direction> is either Waxing or Waning
    <shape> is either Crescent or Gibbous
    All <phase>s are one day events.  The moon is either waxing
    or waning when it is not full or new.  The moon is either
    crescent or gibbous when its waxing or waning.
    You can specify one or several of the options.
    Examples:
	Moon=Full     - is it a full moon? (every ~29.5 days)
	Moon=Waxing   - moving a from new to a full moon
	Moon=Waxing Crescent - waxing and crescent shape
	Moon=FirstQuarter - a 1/4 sliver (every ~29.5 days)

Sunspot=<n>
    Summary: Play based on predicted sunspot level
    Where: <n> is a number between 0 and 150 representing the
    minimum required sunspot number (ie number of sunspots).
    Sunspots have an appropriately 11 year cycle.  When strong
    they can interfere with satellite communication.

LowDisk=<n>
    Summary: Play a page/mag when disk space is low.
    You specify the number of megabytes which is considered low.
    E.g.:  LowDisk=5 - play when there is less than 5 megabytes
    of free disk space on drive C:.  You can design a page that displays
    a discrete overlay - like a single pixel red dot in the corner - that's
    only displayed when diskspace is low!  (Note that LowDisk uses the
    "computer" meaning of a megabyte: 1,048,576 bytes.)

OneIn={ <n> | <n>% }
    Summary: Play randomly.
    If you want a page to have 1 in 10 odds of playing each time MediaShow checks it specify:
	OneIn=10
	
    Alternately, you can state the percent the page/mag should play:
	OneIn=80%
    
TimeSlot=<minutes offset> <slot offset>
    Summary: Play a TV Guide page/mag according to its timeslot
    TV Guide pages are named TV?0900?.pge[.xml] where 0900 is the time
    the page is valid for.  A timeslot a half-hour period.  
    If we want a page with 9:00 in its name to play in the 9:00-9:29
    timeslot we would code: TimeSlot=0 0.  If we want
    this same page to play from 8:50-9:20 we code: TimeSlot=10 0.
    Here 10 minutes are added to the current time making it start
    playing 10 minutes "early".  To play the pages for the next
    timeslot code: TimeSlot=0 1.
    Typical use:

	TimeSlot=10 0          - what's on
	TimeSlot=0 1           - coming up

    You may optionally specify a range for the either number, for example:

	TimeSlot=10 0..5       - what's on in the next 5 slots

   Negative numbers are permitted.
   Finally, for those really tricky situations you can tweak the time
   of the page:

	TimeSlot=minutes -25..25

   This will play the page 25 minutes before the time in the filename
   to 25 minutes after the time in the filename.  You can specify 
   multiple minute ranges.

Expire=<full date and time>
    Summary: stop playing a page/mag after a certain point in time.
    A typical use is to stop sports scores from playing after 11am
    on the day after the game.  So if today is 1997.12.04 and
    we want this page to stop playing tomorrow at 11am we code:

	Expire=2020.12.05 11:00:00:00
	
Target=[-host=<host> -userid=<userid> -password=<password> -creds=<creds>] <page>
    Summary: play something else (possibly remotely) while this plays.
    This is the same as the target page that can be specified in a page except this plugin supports remote
    targets.  Also supports target magazines.
   	
TargetExpire=<full date and time> <full path of target page>
    Summary: play the target page until the specified date/time.  Does NOT change whether the base page plays or not.
    
	TargetExpire=2020.12.05 11:00:00:00 c:\digimation\pages\TutorialTitle\Intro.pge.xml

RunDuration=HH:MM:SS:FF
    Summary: Stop playing a certain duration after the file was created.
    For example to stop playing 30 minutes after a page was created:
    
    	RunDuration=00:30:00:00

Absolute=<full date and time> <full date and time>
    Summary: Play a page/mag between two absolute points in time. 
    Regular date and time ranges in page/mags are still processed.
    Example:

	Absolute=2007.12.05 11:00:00:00 2007.12.06 10:59:59:29

ShowMinute={<minute>|odd|even|all} ...
    Summary: play only in the given minute(s).
    This plugin works like the old MediaShow command SHOW_MINUTE=nn.
    Example:

	ShowMinute=0 10 20 30 40 50

    Play only on the hour, ten minutes past, etc.
    ShowMinute also supports "even" for minutes that
    are divisible by two and "odd" for minutes that aren't.
    So:

	ShowMinute=even 1 2 3 4 5 6 7 8 9

    Will play then first 10 minutes of every hour and even minutes

Hour={<hour>|odd|even|all} ...
    Summary: play only in the given hour(s)
    Options are the same as ShowMinute - above.

Weekday={<dayname>|<hex-number>} ...
    Summary: play based on the day of the week
    This plugin works like the magazine attribute MAG_DAY but the
    syntax is more general.
    Examples:

	Weekday=sun     - play only on Sundays
	Weekday=sat sun - play only on weekends
	Weekday=7fh     - play every day (assembler-style hex)
	Weekday=0x7f    - play every day (C-style hex)
	Weekday=0x02 tue 04H - combining the above 
	Weekday=Workday - Monday to Friday inclusive        
	Weekday=Weekend - Saturday and Sunday
	Weekday=All - every day

Week=[-<day>] [-s <time>] {<number>[-<number>]|odd|even|/<number>} ...
    Summary: play based on the week of the year
    This is a *broadcast* week.  (e.g. http://www.rab.com/bccal99.html) 
    The first week is the one that included January 1.  This would typically
    include a few days from the previous year.
    By default Monday is the first day of the week.  But using -<day> (eg -thu) you can change this.
    By default midnight is when the change over occurs.  But using -s <time> (eg -s 18:00:00:00) you can change this.
    Examples:

	Week=<number>              - Specific week
	Week=<number>-<number>     - Range of weeks
	Week=odd                   - Odd numbered weeks
	Week=even                  - Even numbered weeks
	Week=/3                    - Every third
	Week=/4                    - Every fourth week, etc.
	
Expression=<boolean plugin expression>
    Summary: combine other plugins.
    The expression plugin lets you make Boolean expressions
    from any other plugins.  It is best explained with some examples:

    expression=not {moon full}  - play this page with the moon isn't full
    expression=not {showminute 0 1 2 3 4 5} - play this page the last 55 minutes of the hour
    expression={moon full} or {moon waxing}
    expression={month Q1} or {month Q2} - first half of the year
    expression=not ({month Q1} or {month Q2}) - second half of the year
    expression=not {expire 1998.10.02 23:59:59:29} - play after Oct 2
    expression={moon full} and {occasion ElvisBirthday}
    expression={weekday fri} and {date 13} - play on Friday the 13th

    For plugin programmers:
    If MediaShow selects the page/mag to be played, the OnPreLoad(), OnPlayEarly()
    and OnPlay() functions in *all* the plugins in the expression are called.
    
Multi={<plugin-and-options>}...
     A simpler format of expression.  The plugins are always and-ed together.

OnPreload={async|sync}+{show|hide} <command line>
    Summary: Execute the windows command line when the page/mag/screen is preloaded.
    The command line can be any batch file or program.
	
    One of "async" or "sync" must proceed the command line. 
    "sync" means execution of MediaScreen/Show will not continue
    until your command is done so only use it when you command is
    really fast or when it must be done before the page/mag/screen
    begins.  If you command is slow, use "async".

    You can supply an unlimited of argument/options on the command line.
    Examples:

	OnPreload=async MyScript 45
	OnPreload=sync replace_backgrounds .eve
		
OnPlay={async|sync}+{show|hide}[+{early|punctual}] <command line>
    Summary: Execute the windows command line when the page/mag/screen has just begun playing.
    The parameters are the same as the OnPreLoad plugin.

    Examples:    
       
	OnPlay=async+hide ControlSwitcher in=34 out=45
	OnPlay=async+hide msccmd play c:\screens\myscreen.scn

    Assuming you have a command called ControlSwitcher.
    
OnEnd={async|sync}+{show|hide} <command line>
    Summary: Execute the windows command line when the page/mag/screen has just finished playing.

TimeSpan=HH:MM:SS:FF-HH:MM:SS:FF ...
    Summary: Play the file (i.e. page, mag, screen, etc) only in the specified time period.

    Example:
	TimeSpan=12:00:00:00-12:59:59:29        will play over the noon hour.
	TimeSpan=11:00:00:00-11:59:59:29 23:00:00:00-23:59:59:29  will play the last hour of the AM and PM
	
    Note TIME_RANGE is built into MediaScreen/Show.
	
TimeRule=<start>-<stop>-<freq>-<duration> ...
    Summary: Make lots of time ranges

    Example:
    	TimeRule=12:00:00-23:59:59-00:30:00-00:00:10     play every 30 minutes in the afternoon for 10 seconds

MaxDays=<days>
    Summary: Play a certain number of days after the start date.
    
    This plugin looks in the page for START_YMD in an .pge file or the first <rt:dateRange> in a .pge.xml file
    and adds <days> to get a stop date.  Note that the actual start date is counted as one
    of the days.
    
    Example:
    	START_YMD=2002.03.13
        STOP_YMD=3000.12.31
        MAXDAYS=2
         
    will play on 2002.03.13 and 2002.03.14 only

MaxWeeks=<weeks>
    Summary: Same as MaxDays but for weeks.
 
RenderStatus=<status>
RENDER_STATUS=<status>
    Summary: Play this page if it has been rendered.
    When the DiGiMATiON Renderer completes rendering the media for a page, it sets
    RENDER_STATUS=rAVI (if it rendered an AVI).  This plugin simply checks for the
    for the first letter being "r".  Set RENDER_STATUS=u for unrendered pages.

PuStatus=<status>
    Summary: Play this page if the power user status is good.
    NetGate usually modifies this value based on the Billboard administrator's actions.
   

    
JustPlayed=<files>
    Summary: Play this page/mag/etc if any of the specified pages have just played.
    Examples:

        JustPlayed=news*.pge
        JustPlayed=one.pge two.pge c:\media\magazines\news.mag
        JustPlayed=c:\media\magazine\news*.mag news*.pge
        JustPlayed=c:\digimation\pages\large\larg*.pge.xml

    As you can see local files, absolute paths, pages, magazines, wildcards,
    multiple files, classic and XML are permitted.  If you specify a .mag.xml to JustPlayed,
    it will compare that name with the currently playing magazine.  Likewise for pages, etc.
    This plugin finds the currently playing page
    using a feature introduced in MediaShow 3.6t12.
    
Need={anim|audio|video|no_video_transfer|crawl|scroll|layout|background|logos|exist}...
    Summary: Play this page if the specified item is present AND the file(s) associated with it exist.
    You can specify one or more items.
    "anim" checks ANIM_FILE=<file>, "audio" checks AUDIO_FILE=<file>, etc.
    "layout", "background" and "logos" check the page's IPS (if classic).
    For XML pages, "background" does not apply.  "logos" checks all the images.
    "exist" is slightly different -- it checks that the files mentioned in the page exist.
    It does not check if any specific files are in the page.
    "no_video_transfer" checks that <video-file-specified-in-page>.STP does not exist.
    Examples:

        Need=anim
        Need=crawl scroll background
        Need=anim audio crawl scroll layout background logos exist
        
Compare=<file> <operator> <value> 
    Summary: Play based on a value found in another file
    Where:
    <file> is the full path to a text file
    <operator> is lt, <, gt, >, =, eq, !=, ne 
    lt, gt, eq, ne are string comparisons
    < > = != are numeric comparisons
    <value> is a number or string to compare with the first line of text file
    Example:
    	Compare=c:\data\degree.txt > 30          play this page when its hot (assuming degree.txt has is updated with the current temperature in Celsius)

Control=[-host=<host> -userid=<userid> -password=<passwprd> -creds=<creds>] <when> <do> <file> [<zone>]
    Summary: Perform command and control
    Where:
    <when> is the time in this page's life to play.  Can be: preload, play-early, play
    <do> is what to do.  Can be: exec, access, preload, play
    <file> is the full path to the page/mag/etc to play.  Must be quoted if contains spaces
    <zone> is the optional zone to play in.  Most be quoted if contains spaces.
    Example:
  	Control=play play c:\My\Zone.zon
  	
WinTv=file:<file> [channel:<channel>] minutes:<minutes>
    Summary: Record using the Hauppauge WinTV
    <file> is the MPEG file to record to
    <channel> is the channel number.  Often omitted meaning the line in or the previously selected channel.
    <minutes> is how long to record.

RecordVideo=file:<file> input:<input> [channel:<channel>] minutes:<minutes>
    Summary: Record using GBrecord - supports most PVR cards
    <file> is the MPEG file to record to
    <input> is {tuner|svideo1|svideo2|composite1|composite2|composite3}
    <channel> is the channel number.  Omitted for non-tuner input.
    <minutes> is how long to record.
    
PaintWeek=<encoded data>
    Summary: Draw when this page/mag is to play
    Use the Timeline-like GUI to describe when to play.

PlanWeek=v2 <play-interval>...
     Fine-grained week calendar
     "v2" is the version of the plugin and may change.
     Example:
     PlanWeek=v2 Mo20:00-05:00 Tu10:00-We04:00note_here

EventLog={yes|no}
    Summary: log in the Windows Event Log
    The options enabled or disable this plugin.

SerialDevice=<options>
    Summary: send commands to a serial device
    Supports more COM: ports than MediaShow


WebOnly={yes|no}
    Summary: Indicate that this file is intended for the web only
    The default is yes.

Platform=[Android] [Web] [Windows]
    Summary: Specify the platforms (eg Android, Web, Windows) where this file is to play


    
Computer=<computer>,...
    Summary: Play based on computer name
    You do NOT have to set the computer name on each playback since its already set

Keywords=[-p<playback>] [-k<extra-comma-delimited-keywords>][[{-any|-ANY}] <keywords>][{-all|-ALL} <keywords>][-exclude-any <keywords>][-exclude-all <keywords>]
    Summary: Play based on selected keywords
    Play this file if the command line keywords are in the playback file or the optional keywords.
    Keywords are space delimited everywhere but in the -k option.
    If the user checks "Let Audience.billboard users select keywords" it puts $pd_keywords on the command line rather than actual keywords.
    Billboard then presents a user-interface for this.  In case a page slips throught with $variable in the command line the plugin tells its client (eg MediaShow) that it should be ignored.
    Keywords can only be ASCII letters and underscores.

Playback=<playback1> <playback2> ...
    Summary: Play a page/mag on selected playbacks
    If you have a page that you want to only play on a handful of playbacks this is an easy plugin that will do that.
    Its easier that Keywords because the list of playbacks is automatically maintained (the plugin just looks for .ply.xml files) and you don't have to
    set the current playback (the plugin asks MediaScreen for that).

iCal=<file> [<uids> ...]
    Summary: Play when iCal events are scheduled.
    Enter the full path to an iCal (.ics) file.  Use double quotes if there is a space in the path.
    iCal (RFC 2445) is a powerful and standardized format for describing schedules.  You can make a schedule using Windows Calendar and export it to an .ics file.
    iCal supports reoccurring events.  For example, you can schedule an event every second Tuesday from 9am to 10am, etc.
    Pre-made iCal files are available online at http://www.apple.com/downloads/macosx/calendars and other places.
    You can optionally, specify the UID of events you are interesting in.  (Easily done in the GUI.)
    Examples:
    	iCal=c:\downloaded_schedules\MapleLeafs.ics		- Play when the Toronto Maple Leafs have a game (downloaded from http://www.apple.com/downloads/macosx/calendars/torontomapleleafscalendar.html)
    
Heartbeat=<file>
    Summary: Update a heartbeat file with a page/mag is played
    When the page plays its full path will be played into <file>.  Other content in the file will be discarded.
    And, of course, the file's modification time is updated. 
    Will not update a heartbeat file more than once every 15 seconds.
    Has no effect on whether the page plays or not.
    You can use this plugin to check that an important page(s) is playing.  Or you can use it for the opposite -- use it in a low priority
    emergency page(s) and when you see the heartbeat updated you know there is trouble.
    
MailMsg=-s<subject> -b<body>
    Summary: Send a mail message when this page/mag is played
    Non alphanumeric characters in the <subject> and <body> must be hex-percent-encoded.
    This is automatically done when you use the GUI.
    Subject or body can contain $file (hex-percent-encoded) to name of the current file in mails.
    You must also configure some more parameters.  The plugin will initially take the configuration from your
    Billboard setup (if present).  Again, easily done with the GUI.
    Will only send one mail every 10 minutes (to avoid fill mailboxes with redundant stuff).
    
Pan=
    Summary: Create an animation that pans over an image
    This plugin has no options.  It only works for XML pages.  It will change the largest image into an MNG animation
    that pans around it.  The image needs to be larger than the zone or it will do nothing.  It modifies the page as follows:
    	- Inserts the MNG as a video file, changes the video type to "mpeg".
    	- Creates a transparent TGA export image and inserts it.
    	- Removes the JPEG export image.
    Future versions may include more interesting ways to pan around the image.
    
Text=<any text>
    Summary: Displays the text you supply.
    Default: Hello
    Android only.
    
TextOnBackground=-bg=<background> -text=<text>
    Summary: Displays text on a background image.
    Android only.
    
Rotate=<degrees>
    Summary: Turns the page's image the specified number of degrees.
    Default: 90
    Android only.
  
MemInfo=[-brief]
    Summary: Display memory info
    Pages only.  Android only.
    If you use the -brief option it will only display <heap-used>% | <native-used>%

TakeTurns=
    Summary: play one page of a set each time thru a pagelist
    Place news01.pge.xml, news02.pge.xml, news03.pge.xml in a pagelist.
    Add the plugin to each page.
    
ShareUrl=-host=<host> -userid=<userid> -password=<password> -creds=<creds> -url=<url>
    Summary: Share a URL via a website
    When a page plays this plugin updates a website using ftp.
    The ftp account must be setup so when the user ftp's in its in the website's home folder (this is the usual case).
    To reduce latency it logs in to the ftp site when the page preloads and only does the write when it plays. 
    You can then send a user to the user's home page and be redirected to the current URL.
    
_FindPlugins=
    Summary: Helps users find the right plugin
    This plugin is not to be used in a page.  In a wizard-like way it asks the user questions and suggests plugins that are right for their needs.
    If the user selects the Expire plugin it will return "Expire=" from EditPlugin() which Audience.foundation can use.
  
Combining Plugins in Classic Pages
    You can use multiple plugin in a page or magazine.
	This means you can do things like this:

		Moon=Full
		Occasion=ElvisBirthday

    - only play when Elvis' birthday falls on a full moon!
    In Audience you can do this with the Multi plugin.
    
Script plugins
--------------

You may also use plugins in scripts.  Here is an example script:

	page1.pge
	{tick}
	page2.pge

As you might expect, the brace-bracketed line calls the "tick" plugin.
This plugin, turns {tick} into pageSS.pge where SS is the current second
(with leading zero).

Page/Mag/Screen Plugins - for programmers
-----------------------------------------

We suggest that you should be at least an intermediate programmer before
writing a MediaShow plugin.  Why?  Because if your plugin crashes
(or otherwise causes trouble) a TV channel will go down.
Good plugins are:

	- very fast
	- totally robust
	- small
	- do one thing well

Plugins should be very fast to execute (in all cases) because MediaShow
will be executing it many times each cycle - in addition to other plugins
possibly.  MediaShow is a realtime application so it can not be spending
any noticeable percentage of its time running plugins.

MediaShow hands total control to the plugin.  If you get into an
infinite loop the channel will freeze.  If you address a null pointer
the channel will freeze.  We strongly advise against the use or malloc
or new in plugins.

Plugins should be small because there may be many running. Small
chunks of code are easier to make robust.  If you find your plugin getting
over 100K it's probably time to rethink things.

A plugin that does one thing very well is a joy to use.  Your plugin
should accept any possible input without crashing.

Before we get into the nitty-gritty on how to make plugins.  Have
you considered writing a standalone program instead of a plugin.
MediaShow will immediately see new mags/scripts/pages - or changes in them -
and schedule them appropriately.  Maybe you just need to write a program
that modifies mags/scripts/pages.

Now the details... as we mentioned above a MediaShow plugin is
simply a Win32 DLL which certain functions defined.  This description
is geared towards Borland C++ users.   Here is a sub-mini plugin that
plays pages in January:

extern "C" BOOL WINAPI _export IsPlayNow(const WORD argc, LPCSTR argv[], LPCSTR szFile, const DATETIME dtPlay, BOOL *bIsPlayNow)
{
	bIsPlayNow = (dtPlay.Month == 1);  // Set bIsPlayNow to TRUE only when month is 1 (or January)
	return TRUE; // Return TRUE because we are sure about our result
}

Compile this file into a .DLL and rename it .MPI and that's it!
We'll now describe the functions in greater detail.


Function:
	IsPlayNow

Summary:
	IsPlayNow is called by MediaShow when it is deciding whether or not
	the play a mag or page.  It is not guaranteed to always call a pages
	IsPlayNow - the page may be excluded by another option (e.g. TIME_RANGE)
	or another plugin.

Parameters:
	Input:

		 argc
			Number of options

		 argv
			The options from the page (or mag).
			E.g. if the page said MyPlugin=Hello World
			then argv[0] = "Hello" and argv[1] = "World".

		 szFile
			The full path of the page/mag being processed.

		 dtPlay
			The date/time being considered

	Output:
		 bIsPlayNow
			Set this to TRUE if the page/mag should be played

Return Code:
	The return code of your IsPlayNow function does not determine if
	the play is played or not.  It tells MediaShow if you
	where able to *decide* whether it should be played or not.  When you
	return TRUE, MediaShow checks the value you set for *bIsPlayNow.  If it
	is also TRUE then MediaShow will consider playing the page.  If your
	plugin gets an option it is not expecting it should return FALSE.
	
	
Function:
	OnDraw

Summary:
	OnDraw is called when a page has been selected to play and
	is being preloaded.  It allows a plugin to dynamically replace the bitmap that will be displayed for the page.

Parameters:
	[in] argc
		Number of options - same as IsPlayNow

	[in] argv[]
		The options - same as IsPlayNow
	
	[in] szPage
		The full path of the page being processed.
		
	[in,out] szBitmap
		When your OnDraw() is called this will have the full Windows path to the bitmap that MediaShow is about to use for the page.
		(Almost always the TGA export image from the page).  You can put the full Windows path to a different bitmap.  Digiblit only supports TGA and JPG
		image types.  If you wish you code can read the original bitmap, change it in memory and write it out under different name
		and return that name.
		
	[in] sizeBitmap
		Number of bytes of the szBitmap field.

Function:
	OnPreLoad

Summary:
	OnPreLoad is called when a page/mag/screen/etc has been selected to play and
	is being preloaded.

Parameters:
	argc
		Number of options - same as IsPlayNow

	argv[]
		The options - same as IsPlayNow
	
	szFile
		The full path of the page/mag being processed.


Function:
	OnPlayEarly

Summary:
	OnPlayEarly is called when a page/mag/screen/etc is just about to start playing

Parameters:
	Same as OnPreLoad above.


Function:
	OnPlay

Summary:
	OnPlay is called when a page/mag/screen/etc has just started playing

Parameters:
	Same as OnPreLoad above.



Function:
	GetDescription

Summary:
	Called by an expression editor/MediaMake when it wants a brief description of what the plugin does

Parameters:
	szDesc
		Null-terminated string output by the function
	size
		number of bytes in the buffer that will hold the description
	

	This function is usually implemented with just one line of code - like this:	
	
	extern "C" void WINAPI _export GetDescription(LPSTR szDesc, const size_t size)
	{
		lstrcpyn(szDesc, "Play based on the phases of the moon!", size);
	}


Function:
	EditPlugin

Summary:
	Display a GUI that provides a user-friendly way to edit the plugin's options

Parameters:
	szCommandLine
		A null-terminated buffer - used for both input and output.
		It is the command-line for the plugin from the page.
	
	dwSize
		Number of bytes in the buffer
	

	As an example szCommandLine might be "moon=full" on input to this function.  Then, after
	the user makes changes in a dialog box, szCommandLine is "moon=new" when the function exits.
	It's the job of the function's caller to read/write the command-line the page/mag/screen/etc.
	EditPlugin() should TRUE if the user clicked on OK, otherwise FALSE.
	

Function:
	DllEntryPoint / DllMain 

Summary:
	DllEntryPoint / DllMain is not a MediaShow plugin specific function.  Borland C++
	calls DllEntryPoint when a DLL is loaded or unloaded.  Visual C++ called DllMain.
	Use DllEntryPoint / DllMain to initialize your plugin.  You do not have to implement this function.
	If you have no initialization to do - leave it out.
	See Borland C++ / Visual C++ documentation for more detail.


Function:
	GetPages

Summary:
	GetPages is only used for *script* plugins.  When MediaShow sees:

		page1.pge
		{MyScriptPlugin thing1 thing2}
		page2.pge

	in a script (.LIS file) it calls GetPages in MyScriptPlugin.mpi.
	Return the name of the page you want MediaShow to play.  The page
	is still evaluate to see if its valid to play.  It may contain
	page plugins!

Parameters:
	Input:

		 argc
			Number of options

		 argv
			The options from the page (or mag).
			E.g. if the script said {MyPlugin Hello World}
			then argv[0] = "Hello" and argv[1] = "World".

		 szFile
			The full path of the script being processed.

		 dtPlay
			The date/time being considered
		 
		 wResultSize
			Size of the result buffer.

	Output:
		 szResult
			The buffer where you write the name of the page.
            If in the same directory as script you don't need to return the full path
            - eg "tick34.pge" - this is cleaner.  But if in another directory you must
		    return the full path.  You may also return multiple pages - separate
			them with semi-colons - be sure to respect the size of the buffer you
			are given.


Return Code:
	The return code of your IsPlayNow function does not determine if
	the play is played or not.  It tells MediaShow if you
	where able to *decide* whether it should be played or not.  When you
	return TRUE, MediaShow checks the value you set for *bIsPlayNow.  If it
	is also TRUE then MediaShow will consider playing the page.  If your
	plugin gets an option it is not expecting it should return FALSE.


Function:
	AcceptCallbacks

Summary:
	Receive pointers to functions within MediaShow.
	MediaShow provides some functions that plugins can use.
	If you do not wish to use these function simply omit this
	function from your plugin.  Typically a plugin that wants
	to use the MediaShow functions stores the pointers in
	AcceptCallbacks() and does little else.

Parameters:
	Input:
		a structure containing pointers to MediaShow functions

	Output:
		none


Return Code:
	none

Example:

	typedef BOOL (WINAPI *fMediaShow_IsPlayNow)(LPCSTR szFile, const PLUGIN_DATETIME dtPlay, BOOL *bResult);
	typedef void (WINAPI *fMediaShow_Log)(LPCSTR);
	typedef void (WINAPI *fMediaShow_GetTimeInfo)(BYTE *frames_per_second, DWORD *pdwReserved1, DWORD *pdwReserved2, DWORD *pdwReserved3);  // MediaShow 3.6s24 or later required
	typedef void (WINAPI *fMediaShow_GetShowing)(LPSTR szZone, const size_t sizeZone, LPSTR szMag, const size_t sizeMag, LPSTR szScript, const size_t sizeScript, LONG *iIndex_out, LONG *iScriptItems_out, LPSTR szPage, const size_t sizePage, LPSTR szTargetPage, const size_t sizeTargetPage, LPSTR szExtra, const size_t sizeExtra); // MediaShow 3.6t12 or later required
	typedef void (WINAPI *fMediaShow_GetDisplayInfo)(LPSTR szPlaybackEngine, const size_t sizePlaybackEngine, LPSTR szDisplayWith, const size_t sizeDisplayWith); // More info to come
	typedef void (WINAPI *fMediaShow_GetVar)(LPCSTR szPage, LPCSTR szName, LPSTR szValue, const size_t); 

	typedef struct
	{
		DWORD	size;				
		fMediaShow_IsPlayNow	pIsPlayNow;
		fMediaShow_Log			pLog;
		fMediaShow_GetTimeInfo	pGetTimeInfo;		// Added 2004Oct27
		fMediaShow_GetShowing	pGetShowing;		// Added 2005May25
		fMediaShow_GetDisplayInfo	pGetDisplayInfo;	// Added 2006Jul13
		fMediaShow_GetVar		pGetVar;			// Added 2015apr21
		LPVOID	pReserved[18];
	} PLUGIN_CALLBACKS_EX;


	static fMediaShow_GetShowing	pGetShowing = NULL;
	
	extern "C" void WINAPI _export AcceptCallbacks(PLUGIN_CALLBACKS_EX *pCallbacks)
	{
		// Just stash the pointers to the function(s) you want and exit
		pGetShowing = pCallbacks->GetShowing;
	}
	
	// Elsewhere in the plugin you can use the functions:
	void Foo(PLUGIN_DATETIME dt)
	{
		BOOL	bResult;
		BYTE	frames_per_second;
		
		pMediaShow_IsPlayNow("c:\media\pages\news.pge", dt, &bResult);
		pMediaShow_Log("Hello\n");
		pMediaShow_GetTimeInfo(&frames_per_second, NULL, NULL, NULL);
		
		char	szZone[MAX_PATH+1];
		char	szMag[MAX_PATH+1];
		char	szPageList[MAX_PATH+1];
		LONG	iScriptIndex;
		LONG	iScriptItems;
		char	szPage[MAX_PATH+1];
		char	szTargetPage[MAX_PATH+1];
		char	szExtra[1024];
		
		pMediaShow_GetShowing(szZone, sizeof(szZone), szMag, sizeof(szMag), szPageList, sizeof(szPageList), &iScriptIndex, &iScriptItems, szPage, sizeof(szPage), szTargetPage, sizeof(szTargetPage), szExtra, sizeof(szExtra));
	}
	

Now you know how the plugin functions work.  Here is a complete
example - the entire source for the Month plugin...


--- cut here --- month.cpp --------------------------

//
// Example MediaShow page or magazine plugin
// Copyright ? 1997-2001, DiGiMATiON

// Uncomment in Borland
#include <windows.h>
#pragma hdrstop

// Uncomment in Visual C++
//#include "stdafx.h"

#include "plugin.h"

typedef enum
{
	WINTER,
	SPRING,
	SUMMER,
	FALL
} SEASON;

static SEASON season_table[12] =
{
	WINTER, // Jan
	WINTER, // Feb
	SPRING, // Mar
	SPRING, // Apr
	SPRING, // May
	SUMMER, // Jun
	SUMMER, // Jul
	SUMMER, // Aug
	FALL, // Sep
	FALL, // Oct
	FALL, // Nov
	WINTER, // Dec
};

typedef enum
{
	Q1,
	Q2,
	Q3,
	Q4
} QUARTER;

static QUARTER quarter_table[12] =
{
	Q1, // Jan
	Q1, // Feb
	Q1, // Mar
	Q2, // Apr
	Q2, // May
	Q2, // Jun
	Q3, // Jul
	Q3, // Aug
	Q3, // Sep
	Q4, // Oct
	Q4, // Nov
	Q4, // Dec
};

#ifndef CEQ
#define CEQ(_a,_b)              (stricmp((_a),(_b)) == 0)
#endif

#pragma argsused
extern "C" BOOL WINAPI _export IsPlayNow(WORD argc, LPCSTR argv[], LPCSTR szFile, DATETIME dt, BOOL *bIsPlayNow)
{
	SEASON                  season;
	QUARTER                 quarter;
	BOOL                            bResult = TRUE;

	// For safety - if we crash so does MediaShow!
	if ((szFile == NULL) || (bIsPlayNow == NULL)) return FALSE;
   if (argc != 1) return FALSE;

	season = season_table[dt.Month - 1];
	quarter = quarter_table[dt.Month - 1];

	if (CEQ(argv[0], "Winter"))
	{
		*bIsPlayNow = (season == WINTER);
	}
	else if (CEQ(argv[0], "Spring"))
	{
		*bIsPlayNow = (season == SPRING);
	}
	else if (CEQ(argv[0], "Summer"))
	{
		*bIsPlayNow = (season == SUMMER);
	}
	else if (CEQ(argv[0], "Fall"))
	{
		*bIsPlayNow = (season == FALL);
	}
	else if (CEQ(argv[0], "q1"))
	{
		*bIsPlayNow = (quarter == Q1);
	}
	else if (CEQ(argv[0], "q2"))
	{
		*bIsPlayNow = (quarter == Q2);
	}
	else if (CEQ(argv[0], "q3"))
	{
		*bIsPlayNow = (quarter == Q3);
	}
	else if (CEQ(argv[0], "q3"))
	{
		*bIsPlayNow = (quarter == Q3);
	}
	else
	{
		bResult = FALSE;
	}

	return bResult;
}

/*
// Not needed so commented out
extern "C" void WINAPI _export OnDraw(WORD argc, LPCSTR argv[], LPCSTR szPage, LPSTR szBitmap, const size_t sizeBitmap)
{
	// Do nothing
}

extern "C" void WINAPI _export OnPreLoad(WORD argc, LPCSTR argv[], LPCSTR szFile)
{
	// Do nothing
}

extern "C" void WINAPI _export OnPlayEarly(WORD argc, LPCSTR argv[], LPCSTR szFile)
{
	// Do nothing
}

extern "C" void WINAPI _export OnPlay(WORD argc, LPCSTR argv[], LPCSTR szFile)
{
	// Do nothing
}
*/

extern "C" void WINAPI _export GetDescription(LPSTR szDesc, const size_t size)
{
	lstrcpyn(szDesc, "Knows all about months", size);
}

extern "C" BOOL WINAPI _export GetPlayPredict(PLUGIN_PLAY_PREDICT *pPredict)
{
	ZeroMemory(pPredict, sizeof(PLUGIN_PLAY_PREDICT));
	pPredict->bVaryByDate = TRUE;
	return TRUE;
}

// Optional, necessary if you want the plugin to have a GUI
extern "C" DWORD WINAPI _export extern "C" _export EditPlugin(LPSTR szCommandLine, const DWORD dwSize)
{
	// The month plugin has a GUI but it has been omitted for this example
	return FALSE;
}

--- cut here --- plugin.h --------------------------

//
//	MediaShow plugin header
// Copyright ? 1997-2001, DiGiMATiON

#ifndef _MEDIASHOW_PLUGIN_H
#define _MEDIASHOW_PLUGIN_H

#ifndef BYTE
#define BYTE 	unsigned char
#endif

#ifndef WORD
#define WORD	unsigned short
#endif

// Ensure no padding in VC++
#ifdef _MSC_VER
#pragma pack(0);
#endif

typedef struct
{
	WORD Year; 		// 4 digits - eg 1997
	BYTE Month;    // 1 to 12 - January is 1
	BYTE Day;      // 1 to 31 - Day of the month
	BYTE Frame;    // 0 to 29
	BYTE Second;   // 0 to 59
	BYTE Minute;   // 0 to 59
	BYTE Hour;     // 0 to 23
} DATETIME;

#ifdef __cplusplus
extern "C" {
#endif

// Magazine, Screen and Page plugins

// Should we play the given time?
//
// Input:
//		argc and argv: command line in C main() style
//		szFile: full path to the page/mag/screen in question
//		dtPlay: the date/time we are being asked about (not the present time)
// Output:
//		return value: could we determine whether or not to play
//		bIsPlayNow: if return value is true this holds the result
BOOL WINAPI _export IsPlayNow(const WORD argc, LPCSTR argv[], LPCSTR szFile, const DATETIME dtProposedPlayTime, BOOL *bIsPlayNow);

// We have been selected to be play (no longer have a choice)
// maybe we want to do something - only put this function in your plugin if it does something.
void WINAPI _export OnPreLoad(const WORD argc, LPCSTR argv[], LPCSTR szFile);

// This page/mag/screen/etc is about to start playing - only put this function in your plugin if it does something.
void WINAPI _export OnPlayEarly(const WORD argc, LPCSTR argv[], LPCSTR szFile);

// This page/mag/screen/etc has just started playing - only put this function in your plugin if it does something.
void WINAPI _export OnPlay(const WORD argc, LPCSTR argv[], LPCSTR szFile);

// Return a human-readable which says what the plugin does - mandatory
void WINAPI _export GetDescription(LPSTR szDesc, const size_t size);

// Provide info about what IsPlayNow() does
BOOL WINAPI _export GetPlayPredict(PLUGIN_PLAY_PREDICT *);

// Display a GUI to edit the plugins command line.
// example szCommandLine = "MyPlugin=Option1 Option1"
// Output:
//		return value: TRUE if the user clicked on OK, otherwise FALSE
DWORD WINAPI _export EditPlugin(LPSTR szCommandLine, const DWORD dwSize);

//----------------------
// Script plugins

// Input:
//		argc and argv: command line in C main() style
//		szFile: full path to the script in question
//		dtPlay: the date/time we are being asked about (not the present time)
//		wResult: size of the result buffer (typically 256bytes)
// Output:
//		return value: could we determine a page to return (or not)
//		szResult: a buffer passed into GetPage where you put the name of the page
//              If in the same directory as script you don't need to return the full path
//              - eg "tick34.pge" - this is cleaner.  But if in another directory you must
//			       return the full path
BOOL WINAPI _export GetPages(const WORD argc, LPCSTR argv[], LPCSTR szFile, const DATETIME dtProposedPlayTime, LPSTR szResult, const WORD wResultSize);

#ifdef __cplusplus
}
#endif

#endif