git.sesse.net Git - vlc/blob - extras/MacOSX/eyetvplugin/EyeTVPluginDefs.h

   1 /* This is public domain code developed by Elgato Systems GmbH. No GPL-covered \r
   2  * changes were added to this file by any members of the VideoLAN team. If you\r
   3  * want to do so, add a modified GPL header here, but keep a message emphasising\r
   4  * the non-licensed parts of this header file. \r
   5  * Ideally, VideoLAN-related changes should only go to eyetvplugin.h.\r
   6  * \r
   7  * $Id$\r
   8  */\r
   9 \r
  10 \r
  11 #pragma once\r
  12 \r
  13 /*\r
  14 \r
  15         The EyeTV Plugin API\r
  16         ====================\r
  17         \r
  18         The EyeTV Software gives third parties access to the incoming MPEG-2 transport stream. \r
  19         At this time the API is available for the following products:\r
  20                 \r
  21                 - EyeTV 200 (analog)\r
  22                 - EyeTV 300 (DVB-S) \r
  23                 - EyeTV 400 (DVB-T)\r
  24                 \r
  25         A plugin receives device plugged/unplugged notifications, it can request or release \r
  26         individual PIDs and most importantly it has access to transport stream packets in \r
  27         real time, as they arrive from the device.  Note that the plugin is called before EyeTV \r
  28         itself looks at the packets, so it is even possible to modify the data.\r
  29         \r
  30         Plugins currently live in EyeTV.app/Contens/Plugins/\r
  31         \r
  32         A plugin is packaged as a bundle with a single entry point:\r
  33         \r
  34                 long EyeTVPluginDispatcher(EyeTVPluginSelector                  selector,  \r
  35                                                                                 void                                    *refCon, \r
  36                                                                                 EyeTVPluginDeviceID             deviceID, \r
  37                                                                                 long                                    param1, \r
  38                                                                                 long                                    param2,  \r
  39                                                                                 long                                    param3, \r
  40                                                                                 long                                    param4);\r
  41 \r
  42         \r
  43         PID Filtering\r
  44         =============\r
  45         \r
  46         EyeTV employs both hardware and software PID filtering.  A plugin's dispatch routine \r
  47         is called with the kEyeTVPluginSelector_PacketsArrived selector after the hardware \r
  48         PID filter (naturally) but prior to the software PID filter, so the plugin has access \r
  49         to all packets that are delivered by the hardware.  \r
  50         \r
  51         A plugin can request PIDs that are not needed by EyeTV from the hardware PID filter by \r
  52         means of a callback routine, see eyeTVPluginSelector_SetCallback.\r
  53 \r
  54         Note that hardware PID filtering is on for single processor machines (to reduce the CPU \r
  55         load), but off for multi-processor machines (to improve channel switch times).  \r
  56         This behaviour is controlled by the "hardware PID filter" key in com.elgato.eyetv.plist, \r
  57         which defaults to "Auto" ("Off" on MP machines, "On" on single-processor machines).  EyeTV\r
  58         does not offer GUI to change this setting.  A plugin hence needs to be prepared to handle \r
  59         both an entire transponder or multiplex and to request PIDs it might need.\r
  60         \r
  61         Note that the plugin is called on the real-time thread that receives the transport stream\r
  62         packets and that the packet buffers passed to the plugin are the actual hardware DMA buffers.\r
  63         Please return as quickly as possible from the kEyeTVPluginSelector_PacketsArrived call and\r
  64         avoid blocking the calling thread.\r
  65 \r
  66 \r
  67 \r
  68 \r
  69 \r
  70         Revision History:\r
  71 \r
  72         02/27/2004:             Initial Release.\r
  73 \r
  74 */\r
  75         \r
  76 \r
  77 \r
  78 #define EYETV_PLUGIN_API_VERSION                                0x04021901\r
  79 #define EYETV_PLUGIN_API_MIN_VERSION                    0x04021901\r
  80 \r
  81 typedef long long       EyeTVPluginDeviceID;\r
  82 typedef long            EyeTVPluginDeviceType;\r
  83 typedef long            EyeTVPluginSelector;\r
  84 \r
  85 enum {\r
  86         kEyeTVPIDType_Video             = 0,\r
  87         kEyeTVPIDType_MPEGAudio         = 1,\r
  88         kEyeTVPIDType_VBI                       = 2, /* teletext */\r
  89         kEyeTVPIDType_PCR                       = 3,\r
  90         kEyeTVPIDType_PMT                       = 4,\r
  91         kEyeTVPIDType_Unknown           = 5,\r
  92         kEyeTVPIDType_AC3Audio          = 6\r
  93 };\r
  94 \r
  95 \r
  96 typedef struct EyeTVPluginPIDInfo EyeTVPluginPIDInfo;\r
  97 struct EyeTVPluginPIDInfo {\r
  98         long                                    pid;\r
  99         long                                    pidType;        \r
 100 };\r
 101 \r
 102 \r
 103 \r
 104 /***********************************************************************************\r
 105 *\r
 106 *       EyeTVPluginCallbackParams,\r
 107 *\r
 108 ***********************************************************************************/\r
 109 enum {\r
 110         kEyeTVPluginCallbackSelector_RetainPIDs = 0,    \r
 111         kEyeTVPluginCallbackSelector_ReleasePIDs = 1            \r
 112 };\r
 113 \r
 114 typedef struct EyeTVPluginCallbackParams EyeTVPluginCallbackParams;  \r
 115 struct EyeTVPluginCallbackParams {\r
 116         EyeTVPluginDeviceID             deviceID;       //      the deviceID\r
 117         long                                    selector;       //      callback selector, see above\r
 118         long                                    *pids;          //      list of pids to release/retain\r
 119         long                                    pidsCount;      //      count of pids\r
 120 };\r
 121 \r
 122 \r
 123 /***********************************************************************************\r
 124 *\r
 125 *       typedef for the callback function,\r
 126 *\r
 127 ***********************************************************************************/\r
 128 typedef long(* EyeTVPluginCallbackProc)(EyeTVPluginCallbackParams *params);\r
 129 \r
 130 \r
 131 \r
 132 /***********************************************************************************\r
 133 *\r
 134 *       EyeTVPluginParamStructs\r
 135 *\r
 136 ***********************************************************************************/\r
 137 \r
 138 \r
 139 typedef struct EyeTVPluginInitializeParams      EyeTVPluginInitializeParams;\r
 140 struct EyeTVPluginInitializeParams {\r
 141         long                                                    apiVersion;             // version of the EyeTV_PLUGIN_API\r
 142         EyeTVPluginCallbackProc                 callback;               // the callback\r
 143 }; /* 8 bytes */\r
 144 \r
 145 \r
 146 \r
 147 typedef struct EyeTVPluginGetInfoParams EyeTVPluginGetInfoParams;\r
 148 struct EyeTVPluginGetInfoParams {\r
 149         long                                                    *pluginAPIVersion;              // <- EYETV_PLUGIN_API_VERSION\r
 150         char                                                    *pluginName;            // <- points to a 128-byte buffer, the plugin is expected to fill the buffer with\r
 151                                                                                                                 //        a UTF-8 encoded string.       \r
 152         char                                                    *description;           // <- points to a 1024-byte buffer, the plugin is expected to fill the buffer with\r
 153                                                                                                                 //        a UTF-8 encoded string describing the plugin.\r
 154 }; /* 12 bytes */\r
 155 \r
 156 \r
 157 \r
 158 enum {\r
 159         kEyeTVPluginDeviceType_Unknown = 0,     \r
 160         kEyeTVPluginDeviceType_e200 = 1,\r
 161         kEyeTVPluginDeviceType_e300 = 2,\r
 162         kEyeTVPluginDeviceType_e400 = 3\r
 163 } ;\r
 164 \r
 165 typedef struct EyeTVPluginDeviceAddedParams EyeTVPluginDeviceAddedParams;\r
 166 struct EyeTVPluginDeviceAddedParams {\r
 167         EyeTVPluginDeviceType                   deviceType;             \r
 168 }; /* 4 bytes */\r
 169 \r
 170 \r
 171 typedef struct EyeTVPluginPacketsArrivedParams EyeTVPluginPacketsArrivedParams;\r
 172 struct EyeTVPluginPacketsArrivedParams {\r
 173         long                                                    **packets;              // points to an array of packets\r
 174         long                                                    packetCount;    \r
 175 }; /* 8 bytes */\r
 176 \r
 177 \r
 178 \r
 179 typedef struct EyeTVPluginServiceChangedParams EyeTVPluginServiceChangedParams;\r
 180 struct EyeTVPluginServiceChangedParams {\r
 181         long                                                    headendID;              // new headend ID. For E300 it's the orbital position of the satellite\r
 182                                                                                                         // in tenth of a degree\r
 183         long                                                    transponderID;  // new transponder ID (The Frequency in kHz)\r
 184         long                                                    serviceID;              // new service ID (the ID of the used service as included in the DVB Stream)\r
 185         EyeTVPluginPIDInfo                              *pidList;               // points to the list of active PIDs;\r
 186         long                                                    pidCount;               // the length of pidList\r
 187 }; /* 20 bytes */\r
 188 \r
 189 \r
 190 \r
 191 \r
 192 /***********************************************************************************\r
 193 *\r
 194 *       EyeTVPluginParams\r
 195 *               \r
 196 ***********************************************************************************/\r
 197 typedef struct EyeTVPluginParams EyeTVPluginParams;\r
 198 struct EyeTVPluginParams {\r
 199         EyeTVPluginDeviceID             deviceID;       // ID of the device\r
 200         EyeTVPluginSelector             selector;       // selector\r
 201         void                                    *refCon;        // refCon\r
 202 \r
 203         union {                                                                                         \r
 204                 EyeTVPluginInitializeParams                     initialize;                     // kEyeTVPluginSelector_Initialize\r
 205                                                                                                                                 // kEyeTVPluginSelector_Terminate, no additional parameters\r
 206                 EyeTVPluginGetInfoParams                        info;                           // kEyeTVPluginSelector_GetInfo\r
 207                 EyeTVPluginDeviceAddedParams            deviceAdded;            // kEyeTVPluginSelector_DeviceAdded\r
 208                                                                                                                                 // kEyeTVPluginSelector_DeviceRemoved, no additional parameters\r
 209                 EyeTVPluginPacketsArrivedParams         packetsArrived;         // kEyeTVPluginSelector_PacketsArrived\r
 210                 EyeTVPluginServiceChangedParams         serviceChanged;         // kEyeTVPluginSelector_ServiceChanged\r
 211         \r
 212         };\r
 213 };\r
 214 \r
 215 \r
 216 enum {          // EyeTVPluginSelector\r
 217         kEyeTVPluginSelector_Initialize = 0,            \r
 218         kEyeTVPluginSelector_Terminate = 1,                     \r
 219         kEyeTVPluginSelector_GetInfo = 2,                       \r
 220         kEyeTVPluginSelector_DeviceAdded = 3,           \r
 221         kEyeTVPluginSelector_DeviceRemoved = 4,         \r
 222         kEyeTVPluginSelector_PacketsArrived = 5,        \r
 223         kEyeTVPluginSelector_ServiceChanged = 6 \r
 224 };                                              \r
 225 \r
 226 \r
 227 \r
 228 /***********************************************************************************\r
 229 *\r
 230 *       EyeTVPluginEntryProc\r
 231 *\r
 232 ***********************************************************************************/\r
 233 typedef long(* EyeTVPluginEntryProc)(EyeTVPluginParams *params);\r