UTS6710/aps/application/app_frmwrk/dvb/include/al_teletext.h

/**
* Copyright(c) 2011 Sunmedia Technologies - All Rights Reserved.
*
* @file
*
* @brief this file defines teletext interface for app layer.
*
* The file supports the teletext functions by used for app layer, and the datas related
* teletext functions are "EBU teletext" datas.  "EBU teletext" datas includes teletext
* subtitles, since these are carried on a particular teletext magazine/page. So the
* function in the file includes teletext subtitle function.
*
*/

#ifndef __AL_TELETEXT_H__
#define __AL_TELETEXT_H__

#include "al_basictypes.h"
//#include "region.h"

#ifdef __cplusplus
	extern "C"{
#endif

//#ifdef CONFIG_SUPPORT_TTX
/**
* @brief define teletext descriptor language code size.
*/
#define LANG_CODE_SIZE (3)

/**
* @brief structure definition for teletext descriptor information.
*
* After one teletext descriptor from the PMT is parsed, the information
* will be stored to teletext descriptor buffer with the structure. \n
* The parsing descriptor information includes the information:
* @li Pid: specify the pid of the transport stream packets which carry the
* associated program element.
* @li Language: contain charater language code of language of teletext.
* @li Type: contain the teletext type.
* @li MagazineNum: contain the teletext magazine number.
* @li PageNum: contain the teletext page number.
*/
typedef struct _AL_TTX_Desc_t
{
	al_int id; /**< teletext id by used when play recorded file*/
	al_uint16 Pid; /**< teletext pid */
	al_uint8 Language[LANG_CODE_SIZE]; /**< teletext language */
	al_uint8 Type; /**< teletext type */
	al_uint8 MagazineNum; /**< teletext magazine number */
	al_uint8 PageNum; /**< teletext page number */
}AL_TTX_Desc_Info_t;

/**
* @brief type definition for the teletext page.
*
* @li PageNum: teletext page number.
* @li SubPageNum: teletext subpage number.
*/
typedef struct _AL_TTX_Page_t
{
    al_uint16 PageNum;
    al_uint16 SubPageNum;
}AL_TTX_Page_t;

/**
* @brief type definition for the teletext page.
*
* When starting to display teletext on the screen, it needs select the displayed
* teletext page type with spec.
*/
typedef enum
{
	AL_TTX_PAGE_TYPE_CURRENT_PAGE = 0, /**< current page type that is the last displayed page */
	AL_TTX_PAGE_TYPE_INITIAL_PAGE, /**< initial page type */
	AL_TTX_PAGE_TYPE_SUTITLE_PAGE, /**< subtitle page type */
	AL_TTX_PAGE_TYPE_MAX /**< invalid page type */
}AL_TTX_Page_Type_t;

/**
* @brief type definition for the teletext descriptor.
*
*/
typedef enum
{
	AL_TTX_DESC_TYPE = 0,		/**< teletext descriptor type */
	AL_TTX_SUB_DESC_TYPE,		/**< teletext subtitle descriptor type */
	AL_TTX_DESC_MAX			/**< invalid descriptor type */
}AL_TTX_Desc_Type_t;

/**
* @brief area language definition for analogue teletext.
*
* If the user can set the analogue teletext language on the mainmenu,
* the set teletext language will be stored to EEPROM or FLASH.
* If analogue teletext needs be displayed on the screen, the stored
* teletext language will be set to teletext decoder module. The teletext
* decoder thread starts to parse data with the set teletext language,
* otherwise parse data with the initial teletext language.
*/
typedef enum
{
    AL_TTX_LANG_WEST_EUROPEAN = 0,/**< west european language */
	AL_TTX_LANG_GREEK, /**< greek language */
	AL_TTX_LANG_EAST_EUROPEAN, /**< east european language */
	AL_TTX_LANG_ARABIC, /**< arabic language */
	AL_TTX_LANG_CYRILLIC, /**< cyrillic language */
	AL_TTX_LANG_RUSSIAN, /**< russian language */
	AL_TTX_LANG_HEBREW, /**< hebrew language */
	AL_TTX_LANG_FARSI, /**< farsi language */
    AL_TTX_LANG_CENTRAL_EUROPEAN, /**< central language */
    AL_TTX_LANG_WEST_EUROPEAN_TURKISH, /**< west european turkish language */
    AL_TTX_LANG_RUSSIA2,
    AL_TTX_LANG_BYELORUSSIAN,
    AL_TTX_LANG_THAI,
    AL_TTX_LANG_MAX /**< invalid language */
}AL_TTX_LANG_t;

/**
* @brief type definition for search page direction.
*
* When pressing the key to search page, it needs direct the search mode.
* Then the subtitle datas from subtitle buffer are gotten with the search
* mode.\n
* For example, when the teletext is displaying on the screen and the search
* mode is "AL_TT_DIRECTION_UP", if the user presses subtitle key, the
* display mode will be changed to subtitle display mode and the subtitle
* datas will be gotten by searching minimal to maximum subtitle page.
*/
typedef enum
{
	AL_TTX_DIRECTION_DOWN = 0, /**< down direction */
	AL_TTX_DIRECTION_UP, /**< up direction */
	AL_TTX_DIRECTION_DISP, /**< display  specific page*/
	AL_TTX_DIRECTION_MAX /**< invalid direction */
}AL_TTX_Search_Direction_t;

/**
* @brief type definition for teletext source.
*
* At present, the condition that gets the analog teletext data and the digital
* teletext data is different. When teletext function starting, the different
* settings are requested with different teletext sources. \n
* For example: if the source type is analog source type, the interrupt
* needs be enable.
*/
typedef enum
{
	AL_TTX_SOURCE_TYPE_DIGITAL = 0, /**< digital source type */
	AL_TTX_SOURCE_TYPE_ANALOG, /**< analog source type */
	AL_TTX_SOURCE_TYPE_MEDIA,  /**< media source type */
	AL_TTX_SOURCE_TYPE_MAX /**< invalid source type */
} AL_TTX_Source_Type_t;

/**
* @brief function definition for teletext key.
*
* When the user presses the keys of teletext, api layer will set the
* involved function to decoder layer, and the teletext decoder thread
* will start to parse data with the function.
*/
typedef enum
{
	AL_TTX_FUN_TEXT_ON_MODE = 0, /**< teletext on mode */
	AL_TTX_FUN_TEXT_OFF_MODE, /**< teletext off mode */
	AL_TTX_FUN_MIX_ON_MODE, /**< teletext mix on mode */
	AL_TTX_FUN_MIX_OFF_MODE, /**< teletext mix off mode */
	AL_TTX_FUN_REVEAL_ON_MODE, /**< teletext reveal on mode */
	AL_TTX_FUN_REVEAL_OFF_MODE, /**< teletext reveal off mode */
	AL_TTX_FUN_SUBTITLE_ON_MODE, /**< teletext subtitle on mode */
	AL_TTX_FUN_SUBTITLE_OFF_MODE, /**< teletext subtitle off mode */
	AL_TTX_FUN_SIZE_UP, /**< teletext top size  mode */
	AL_TTX_FUN_SIZE_DOWN, /**< teletext bottom size mode */
	AL_TTX_FUN_SIZE_LEFT, /**< teletext TAP mode */
	AL_TTX_FUN_SIZE_RIGHT, /**< teletext PAT mode */
	AL_TTX_FUN_SIZE_RIGHT_UP, /**< teletext PAT and top size mode */
	AL_TTX_FUN_SIZE_RIGHT_DOWN, /**< teletext PAT and bottom size mode */
	AL_TTX_FUN_SIZE_NORMAL, /**< teletext normal mode */
	AL_TTX_FUN_HOLD_ON, /**< teletext hold on mode */
	AL_TTX_FUN_HOLD_OFF, /**< teletext hold off mode */
	AL_TTX_FUN_CONCEAL_ON, /**< teletext conceal on mode */
	AL_TTX_FUN_CONCEAL_OFF, /**< teletext conceal off mode */
	AL_TTX_FUN_SUBTITLE_CONCEAL_ON, /**< teletext subtitle conceal on mode */
	AL_TTX_FUN_SUBTITLE_CONCEAL_OFF, /**< teletext subtitle conceal off mode */
	AL_TTX_FUN_RED, /**< teletext red key being operated mode */
	AL_TTX_FUN_GREEN, /**< teletext green key being operated mode */
	AL_TTX_FUN_YELLOW, /**< teletext yellow key being operated mode */
	AL_TTX_FUN_BLUE, /**< teletext blue key being operated mode */
	AL_TTX_FUN_INDEX, /**< teletext index mode */
	AL_TTX_FUN_SUBCODE_MENU_ON, /**< teletext subcode menu on mode */
	AL_TTX_FUN_SUBCODE_MENU_OFF, /**< teletext subcode menu off mode */
	AL_TTX_FUN_PAGE_UP, /**< teletext page up mode */
	AL_TTX_FUN_PAGE_DOWN, /**< teletext page down mode */
	AL_TTX_FUN_SUBCODE_PAGE_UP, /**< teletext subpage up mode */
	AL_TTX_FUN_SUBCODE_PAGE_DOWN, /**< teletext subpage down mode */
	AL_TTX_FUN_LIKE_PAGE_ON, /**< teletext like page on mode */
	AL_TTX_FUN_LIKE_PAGE_OFF, /**< teletext like page off mode */
	AL_TTX_FUN_TOP_ON_MODE, /**< teletext TOP on mode */
	AL_TTX_FUN_TOP_OFF_MODE,/**< teletext TOP off mode */
	AL_TTX_FUN_MAX /**< invalid function */
}AL_TTX_FUNC_t;

/**
* @brief select the teletext data type for gotten the teletext data.
*/
typedef enum
{
	AL_TTX_DEMUX_CHAN = 0, /**< data comes from demux channel for TS */
	AL_TTX_PE_CHAN, /**< data comes from PE channel for recorded TS */
	AL_TTX_MAX /**<invalid data source */
}AL_TTX_Data_Source_t;

/**
* @brief teletext start function.
*
* The function will create teletext decoder thread, and init slicer
* param. If the teletext type is analogue teletext, the interrupt function will be enable.
* The channel of teletext will be opened with teletext pid  and the parsing task will start
* to decode teletext page.
*
* @param SourceTyped teletext source type.
*
* @param DigitialLang digitial TTX language gotten from eeprom/flash if user setting
* on the main menu.
*
* @param TTXLang teletext language type.
*
* @return AL_SUCCESS if starting is successful, AL_FAILURE
* otherwise.
*/
AL_Return_t AL_TTX_Start(AL_TTX_Source_Type_t SourceType, al_uint8 *TTXLanguage);

/**
* @brief teletext stop function.
*
* The function will suspend teletext decoder thread, reset slicer
* function. If the teletext type is analogue teletext, the interrupt
* function will be disable.
*
* @param al_void.
*
* @return AL_SUCCESS if stopping is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_Stop(al_void);

/**
* @brief the function will reset teletext module, following initialization
* or a programe change.
*
* @param void.
*
* @return AL_SUCCESS if reseting is successful, AL_FAILURE
* therwise.
*/
AL_Return_t AL_TTX_Reset(al_void);

/**
* @brief the function will get teletext subtitle being exist or not.
*
* @param al_void.
*
* @return AL_SUCCESS if teletext subtitle is exist , AL_FAILURE
* otherwise.
*/
AL_Return_t AL_TTX_SubtitleExistStatus(al_void);

/**
* @brief the function will set key functions.
*
* If the user presses keys of teletext, the function wil be used for setting
* key function to middleware layer.
*
* @param KeyFun the functions can be set by the user pressing key.
*
* @return AL_SUCCESS if setting key function is successful, AL_FAILURE
* otherwise.
*/
AL_Return_t AL_TTX_SetKeyFunc(AL_TTX_FUNC_t KeyFun);

/**
* @brief search subtitle page function.
*
* When starting to display subtitle on the screen with pressing subtitle key,
* it needs direct the search mode.
* For example: when the teletext is displaying on the screen and the search
* mode is "AL_TT_DIRECTION_UP", if the user presses subtitle key, the
* display mode will be changed to subtitle mode and the subtitle data
* will be gotten by searching minimal to maximum subtitle page.
*
* @param Direct the search mode.
* @param *DisplayPage 
* when mode is AL_TTX_DIRECTION_DISP, DisplayPage is page number by user.
* otherwise gotten current display teletext subtitle page number.
*
* @return AL_SUCCESS if searching subtitle page is successful, AL_FAILURE
* otherwise.
*/
AL_Return_t AL_TTX_SearchSubtitlePage(AL_TTX_Search_Direction_t Direct, AL_TTX_Page_t *DisplayPage);

/**
* @brief set digital entry function.
*
* If the user presses the "0-9" keys while teletext is displaying on the screen,
* displayed teletext page number will be changed to the number by user setting.
*
* @param DigitalEntry the "0-9" keys.
*
* @return AL_SUCCESS if setting digital entry is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_SetDigitalEntry(al_uint8 DigitalEntry);

/**
* @brief set analog teletext language function.
*
* If the user can set analogue teletext language on the mainmenu, the set
* teletext language will be stored to EEPROM or FLASH. If analogue teletext
* needs be displayed on the screen, the stored analogue teletext language will
* be set to teletext decoder module. The teletext decoder thread
* starts to parse data with the set analogue teletext language, otherwise parse
* data with the initial analogue teletext language.
*
* @param TeletextLang set analog teletext language.
*
* @return AL_SUCCESS if setting language is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_SetLanguage(AL_TTX_LANG_t TeletextLang);

/**
* @brief the function will get teletext data being valid or not.
*
* Before teletext parsing, teletext needs be preparsing. If gotten datas
* are some errors, the datas with preparsing don't be stored
* to cache buffer, and the teletext function of sysapp layer don't work.
*
* @param *Status gotten the signal status value. if the preparsing is
* successful, the gotten signal status is al_true, else if the preparsing
* is false, the gotten signal status is al_false.
*
* @return AL_SUCCESS if gotten signal is successful, AL_FAILURE
* therwise.
*/
AL_Return_t AL_TTX_GetSignalStatus(al_bool *Status);

/**
* @brief the function can get the parsed teletext descriptor information.
*
* After creating subtitle menu with pressing subtitle key, the subtitle menu
* with all subtitle types is shown on the screen. So when displayed information
* is inited, the parsed teletext subtitle descriptor information will be gotten.
*
* @param TTXDescType teletext descriptor type.
*
* @param Index using the index can get special teletext subtitle descriptor information
* from the buffer.
*
* @param *TeletextDescInfo it will store the gotten teletext subtitle descriptor
* information.
*
* @return AL_SUCCESS if getting teletext subtitle descriptor information is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_GetDescInfo(AL_TTX_Desc_Type_t TTXDescType, al_int Index, AL_TTX_Desc_Info_t *TTXDescInfo);

/**
* @brief the function can get file ts teletext information from pe module
*
* when play recorded file, if need to display teletext on the screen, the file ts
* teletext information need to be gotten from pe module.
*
* @param al_void.
*
* @return AL_SUCCESS if getting file ts teletext information is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_GetFileTsTTXInfo(al_void);

/**
* @brief the function can get the valid teletext or teletext subtitle descriptor total number.
*
* Before the teletext subtitle module starts to work, it needs get the subtitle descpritor
* total number. If the total number is more than 0, the subtitle module will start
* to work, otherwise stop to work.
*
* @param TTXDescType teletext descriptor type.
*
* @param *GetTotalNum get the teletext or teletext subtitle descriptor total number.
*
* @return AL_SUCCESS if getting total number is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_GetTotalNum(AL_TTX_Desc_Type_t TTXDescType, al_uint32 *GetTotalNum);

/**
* @brief get TTX time data
*
* @param buff: data buffer
*
* @param buff_size: buffer size
*
* @return AL_SUCCESS if getting time string is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AI_TTX_GetTimeData(al_uint8 *buff, al_uint8 buff_size);

/**
* @brief refresh page
*
* @param al_void.
*
* @return AL_SUCCESS if refresh page successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_TTX_RefreshPage(al_void);

//#endif

#ifdef __cplusplus
}
#endif
#endif