/* rlm.h * * The Rivendell Loadable Module Interface * * (C) Copyright 2008-2013 Fred Gleason * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2 as * published by the Free Software Foundation. * * 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., 675 Mass Ave, Cambridge, MA 02139, USA. * * * This interface can be used to create "Rivendell Loadable Modules" [RLMs] * that enable Rivendell's "Now & Next" capability to supply program associated * data [PAD] to external devices and systems. Runtime module configuration * is accomplished in RDAdmin->ManageHosts->RDAirPlay->ConfigureNow&Next. * * Compiled plugins are dynamically loadable libraries (DLLs) and have names * of the form '.rlm'. The following callbacks are provided: * * void _RLMStart(void *ptr,const char *arg) * Called once upon RDAirPlay startup. The plugin should do any necessary * startup tasks (opening i/o devices, allocating memory, etc) here. The * single argument 'arg' is a null-terminated string, consisting of the * 'Argument' parameter supplied in the specific runtime configuration * from RDAdmin. The 'ptr' argument is an opaque pointer that is * used as the first argument to the utility functions. * * void _RLMFree(void *ptr) * Called once upon RDAirPlay shutdown. Any system resources allocated * by the plugin should be released here. The 'ptr' argument is an opaque * pointer that is be used as the first argument to any of the utility * functions. * * * void _RLMPadDataSent(void *ptr,const struct rlm_svc *svc, * const struct rlm_log *log, * const struct rlm_pad *now, * const struct rlm_pad *next) * Called each time RDAirPlay changes play state on a log. The 'svc' * and 'log' parameters provide information about the current log and * service respectively. The 'ptr' argument is an opaque pointer that * is used as the first argument to the utility functions. * * WARNING: the structures provided in this callback are dynamically * allocated, their scope is valid only within the callback! * * void _RLMTimerExpired(void *ptr,int timernum) * Called each time the system RLM timer indicated by 'timernum' expires. * See the 'RLMStartTimer()' and 'RLMStopTimer()' functions for info on * using timers. The 'ptr' argument is an opaque pointer that is * used as the first argument to the utility functions. * * void _RLMSerialDataReceived(void *ptr,int handle, * const char *data,int len) * Called each time data is received on an open tty/serial device. See * the 'RLMOpenSerial()' and 'RLMCloseSerial()' functions for info on * using tty/serial devices. The 'ptr' argument is an opaque pointer * that is used as the first argument to the utility functions. */ #ifndef RLM_H #define RLM_H #include #include #ifdef __cplusplus extern "C" { #endif /* * RLM Interface Version */ #define RLM_VERSION 17 /* * Available Timers */ #define RLM_MAX_TIMERS 32 /* * Timer Modes * (for use in the RLMStartTimer() function). */ #define RLM_TIMER_REPEATING 0 #define RLM_TIMER_ONESHOT 1 /* * Parity Modes * (for use in the RLMOpenSerial() function). */ #define RLM_PARITY_NONE 0 #define RLM_PARITY_EVEN 1 #define RLM_PARITY_ODD 2 /* * Cart Types * (for use in the 'rlm_carttype' field of the 'rlm_pad' struct) */ #define RLM_CARTTYPE_ALL 0 #define RLM_CARTTYPE_AUDIO 1 #define RLM_CARTTYPE_MACRO 2 /* * Log Machine Modes * (for use in the 'rlm_mode' field of the 'rlm_log' struct) */ #define RLM_LOGMODE_LIVEASSIST 1 #define RLM_LOGMODE_AUTOMATIC 2 #define RLM_LOGMODE_MANUAL 3 /* * Data Encodings * (for use in the RLMResolveNowNextEncoded() function). */ #define RLM_ENCODE_NONE 0 #define RLM_ENCODE_XML 1 #define RLM_ENCODE_URL 2 /* * Service data structure */ struct rlm_svc { char svc_name[256]; /* Service name */ char svc_pgmcode[256]; /* Program Code */ char reserved[1536]; /* Reserved for future use */ }; /* * Log data structure */ struct rlm_log { char log_name[65]; /* Log name */ uint32_t log_mach; /* Log machine number, 0=Main, 1=Aux 1, 2=Aux2 */ char log_onair; /* On-air flag, 0=False, 1=True */ uint32_t log_mode; /* Log machine mode, 1=LiveAssist, 2=Automatic, 3=Manual */ char reserved[1974]; /* Reserved for future use */ }; /* * Metadata structure */ struct rlm_pad { uint32_t rlm_cartnum; /* Rivendell cart number */ uint32_t rlm_len; /* Event length, in milliseconds */ char rlm_year[5]; /* Cart year */ char rlm_group[11]; /* Rivendell Group Name */ char rlm_title[256]; /* Cart 'title' field */ char rlm_artist[256]; /* Cart 'artist' field */ char rlm_label[65]; /* Cart 'label' field */ char rlm_client[65]; /* Cart 'client' field */ char rlm_agency[65]; /* Cart 'agency' field */ char rlm_comp[65]; /* Cart 'composer' field */ char rlm_pub[65]; /* Cart 'publisher' field */ char rlm_userdef[256]; /* Cart 'user defined' field */ char rlm_album[256]; /* Cart 'album' field */ char rlm_isrc[12]; /* Cut International Standard Recording Code */ char rlm_isci[32]; /* Cut ISCI Code */ char rlm_carttype; /* Cart type, see RLM_CARTTYPE_* defines */ char rlm_ext_eventid[33]; /* Event ID, from external scheduler */ char rlm_ext_data[33]; /* Data, from external scheduler */ char rlm_ext_annctype[1]; /* Announcement Type, from external scheduler */ int32_t rlm_start_msec; /* Event start time, milliseconds part */ int32_t rlm_start_sec; /* Event start time, seconds part */ int32_t rlm_start_min; /* Event start time, minutes part */ int32_t rlm_start_hour; /* Event start time, hours part */ int32_t rlm_start_day; /* Event start date, day of month part */ int32_t rlm_start_mon; /* Event start date, month of year part */ int32_t rlm_start_year; /* Event start date, year part */ char rlm_conductor[65]; /* Cart 'conductor' field */ char rlm_song_id[33]; /* Cart 'songId' field */ char rlm_outcue[65]; /* Cut outcue field */ char rlm_description[65]; /* Cut description field */ char reserved[305]; /* Reserved for future use */ }; /* * Communications Functions * * * Send a UDP packet. * * The parameter is a null-terminated string consisting of the * IPv4 destination address in dotted-quad notation, and is the * destination UDP port number. All structures are in host (*not* network) * byte order. The data to be sent, of length , is pointed to by * . */ void RLMSendUdp(void *ptr,const char *ipaddr,uint16_t port, const char *data,int len); /* * Open a tty device (serial port) for output. * * The parameter is a null-terminated string consisting of the * name of the tty device to open (e.g. "/dev/ttyS0"). The , * and parameters define the communications * parameters to be used. * * RETURNS: if successful, a non-negative integer that should be used * as the argument for the RLMSendSerial() and RLMCloseSerial() * functions. If unsuccessful, a negative integer will be returned. */ int RLMOpenSerial(void *ptr,const char *devname,int speed, int parity,int word_length); /* * Output data on a tty device. * * Output data of length pointed to by on the tty device * indicated by the value returned by the RLMOpenSerial() function. */ void RLMSendSerial(void *ptr,int handle,const char *data,int len); /* * Close a tty device. * * Close the tty device indicated by the value returned by the * RLMOpenSerial() function. */ void RLMCloseSerial(void *ptr,int handle); /* * Convienence Functions */ /* * Get a string indicating the system time. * * Returns a pointer to a null-terminated string indicating the system time, * formatted as per the argument. The following wildcards are * supported: * d the day as number without a leading zero (1-31) * dd the day as number with a leading zero (01-31) * ddd the abbreviated localized day name (e.g. 'Mon'..'Sun'). * dddd the long localized day name (e.g. 'Monday'..'Sunday'). * M the month as number without a leading zero (1-12) * MM the month as number with a leading zero (01-12) * MMM the abbreviated localized month name (e.g. 'Jan'..'Dec'). * MMMM the long localized month name (e.g. 'January'..'December'). * yy the year as two digit number (00-99) * yyyy the year as four digit number (1752-8000) * h the hour without a leading zero (0..23 or 1..12 if AM/PM * display) * hh the hour with a leading zero (00..23 or 01..12 if AM/PM display) * m the minute without a leading zero (0..59) * mm the minute with a leading zero (00..59) * s the second whithout a leading zero (0..59) * ss the second whith a leading zero (00..59) * z the milliseconds without leading zeroes (0..999) * zzz the milliseconds with leading zeroes (000..999) * AP use AM/PM display. AP will be replaced by either "AM" or "PM". * ap use am/pm display. ap will be replaced by either "am" or "pm". * * RETURNS: A pointer to a null terminated string. This string is statically * allocated, and may be reused in subsequent calls to the utility functions. */ const char *RLMDateTime(void *ptr,int offset_msecs,const char *format); /* * Resolve standard Rivendell Now & Next wildcards, with the possiblity * to encode the PAD fields. * * Returns a pointer to a null-terminated string resulting from resolving * the 'standard' Rivendell Now & Next wildcards in accordance with the * data values in the and parameters. The following wildcards * are supported: * * Now Next Field * ---------------------------------------------- * %n %N The Rivendell cart number * %h %H Event length (in milliseconds) * %g %G The Rivendell group name * %t %T Title * %a %A Artist * %l %L Album * %y %Y Year * %b %B Record Label * %c %C Client * %e %E Agency * %m %M Composer * %p %P Publisher * %r %R Conductor * %s %S Song ID * %u %U User Definied * %o %O Outcue * %i %I Description * %D(
) The current date/time, formatted according to
.
* can be any of the wildcards supported by the RLMDateTime() * function (see above). * * Additionally, an encoding can be specified to allow PAD fields to be * escaped for a particular format. Available encodings are: * * RLM_ENCODE_NONE - Perform no character escaping. * RLM_ENCODE_XML - Escape reserved characters as per XML-v1.0 * RLM_ENCODE_URL - Escape reserved characters as per RFC 2396 Section 2.4 * * RETURNS: A pointer to a null terminated string. This string is statically * allocated, and may be reused in subsequent calls to the utility functions. */ const char *RLMResolveNowNextEncoded(void *ptr,const struct rlm_pad *now, const struct rlm_pad *next, const char *format,int encoding); /* * Resolve standard Rivendell Now & Next wildcards * * (NOTE: This function is deprecated, and included merely to keep old code * working. It should *not* be used in new code. For a better alternative, * see the RLMResolveNowNextEncoded() function above). * * Returns a pointer to a null-terminated string resulting from resolving * the 'standard' Rivendell Now & Next wildcards in accordance with the * data values in the and parameters. The list of available * wildcards can be found in the 'metadata_wildcards.txt' file in the * Rivendell documentation directory. * * RETURNS: A pointer to a null terminated string. This string is statically * allocated, and may be reused in subsequent calls to the utility functions. */ const char *RLMResolveNowNext(void *ptr,const struct rlm_pad *now, const struct rlm_pad *next,const char *format); void RLMLog(void *ptr,int prio,const char *msg); void RLMStartTimer(void *ptr,int timernum,int msecs,int mode); void RLMStopTimer(void *ptr,int timernum); int RLMGetIntegerValue(void *ptr,const char *filename,const char *section, const char *label,int default_value); int RLMGetHexValue(void *ptr,const char *filename, const char *section,const char *label,int default_value); int RLMGetBooleanValue(void *ptr,const char *filename, const char *section,const char *label, int default_value); const char *RLMGetStringValue(void *ptr,const char *filename, const char *section,const char *label, const char *default_value); #ifdef __cplusplus } #endif #endif /* RLM_H */