HBBTV  22.11.0
hbbtv.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
3  * Copyright © 2014 Ocean Blue Software Ltd
4  *
5  * This file is part of a DTVKit Software Component
6  * You are permitted to copy, modify or distribute this file subject to the terms
7  * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
8  *
9  * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
10  * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
11  * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
12  *
13  * If you or your organisation is not a member of DTVKit then you have access
14  * to this source code outside of the terms of the licence agreement
15  * and you are expected to delete this and any associated files immediately.
16  * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
17  *******************************************************************************/
26 /* pre-processor mechanism so multiple inclusions don't cause compilation error*/
27 
28 #ifndef _HBBTV_H
29 
30 #define _HBBTV_H
31 
32 #include "techtype.h"
33 #include "hbbtv_types.h"
34 
35 /*---Constant and macro definitions for public use-----------------------------*/
36 
37 #define HBBTV_DBG_THBBAPI 1
38 #define HBBTV_DBG_TAIT (1 << 2)
39 #define HBBTV_DBG_TKEYS (1 << 3)
40 #define HBBTV_DBG_TAPP (1 << 4)
41 #define HBBTV_DBG_TPVR (1 << 5)
42 #define HBBTV_DBG_TAV (1 << 6)
43 #define HBBTV_DBG_TOBJS (1 << 7)
44 #define HBBTV_DBG_TSTRMEV (1 << 8)
45 #define HBBTV_DBG_TVB (1 << 9)
46 #define HBBTV_DBG_TCHN (1 << 10)
47 #define HBBTV_DBG_TAVC (1 << 11)
48 #define HBBTV_DBG_TSRCH (1 << 12)
49 #define HBBTV_DBG_TDRM (1 << 13)
50 
54 #define HBBTV_CAP_DL 1
55 
59 #define HBBTV_CAP_PVR 2
60 
64 #define HBBTV_CAP_DRM 4
65 
66 
67 /*---Enumerations for public use-----------------------------------------------*/
68 
69 typedef enum
70 {
71  HBBTV_CHANNEL_CHANGE_SUCCEEDED,
72  HBBTV_CHANNEL_CHANGE_WRONG_TUNER,
73  HBBTV_CHANNEL_CHANGE_NO_SIGNAL,
74  HBBTV_CHANNEL_CHANGE_TUNER_IN_USE,
75  HBBTV_CHANNEL_CHANGE_PARENTAL_LOCKED,
76  HBBTV_CHANNEL_CHANGE_ENCRYPTED,
77  HBBTV_CHANNEL_CHANGE_UNKNOWN_CHANNEL,
78  HBBTV_CHANNEL_CHANGE_INTERRUPTED,
79  HBBTV_CHANNEL_CHANGE_RECORDING_IN_PROGRESS,
80  HBBTV_CHANNEL_CHANGE_INSUFFICIENT_RESOURCES,
81  HBBTV_CHANNEL_CHANGE_CHANNEL_NOT_IN_TS,
82  HBBTV_CHANNEL_CHANGE_UNKNOWN_ERROR
83 } E_HBBTV_CHANNEL_CHANGE_STATUS;
84 
85 typedef enum
86 {
87  HBBTV_MP_STOPPED = 0,
88  HBBTV_MP_PLAYING,
89  HBBTV_MP_PAUSED,
90  HBBTV_MP_CONNECTING,
91  HBBTV_MP_BUFFERING,
92  HBBTV_MP_EOF,
93  HBBTV_MP_ERROR
94 } E_HBBTV_MP_STATE;
95 
96 typedef enum
97 {
98  HBBTV_RECPLAYER_STOPPED,
99  HBBTV_RECPLAYER_PLAYING,
100  HBBTV_RECPLAYER_PAUSED,
101  HBBTV_RECPLAYER_BUFFERING,
102  HBBTV_RECPLAYER_EOF,
103  HBBTV_RECPLAYER_ERROR
104 } E_HBBTV_RECPLAYER_STATE;
105 
106 typedef enum
107 {
108  HBBTV_RECORDING_NEWLY_SCHEDULED,
109  HBBTV_RECORDING_ABOUT_TO_START,
110  HBBTV_RECORDING_ACQUIRING_RESOURCES,
111  HBBTV_RECORDING_STARTED,
112  HBBTV_RECORDING_UPDATED,
113  HBBTV_RECORDING_COMPLETED,
114  HBBTV_RECORDING_PART_COMPLETED,
115  HBBTV_RECORDING_FAILED_RESOURCE_LIMITATION,
116  HBBTV_RECORDING_FAILED_INSUFFICIENT_STORAGE,
117  HBBTV_RECORDING_FAILED_TUNER_CONFLICT,
118  HBBTV_RECORDING_FAILED_NOT_ALLOWED,
119  HBBTV_RECORDING_FAILED_UNKNOWN_ERROR,
120  HBBTV_RECORDING_DELETED,
121  HBBTV_RECORDING_TS_STARTING, /* Timeshift related events */
122  HBBTV_RECORDING_TS_STARTED,
123  HBBTV_RECORDING_TS_STOPPED,
124  HBBTV_RECORDING_TS_NOT_POSSIBLE,
125  HBBTV_RECORDING_TS_NOT_ALLOWED,
126  HBBTV_RECORDING_TS_FAILED
127 } E_HBBTV_RECORDING_EVENT;
128 
129 typedef enum
130 {
131  HBBTV_STRING_FORMAT_SI,
132  HBBTV_STRING_FORMAT_HBBTV
133 } E_HBBTV_STRING_FORMAT;
134 
138 typedef enum
139 {
140  HBBTV_DRM_NO_LICENSE,
141  HBBTV_DRM_INVALID_LICENSE,
142  HBBTV_DRM_VALID_LICENSE
144 
145 /*---Global type defs for public use-------------------------------------------*/
146 typedef struct
147 {
148  U32BIT org_id;
149  U16BIT app_id;
150  U8BIT *name;
152 
153 typedef void (*F_HBBTV_DRM_SEND)(U8BIT *message, U32BIT length, U32BIT id, void *user_data);
154 
162 typedef void (*F_HBBTV_DSMCC_FILE_CALLBACK)(void* user_data, U32BIT err, U8BIT* data, U32BIT size);
163 
164 
165 /*---Global Function prototypes for public use---------------------------------*/
175 E_HBBTV_ERR HBBTV_Initialise(U32BIT task_priority, E_HBBTV_STRING_FORMAT string_format,
176  U8BIT options);
177 
181 void HBBTV_Finalise(void);
182 
188 void HBBTV_Start(S_HBBTV_DVB_LOCATOR *p_dvb_locator);
189 
193 void HBBTV_Stop(void);
194 
200 E_HBBTV_ERR HBBTV_HbbTvSetUrl(const U8BIT *url);
201 
209 E_HBBTV_ERR HBBTV_GetBroadcastAppList(S_HBBTV_BROADCAST_APP **apps, U32BIT *total);
210 
216 
223 E_HBBTV_ERR HBBTV_LaunchApplication(U32BIT org_id, U16BIT app_id);
224 
232 E_HBBTV_ERR HBBTV_NotifyKeyPress(E_HBBTV_KEY key);
233 
249 E_HBBTV_ERR HBBTV_ProcessAitSection(U16BIT service_id, U8BIT *data, U32BIT nbytes);
250 
256 E_HBBTV_ERR HBBTV_NotifyServiceListChange(void);
257 
264 E_HBBTV_ERR HBBTV_NotifyParentalRatingChange(BOOLEAN blocked);
265 
275 E_HBBTV_ERR HBBTV_NotifyChannelChangeStatus(U16BIT onet_id, U16BIT trans_id, U16BIT serv_id,
276  E_HBBTV_CHANNEL_CHANGE_STATUS status);
277 
283 E_HBBTV_ERR HBBTV_NotifyProgrammeChanged(void);
284 
292 E_HBBTV_ERR HBBTV_NotifyVideoAspectRatio(E_HBBTV_ASPECT_RATIO ratio);
293 
299 void HBBTV_MPNotifyState(void *ihdl, E_HBBTV_MP_STATE state);
300 
307 E_HBBTV_ERR HBBTV_NotifyRecordingEvent(U32BIT id, E_HBBTV_RECORDING_EVENT event);
308 
315 E_HBBTV_ERR HBBTV_NotifyRecordingPlayerState(void *ihdl, E_HBBTV_RECPLAYER_STATE state);
316 
329 E_HBBTV_ERR HBBTV_DRMRegister(U16BIT ca_system_id, F_HBBTV_DRM_SEND send_function, void *user_data);
330 
337 void HBBTV_DRMUnregister(U16BIT ca_system_id);
338 
349 E_HBBTV_ERR HBBTV_NotifyDRMMessageResult(U32BIT id, U8BIT *message, U32BIT length, U8BIT result_code);
350 
360 E_HBBTV_ERR HBBTV_NotifyDRMSystemMessage(U8BIT *message, U32BIT length, U16BIT ca_system_id);
361 
371 E_HBBTV_ERR HBBTV_NotifyDRMRightsError(E_HBBTV_DRM_ERROR_STATE error_state, U16BIT ca_system_id,
372  U8BIT *rights_issuer_url, U32BIT rights_issuer_length);
373 
379 E_HBBTV_ERR HBBTV_NotifyLowMemory(void);
380 
404 void HBBTV_DBGSetMask(U32BIT debug_mask);
405 
412 E_HBBTV_ERR HBBTV_SetSystemInfo(S_HBBTV_SYSTEM_INFO *info);
413 
419 
426 void HBBTV_DsmccRequestFile(void *user_data, U8BIT* url);
427 
428 #endif /* _HBBTV_H */
Definition: hbbtv_types.h:159
E_HBBTV_KEY
Key codes.
Definition: hbbtv_types.h:87
Definition: hbbtv_types.h:189
void HBBTV_DBGSetMask(U32BIT debug_mask)
Sets the debug mask.
Definition: debug.c:54
E_HBBTV_DRM_ERROR_STATE
OIPF Vol.5, section 7.13.6.
Definition: hbbtv.h:138
Definition of general purpose types.
E_HBBTV_ERR HBBTV_NotifyDRMRightsError(E_HBBTV_DRM_ERROR_STATE error_state, U16BIT ca_system_id, U8BIT *rights_issuer_url, U32BIT rights_issuer_length)
Notifies an incoming rights error from the DRM system.
Definition: hbbtv_control.c:830
void HBBTV_DRMUnregister(U16BIT ca_system_id)
Unregisters a DRM system with the HbbTV engine. Unegistering a new DRM system will also change the ca...
Definition: oipf_drm_agent.c:232
E_HBBTV_ERR HBBTV_NotifyChannelChangeStatus(U16BIT onet_id, U16BIT trans_id, U16BIT serv_id, E_HBBTV_CHANNEL_CHANGE_STATUS status)
Notifies the HbbTV engine of a change in the status of the service identified by the specified DVB tr...
Definition: hbbtv_control.c:493
void HBBTV_DsmccRequestFile(void *user_data, U8BIT *url)
Request file from DSMCC (with &#39;dvb:&#39; origin). The result is returned via function given to HBBTV_Dsmc...
Definition: dsmclient.c:417
void HBBTV_ReleaseAppList(S_HBBTV_BROADCAST_APP *apps)
Releases the list of applications allocated by HBBTV_GetBroadcastAppList.
Definition: hbbtv_control.c:417
E_HBBTV_ERR HBBTV_NotifyDRMSystemMessage(U8BIT *message, U32BIT length, U16BIT ca_system_id)
Notifies an incoming message from the DRM system. The HbbTV engine copies the content of message befo...
Definition: hbbtv_control.c:746
Definition: hbbtv.h:146
E_HBBTV_ERR HBBTV_DRMRegister(U16BIT ca_system_id, F_HBBTV_DRM_SEND send_function, void *user_data)
Registers a DRM system with the HbbTV engine. Registering a new DRM system will also change the capab...
Definition: oipf_drm_agent.c:191
E_HBBTV_ERR HBBTV_LaunchApplication(U32BIT org_id, U16BIT app_id)
Launches the specified application.
Definition: hbbtv_control.c:429
void HBBTV_Finalise(void)
Finalises the HBBTV module.
Definition: hbbtv_control.c:191
E_HBBTV_ERR HBBTV_NotifyParentalRatingChange(BOOLEAN blocked)
Notifies the HbbTV engine that the parental rating of the currently playing service has changed...
Definition: hbbtv_control.c:468
E_HBBTV_ERR HBBTV_NotifyKeyPress(E_HBBTV_KEY key)
Notifies the HbbTV engine of a user key press. If the key is not required by an active HbbTV applicat...
Definition: hbbtv_control.c:580
void HBBTV_Start(S_HBBTV_DVB_LOCATOR *p_dvb_locator)
Allows the HbbTV engine to run on the specified channel and handle the applications lifecyle as speci...
Definition: hbbtv_control.c:205
E_HBBTV_ERR HBBTV_HbbTvSetUrl(const U8BIT *url)
Launches a "Broadcast-INDEPENDENT" application. The url could be an XML-AIT file. ...
Definition: hbbtv_control.c:330
E_HBBTV_ERR HBBTV_ProcessAitSection(U16BIT service_id, U8BIT *data, U32BIT nbytes)
Requests the HbbTV engine to process the specified AIT. The HbbTV engine expects the relevant AITs on...
Definition: ait.c:903
E_HBBTV_ERR HBBTV_NotifyDRMMessageResult(U32BIT id, U8BIT *message, U32BIT length, U8BIT result_code)
Notifies the result message from the DRM system.The HbbTV engine copies the content of message before...
Definition: hbbtv_control.c:788
void HBBTV_MPNotifyState(void *ihdl, E_HBBTV_MP_STATE state)
Notifies the HbbTV engine that the media player state has changed.
Definition: av_control.c:1284
void HBBTV_DsmccSetCallback(F_HBBTV_DSMCC_FILE_CALLBACK func)
Provide function to return result of file requests.
Definition: dsmclient.c:403
E_HBBTV_ERR HBBTV_NotifyServiceListChange(void)
Notifies the HbbTV ending that it must update Service list. This will cause the engine to subsequentl...
Definition: hbbtv_control.c:447
E_HBBTV_ERR HBBTV_NotifyRecordingPlayerState(void *ihdl, E_HBBTV_RECPLAYER_STATE state)
Notifies the HbbTV engine that the media player state has changed.
Definition: av_control.c:1433
System Wide Global Technical Data Type Definitions.
E_HBBTV_ERR HBBTV_NotifyRecordingEvent(U32BIT id, E_HBBTV_RECORDING_EVENT event)
Notifies the HbbTV engine of a recording event.
Definition: hbbtv_control.c:539
E_HBBTV_ERR HBBTV_NotifyVideoAspectRatio(E_HBBTV_ASPECT_RATIO ratio)
Notifies the HBBTV module of the aspect ratio of the video stream. This is used by the engine to corr...
Definition: hbbtv_control.c:643
E_HBBTV_ERR HBBTV_GetBroadcastAppList(S_HBBTV_BROADCAST_APP **apps, U32BIT *total)
Returns a list of HbbTv Broadcast Appications signalled in the current AIT. The list must be freed us...
Definition: hbbtv_control.c:373
E_HBBTV_ERR HBBTV_NotifyProgrammeChanged(void)
Notifies the HbbTV engine that the present/following events have changed on the current service...
Definition: hbbtv_control.c:518
E_HBBTV_ERR HBBTV_Initialise(U32BIT task_priority, E_HBBTV_STRING_FORMAT string_format, U8BIT options)
Initialises the HBBTV module.
Definition: hbbtv_control.c:85
void HBBTV_Stop(void)
Stops the HbbTV engine and prevents any HbbTV application to be displayed.
Definition: hbbtv_control.c:232
E_HBBTV_ERR HBBTV_NotifyLowMemory(void)
Notifies the HbbTv engine that the device is running low on available memory for running applications...
Definition: hbbtv_control.c:894
void(* F_HBBTV_DSMCC_FILE_CALLBACK)(void *user_data, U32BIT err, U8BIT *data, U32BIT size)
Callback function to provide result of file request (using HBBTV_DsmccRequestFile) ...
Definition: hbbtv.h:162
E_HBBTV_ERR HBBTV_SetSystemInfo(S_HBBTV_SYSTEM_INFO *info)
Informs the HbbTV engine of some information regarding the system. The HbbTV engine makes a copy of t...
Definition: hbbtv_control.c:671