1 /* 2 * libzvbi - Program Delivery Control 3 * 4 * Copyright (C) 2000-2004 Michael H. Schimek 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License version 2 as 8 * published by the Free Software Foundation. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 18 */ 19 20 /* $Id: pdc.h,v 1.6 2009/03/23 01:30:19 mschimek Exp $ */ 21 22 #ifndef __ZVBI_PDC_H__ 23 #define __ZVBI_PDC_H__ 24 25 #include <stdio.h> /* FILE */ 26 #include <inttypes.h> /* uint8_t */ 27 28 #include "version.h" 29 #include "macros.h" 30 #include "bcd.h" /* vbi_pgno */ 31 #include "network.h" /* vbi_cni_type */ 32 33 VBI_BEGIN_DECLS 34 35 /* Public */ 36 37 #include <time.h> /* time_t */ 38 39 /** 40 * @addtogroup ProgramID 41 * @{ 42 */ 43 44 /** 45 * @brief Program Identification Label. 46 * 47 * This is a packed representation of the originally announced start 48 * date and time ("AT-2" in EN 300 231 parlance, "Scheduled Start 49 * Time" in EIA 608-B) of a program. 50 * 51 * @since 0.2.34 52 */ 53 typedef unsigned int vbi_pil; 54 55 /** 56 * @brief Macro to create a PIL. 57 * 58 * Valid values for @a month are 1 ... 12, for @a day 1 ... 31, for 59 * @a hour 0 ... 23 and for @a minute 0 ... 59. 60 * 61 * Note in the PDC system (EN 300 231) networks may also transmit 62 * unreal dates or times like 14-00 25:63. You can determine if a PIL 63 * represents a valid date and time with the vbi_pil_is_valid_date() 64 * function. 65 * 66 * @since 0.2.34 67 */ 68 #define VBI_PIL(month, day, hour, minute) \ 69 (((day) << 15) | ((month) << 11) | ((hour) << 6) | (minute)) 70 71 /** Extract the month from a PIL. Valid values are in range 1 ... 12. */ 72 #define VBI_PIL_MONTH(pil) (((pil) >> 11) & 15) 73 74 /** Extract the day from a PIL. Valid values are in range 1 ... 31. */ 75 #define VBI_PIL_DAY(pil) (((pil) >> 15) & 31) 76 77 /** Extract the hour from a PIL. Valid values are in range 0 ... 23. */ 78 #define VBI_PIL_HOUR(pil) (((pil) >> 6) & 31) 79 80 /** Extract the minute from a PIL. Valid values are in range 0 ... 59. */ 81 #define VBI_PIL_MINUTE(pil) ((pil) & 63) 82 83 /** 84 * @brief PIL Service Codes. 85 * 86 * PILs can be zero, or specify a valid date and time, or an unreal 87 * time such as 31:00 if a new label has been assigned to a program 88 * but no transmission time has been decided yet. Some PILs with 89 * unreal date and time have a special meaning. 90 * 91 * These codes are defined in EN 300 231 Section 6.2, Annex E.3 and 92 * Annex F, and in EIA 608-B Section 9.5.1.1. 93 * 94 * @since 0.2.34 95 */ 96 enum { 97 /** 98 * Only in Teletext packets 8/30 format 2, VPS packets and DVB 99 * PDC descriptors: "Timer Control". 100 * 101 * No program IDs are available, use the timer to control 102 * recording. 103 */ 104 VBI_PIL_TIMER_CONTROL = VBI_PIL (15, 0, 31, 63), 105 106 /** 107 * Teletext, VPS, DVB: "Recording Inhibit/Terminate". 108 * 109 * When the PIL changes from a valid program label to @c 110 * VBI_PIL_INHIBIT_TERMINATE the current program has ended and 111 * the next program has not started yet. VCRs recording the 112 * current program shall stop recording and remove the program 113 * from their schedule. VCRs waiting for a new PIL shall 114 * continue waiting. 115 */ 116 VBI_PIL_INHIBIT_TERMINATE = VBI_PIL (15, 0, 30, 63), 117 118 /** 119 * Teletext, VPS, DVB: "Interruption". 120 * 121 * When the PIL changes from a valid program label to @c 122 * VBI_PIL_INTERRUPTION, the current program has stopped but 123 * will continue later. This code is transmitted for example 124 * at the start of a halftime pause or at a film break. VCRs 125 * recording the current program shall stop recording, but not 126 * delete the program from their schedule. The network may 127 * broadcast other programs with different PILs before the 128 * interrupted program continues. VCRs waiting for a new PIL 129 * shall continue waiting. 130 */ 131 VBI_PIL_INTERRUPTION = VBI_PIL (15, 0, 29, 63), 132 133 /** 134 * Teletext, VPS, DVB: "Continuation code". 135 * 136 * This code is transmitted during a service interruption, 137 * the PDC service should resume operation shortly. VCRs 138 * recording the current program shall continue recording, 139 * VCRs waiting for a new PIL shall continue waiting. 140 */ 141 VBI_PIL_CONTINUE = VBI_PIL (15, 0, 28, 63), 142 143 /** 144 * Teletext, VPS, DVB: "No Specific PIL Value". 145 * 146 * Networks may transmit this label with an unplanned program 147 * such as an emergency message. The program type (PTY) field 148 * may still be valid. 149 */ 150 VBI_PIL_NSPV = VBI_PIL (15, 15, 31, 63), 151 152 /** 153 * Only in XDS Current Program ID packets: 154 * 155 * The current program has ended and the next program not 156 * started yet. 157 */ 158 VBI_PIL_END = VBI_PIL (15, 15, 31, 63) 159 }; 160 161 extern vbi_bool 162 vbi_pil_is_valid_date (vbi_pil pil); 163 extern time_t 164 vbi_pil_to_time (vbi_pil pil, 165 time_t start, 166 const char * tz); 167 extern time_t 168 vbi_pil_lto_to_time (vbi_pil pil, 169 time_t start, 170 int seconds_east); 171 extern vbi_bool 172 vbi_pty_validity_window (time_t * begin, 173 time_t * end, 174 time_t time, 175 const char * tz) 176 #ifndef DOXYGEN_SHOULD_SKIP_THIS 177 _vbi_nonnull ((1, 2)) 178 #endif 179 ; 180 extern vbi_bool 181 vbi_pil_validity_window (time_t * begin, 182 time_t * end, 183 vbi_pil pil, 184 time_t start, 185 const char * tz) 186 #ifndef DOXYGEN_SHOULD_SKIP_THIS 187 _vbi_nonnull ((1, 2)) 188 #endif 189 ; 190 extern vbi_bool 191 vbi_pil_lto_validity_window (time_t * begin, 192 time_t * end, 193 vbi_pil pil, 194 time_t start, 195 int seconds_east) 196 #ifndef DOXYGEN_SHOULD_SKIP_THIS 197 _vbi_nonnull ((1, 2)) 198 #endif 199 ; 200 201 /* Private */ 202 203 /** @} */ 204 205 extern void 206 _vbi_pil_dump (vbi_pil pil, 207 FILE * fp) 208 #ifndef DOXYGEN_SHOULD_SKIP_THIS 209 _vbi_nonnull ((2)) 210 #endif 211 ; 212 extern vbi_bool 213 _vbi_pil_from_string (vbi_pil * pil, 214 const char ** inout_s) 215 #ifndef DOXYGEN_SHOULD_SKIP_THIS 216 _vbi_nonnull ((1, 2)) 217 #endif 218 ; 219 220 /** 221 * @addtogroup ProgramID 222 * @{ 223 */ 224 225 /* Public */ 226 227 /** 228 * @brief Sources of PIDs. 229 * 230 * A program identification can be transmitted on different logical 231 * channels. Teletext packet 8/30 format 2 contains a Label Channel 232 * Identifier. XDS Program ID packets can refer to the current or next 233 * program. 234 * 235 * This information is returned in struct @a vbi_program_id by the low 236 * level functions vbi_decode_teletext_8302_pdc(), 237 * vbi_decode_vps_pdc(), vbi_decode_dvb_pdc_descriptor() and the @a 238 * vbi_decoder event @c VBI_EVENT_PROG_ID. 239 * 240 * @since 0.2.34 241 */ 242 typedef enum { 243 /** 244 * Data from Teletext packet 8/30 format 2, Label Channel 0 245 * (EN 300 706 section 9.8.2, EN 300 231 section 8.2.1). 246 * 247 * Teletext packets contain a CNI, PIL, LUF, MI, PRF, PCS and 248 * PTY. They are transmitted once per second for each Label 249 * Channel in use. 250 * 251 * The purpose of Label Channels is to transmit overlapping 252 * PIDs, for example one referring the current program and 253 * another announcing the imminent start of the next 254 * program. Programs can also have multiple PIDs, for example 255 * a sports magazine with several segments, where the entire 256 * program has a PID and each segment has its own PID, 257 * transmitted on a different Label Channel. 258 * 259 * Label Channels are used in no particular order or 260 * hierarchy. 261 */ 262 VBI_PID_CHANNEL_LCI_0 = 0, 263 264 /** Data from Teletext packet 8/30 format 2, Label Channel 1. */ 265 VBI_PID_CHANNEL_LCI_1, 266 267 /** Data from Teletext packet 8/30 format 2, Label Channel 2. */ 268 VBI_PID_CHANNEL_LCI_2, 269 270 /** Data from Teletext packet 8/30 format 2, Label Channel 3. */ 271 VBI_PID_CHANNEL_LCI_3, 272 273 /** 274 * Data from a VPS packet (EN 300 231). 275 * 276 * These packets contain a CNI, PIL, PCS and PTY. They are 277 * transmitted once in each frame, i.e. 25 times per second. 278 */ 279 VBI_PID_CHANNEL_VPS, 280 281 /** 282 * Data from a DVB PDC descriptor (EN 300 468 Section 6.2.29). 283 * 284 * DVB PDC descriptors contain the same PIL as a VPS packet, 285 * but no CNI, PCS or PTY. 286 */ 287 VBI_PID_CHANNEL_PDC_DESCRIPTOR, 288 289 /** 290 * Data from an XDS Current Program ID packet (EIA 608-B 291 * Section 9). 292 * 293 * XDS Current/Future Program ID packets contain a PIL and 294 * tape-delayed flag. Current class packets refer to the 295 * currently transmitted program, Future class packets to the 296 * next program. 297 * 298 * Decoding of XDS Current/Future Program ID packets is not 299 * implemented yet. 300 */ 301 VBI_PID_CHANNEL_XDS_CURRENT, 302 303 /** 304 * Data from an XDS Future Program ID packet. 305 */ 306 VBI_PID_CHANNEL_XDS_FUTURE, 307 308 /** Note this value may change. */ 309 VBI_MAX_PID_CHANNELS 310 } vbi_pid_channel; 311 312 /** 313 * @brief PDC Program Control Status - Audio. 314 * 315 * This information is available with Teletext and VPS program IDs and 316 * returned in struct vbi_program_id by the low level functions 317 * vbi_decode_teletext_8302_pdc(), vbi_decode_vps_pdc() and the @a 318 * vbi_decoder event @c VBI_EVENT_PROG_ID. 319 * 320 * @since 0.2.34 321 */ 322 typedef enum { 323 /** Nothing known about audio channels. */ 324 VBI_PCS_AUDIO_UNKNOWN = 0, 325 326 /** Mono audio is broadcast. */ 327 VBI_PCS_AUDIO_MONO, 328 329 /** Stereo audio. */ 330 VBI_PCS_AUDIO_STEREO, 331 332 /** Primary language on left channel, secondary on right. */ 333 VBI_PCS_AUDIO_BILINGUAL 334 } vbi_pcs_audio; 335 336 /** 337 * @brief Program Identification. 338 * 339 * This structure contains a Program ID received via Teletext packet 340 * 8/30 format 2, VPS, a DVB PDC descriptor or an XDS Current/Future 341 * Program ID packet. When the source does not provide all this 342 * information, libzvbi initializes the respective fields with an 343 * appropriate value. 344 * 345 * @since 0.2.34 346 */ 347 typedef struct { 348 /** Source of this PID. */ 349 vbi_pid_channel channel; 350 351 /** 352 * Network identifier type, one of 353 * - @c VBI_CNI_TYPE_NONE, 354 * - @c VBI_CNI_TYPE_8302 or 355 * - @c VBI_CNI_TYPE_VPS. 356 */ 357 vbi_cni_type cni_type; 358 359 /** 360 * Country and Network Identifier provided by Teletext packet 361 * 8/30 format 2 and VPS. Note when the source is Teletext and 362 * the LUF flag is set, this CNI may refer to a different 363 * network than the one transmitting the PID. 364 */ 365 unsigned int cni; 366 367 /** 368 * Program Identification Label. This is the only information 369 * available from all PID sources. 370 */ 371 vbi_pil pil; 372 373 /** 374 * PDC Label Update Flag (only transmitted in Teletext 375 * packets). When this flag is set, the PID is intended to 376 * update VCR memory, it does not refer to the current 377 * program. According to the examples in EN 300 231 Annex E.3 378 * however VCRs should probably also handle the PID as if a @c 379 * VBI_PIL_INHIBIT_TERMINATE service code was transmitted. 380 * 381 * This flag is used to announce a new PIL for the current 382 * program. The CNI may refer to a different network than the 383 * one transmitting the PID, for example when a program is 384 * about to overrun and will continue on a different network. 385 * If a program is postponed and no transmission time has been 386 * decided yet the new PIL may contain an arbitrary or unreal 387 * time. 388 */ 389 vbi_bool luf; 390 391 /** 392 * PDC Mode Identifier (Teletext). When @c TRUE the end of 393 * transmission of this PIL coincides exactly with the end of 394 * the program. When @c FALSE the program ends 30 seconds 395 * after the PIL is no longer transmitted. Note the flag 396 * applies to all valid PILs as well as the @c 397 * VBI_PIL_INHIBIT_TERMINATE and @c VBI_PIL_INTERRUPTION 398 * service codes. 399 */ 400 vbi_bool mi; 401 402 /** 403 * PDC Prepare to Record Flag (Teletext). When @c TRUE the 404 * program identified by this PID is about to start. A 405 * transition to @c FALSE indicates the immediate start of the 406 * program, regardless of the state of the MI flag. 407 */ 408 vbi_bool prf; 409 410 /** PDC Program Control Status - Audio (Teletext and VPS). */ 411 vbi_pcs_audio pcs_audio; 412 413 /** 414 * PDC Program Type code (Teletext and VPS), can be 0 or 0xFF 415 * if none or unknown. 416 */ 417 unsigned int pty; 418 419 /** 420 * XDS T flag. @c TRUE if a program is routinely tape delayed 421 * (for mountain and pacific time zones). @c FALSE if not or 422 * this is unknown. 423 * 424 * This flag is used to determine if an offset is necessary 425 * because of local station tape delays. The amount of tape 426 * delay used for a given time zone is transmitted in a XDS 427 * Channel Tape Delay packet. 428 */ 429 vbi_bool tape_delayed; 430 431 void * _reserved2[2]; 432 int _reserved3[4]; 433 } vbi_program_id; 434 435 /** @} */ 436 437 /* Private */ 438 439 extern void 440 _vbi_program_id_dump (const vbi_program_id * pid, 441 FILE * fp) 442 #ifndef DOXYGEN_SHOULD_SKIP_THIS 443 _vbi_nonnull ((1, 2)) 444 #endif 445 ; 446 447 448 VBI_END_DECLS 449 450 #endif /* __ZVBI_PDC_H__ */ 451 452 /* 453 Local variables: 454 c-set-style: K&R 455 c-basic-offset: 8 456 End: 457 */ 458