glue_main.c

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2011 Ocean Blue Software Ltd
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 *
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
/*---includes for this file--------------------------------------------------*/
#include "stb_os.h"
#include "glue_memory.h"
#include "glue_debug.h"
#include "glue_queue.h"
#include "glue_timers.h"
#include "glue_main.h"
#include "mheg5_control.h"
#include "dvb_service.h"
#if defined(INCLUDE_IC)
#include "http_interface.h"
#endif
#ifdef INCLUDE_IC
#include "dvb_ics.h"
#endif
#ifndef CI_PLUS_ONLY
#include "glue_dsmcc.h"
#endif
#include "mh5control.h"
#include "mh5support.h"
#include "glue_events.h"
#ifdef INCLUDE_ICS
#include "mh5streamer.h"
#endif
#include "mg_osd.h"

/*---constant definitions for this file--------------------------------------*/

#define MAIN_STACK_SIZE    0x2000

#define PRG_DONE_NONE      0
#define PRG_DONE_INIT      1
#define PRG_DONE_GRAPHICS  2
#define PRG_DONE_MEMORY    3
#define PRG_DONE_SYNCS     4
#define PRG_DONE_QUEUE     5
#define PRG_DONE_DSMCC     6
#define PRG_DONE_MAIN      7
#define PRG_DONE_TIMERS    8
#define PRG_DONE_HTTP      9
#define PRG_DONE_MHEG5     10

/* Mheg has three post process funcs:
 * 1) fileorm, 2) streamevent, 3) streamer,
 * Very unlikely to need more than that
 */
#define MAX_PP_FUNCS 4


/*---local typedef structs for this file-------------------------------------*/

typedef struct s_pp_list
{
   F_PostProcess pp_func;
} S_PP_LIST;

typedef enum
{
   VS_STOPPED,
   VS_TUNING,
   VS_RUNNING,
   VS_REBOOT
} E_ApiStatus;


/* Default service 'rec://svc/def' storage variable */
static S_DVB_LOCATOR default_service = { 0, 0, 0 };

static S32BIT default_service_index = 0;

/*---local (static) variable declarations for this file----------------------*/

static void *task_handle;
/* Semaphore used to synchronise Stop/Quit/Reset functions */
static void *stop_sema = 0;
/* Semaphore used to synchronise Pause function */
static void *pause_sema = 0;
/* Mutex to protect against multiple threads accessing API functions */
static void *api_mutex = 0;

static BOOLEAN active_state = TRUE;
static E_ApiStatus running_state = VS_STOPPED;
static E_ApiStatus started_state = VS_STOPPED;
static BOOLEAN restore_active = FALSE;

static F_MainProcess main_proc_func;
static S_PP_LIST post_processes[MAX_PP_FUNCS];
static BOOLEAN ciplus_request_ndt = FALSE;

/*---local function definitions----------------------------------------------*/

/*---global function definitions---------------------------------------------*/
static void stopEngine(MHEG5StopEventParams_t *params);


static void DummyMainFunc(void)
{
}

static BOOLEAN DummyPostFunc(void)
{
   return FALSE;
}

static void MHEG5Main(void *pArgs)
{
   S_MhegMessage event_msg;
   int i;
   FUNCTION_START(x)
   while (1)
   {
      if (VQ_GetMsg( &event_msg ) != MHERR_OK)
      {
         STB_OSTaskDelay(10);
      }
      else if (event_msg.proc_msg_func == NULL)
      {
         /* received Quit msg */
         VQ_Close();
         break;
      }
      else
      {
         event_msg.proc_msg_func( &(event_msg.data));

         for (i = 0; i != MAX_PP_FUNCS; i++)
         {
            if (post_processes[i].pp_func != DummyPostFunc)
            {
               do
               {
                  main_proc_func();
               }
               while (post_processes[i].pp_func());
               post_processes[i].pp_func = DummyPostFunc;
            }
         }
         main_proc_func();
      }
   }
   TRACE(TERROR, (" **** EXIT **** %d ", running_state));
   if (running_state == VS_RUNNING)
   {
      event_msg.data.stop.action = STOP_ACTION_CLEAR_DSMCC;
      stopEngine( &event_msg.data.stop );
   }
   else
   {
      STB_OSSemaphoreSignal(stop_sema);
   }
   FUNCTION_FINISH(x)
}

static E_MhegErr CreateSyncs(void)
{
   BOOLEAN result = MHERR_OK;
   FUNCTION_START(x)
   api_mutex = STB_OSCreateMutex();
   if (api_mutex == NULL)
   {
      result = MHERR_SYSTEM_RESOURCE_MUTEX;
   }
   else
   {
      stop_sema = STB_OSCreateSemaphore();
      if (stop_sema == NULL)
      {
         result = MHERR_SYSTEM_RESOURCE_SEMAPHORE;
      }
      else
      {
         pause_sema = STB_OSCreateSemaphore();
         if (pause_sema == NULL)
         {
            result = MHERR_SYSTEM_RESOURCE_SEMAPHORE;
         }
         else
         {
            /* Initial value for semaphore is 1, so do wait to decrement value to 0 */
            STB_OSSemaphoreWait(pause_sema);
            STB_OSSemaphoreWait(stop_sema);
         }
      }
   }
   FUNCTION_FINISH(x)
   return result;
}

static void DestroySyncs(void)
{
   FUNCTION_START(x)
   if (pause_sema != 0)
   {
      STB_OSDeleteSemaphore(pause_sema);
      pause_sema = 0;
   }
   if (stop_sema != 0)
   {
      STB_OSDeleteSemaphore(stop_sema);
      stop_sema = 0;
   }
   if (api_mutex != 0)
   {
      STB_OSDeleteMutex(api_mutex);
      api_mutex = 0;
   }
   FUNCTION_FINISH(x)
}

/* Called by External tasks*/
BOOLEAN MH5GlueIsStarted(void)
{
   BOOLEAN result;
   STB_OSMutexLock( api_mutex );
   result = (started_state == VS_RUNNING) ? TRUE : FALSE;
   STB_OSMutexUnlock( api_mutex );
   return result;
}

void MH5GlueDoneRebootMessage(void)
{
   STB_OSMutexLock( api_mutex );
   if (started_state == VS_REBOOT)
   {
      /* as far as external API is concerned, 'running' is the current state */
      started_state = VS_RUNNING;
   }
   STB_OSMutexUnlock( api_mutex );
}

void MH5GlueSetMainPostFunc( F_MainProcess func )
{
   FUNCTION_START(x)
   if (func == NULL)
   {
      main_proc_func = DummyMainFunc;
   }
   else
   {
      main_proc_func = func;
   }
   FUNCTION_FINISH(x)
}

void MH5GlueAddPostProcessFunc( F_PostProcess func )
{
   int i;
   FUNCTION_START(x)
   for (i = 0; i != MAX_PP_FUNCS; i++)
   {
      if (post_processes[i].pp_func == func)
         break;
   }
   if (i == MAX_PP_FUNCS)
   {
      for (i = 1; i != MAX_PP_FUNCS; i++)
      {
         if (post_processes[i].pp_func == DummyPostFunc)
         {
            post_processes[i].pp_func = func;
            break;
         }
      }
   }
   FUNCTION_FINISH(x)
}

static void ResetPostFuncs( void )
{
   int i;
   FUNCTION_START(x)
   for (i = 0; i != MAX_PP_FUNCS; i++)
   {
      post_processes[i].pp_func = DummyPostFunc;
   }
   FUNCTION_FINISH(x)
}

static E_MhegErr MHEG5Exit( void )
{
   E_MhegErr result;
   S_MhegMessage msg;

   FUNCTION_START(x)
   ResetPostFuncs();
   MH5GlueSetMainPostFunc(NULL);
   TRACE(TSTATE, ("************** EXIT! *************"));
   /* Post event to cause main task to quit */
   msg.proc_msg_func = NULL;
   msg.data_type = DT_NONE;
   ResetPostFuncs();
   result = VQ_PutMsg(&msg, PRTY_CRITICAL);
   if (result == MHERR_OK)
   {
      /* Wait for the close event to be processed */
      STB_OSSemaphoreWait( stop_sema );
      STB_OSTaskDelay(10);
      STB_OSDestroyTask(task_handle);
      task_handle = NULL;
   }
   FUNCTION_FINISH(x)
   return result;
}

E_MhegErr MHEG5_Open( S_MhegConfig *pSetup )
{
   E_MhegErr result;
   U32BIT progress = PRG_DONE_NONE;

   FUNCTION_START(MHEG5_Open)

   TRACE(TSTATE,(""))

#ifdef TRACING
   trace_set_time();
#endif

   if (pSetup == NULL)
   {
      DPL1(("ERROR: Open - Setup NULL\n"));
      result = MHERR_BAD_PARAMETER;
   }
   else if (strcmp(pSetup->version_string, MHEG5VersionString()))
   {
      DPL1(("ERROR: Open - Version Mismatch: \"%s\" == \"%s\"?\n",pSetup->version_string, MHEG5VersionString()));
      result = MHERR_VERSION_MISMATCH;
   }
   else if (task_handle)
   {
      result = MHERR_COMP_ALREADY_OPEN;
   }
   else if (pSetup->taskPriority < MHEG5_MIN_TASK_PRIORITY)
   {
      DPL1(("Is taskPriority      0x%x >= 0x%x ?\n", pSetup->taskPriority, MHEG5_MIN_TASK_PRIORITY));
      result = MHERR_BAD_TASK_PRIORITY;
   }
   else
   {
      TRACE(TSTATE,(""))

      // Initialise static data for this file
      main_proc_func = DummyMainFunc;
      ResetPostFuncs();

      result = MH5_SupportInitialise( pSetup );
      if (result == MHERR_OK)
      {
         TRACE(TSTATE,(""))
         progress = PRG_DONE_INIT;

         result = MG_Initialise( pSetup->screenWidth,
               pSetup->screenHeight,
               pSetup->colourDepth );
      }
      if (result == MHERR_OK)
      {
         TRACE(TSTATE,(""))
         progress = PRG_DONE_GRAPHICS;

         if (!MH5GlueMemoryInitialise())
         {
            result = MHERR_ALLOCATING_MEMORY_REGION;
         }
         else
         {
            progress = PRG_DONE_MEMORY;
            result = CreateSyncs();
            if (result == MHERR_OK)
            {
               progress = PRG_DONE_SYNCS;
               result = VQ_Open( pSetup );
               if (result == MHERR_OK)
               {
                  progress = PRG_DONE_QUEUE;
               #ifndef CI_PLUS_ONLY
                  result = MH5GlueDsmccOpen( pSetup->taskPriority );
               #endif  /* !CI_PLUS_ONLY */
               }
            }
         }
      }
      if (result == MHERR_OK)
      {
         TRACE(TSTATE,(""))
         progress = PRG_DONE_DSMCC;
         active_state = TRUE;
         task_handle = STB_OSCreateTask( MHEG5Main, NULL, MAIN_STACK_SIZE,
               (U8BIT)pSetup->taskPriority, (U8BIT *)"MH5GlueMain");
         if (task_handle == NULL)
         {
            TRACE(TERROR, ("Failed To Create Task"));
            result = MHERR_SYSTEM_RESOURCE_TASK;
         }
         else
         {
            progress = PRG_DONE_MAIN;
            /* timer task is +2 higher priority */
            result = VT_TimersInit( pSetup->taskPriority + 2 );
            if (result == MHERR_OK)
            {
               progress = PRG_DONE_TIMERS;
            #if defined(INCLUDE_IC)
               if (httpOpen(pSetup->taskPriority) != HTTP_OK)
               {
                  TRACE(TERROR, ("Failed httpOpen"));
                  result = MHERR_COMP_NOT_OPEN;
               }
            #endif  /* INCLUDE_IC */
            }
         }
      }
      if (result == MHERR_OK)
      {
         TRACE(TSTATE,(""))
         progress = PRG_DONE_HTTP;
         result = MHEG5Initialise( pSetup );
         if (result == MHERR_OK)
         {
            progress = PRG_DONE_MHEG5;
         #ifdef INCLUDE_ICS
            /* Open the IC streamer */
            result = MHEG5StreamerOpen(pSetup->streamerBuffer, pSetup->streamerBufferSize, pSetup->taskPriority);
         #endif
         }
      }

      if (result == MHERR_OK)
      {
         DVB_MhegEventsStart(MHEG5_NotifyDvbEvent);
      }
   }
   /* ------------------------------------------------------------ */
   if (result != MHERR_OK && result != MHERR_COMP_ALREADY_OPEN)
   {
      TRACE(TSTATE,("progress=%d",progress))
      switch (progress)
      {
         case PRG_DONE_MHEG5:
            MHEG5_Terminate();

         case PRG_DONE_HTTP:
         #if defined(INCLUDE_IC)
            httpClose();
         #endif

         case PRG_DONE_TIMERS:
            VT_TimersExit();

         case PRG_DONE_MAIN:
            MHEG5Exit();

         case PRG_DONE_DSMCC:
         #ifndef CI_PLUS_ONLY
            MH5GlueDsmccClose();
         #endif

         case PRG_DONE_QUEUE:
            VQ_Close();

         case PRG_DONE_SYNCS:
            DestroySyncs();

         case PRG_DONE_MEMORY:
            MH5GlueMemoryTerminate();

         case PRG_DONE_GRAPHICS:
            MG_Terminate();
         case PRG_DONE_INIT:
         default:
            /*nothing*/;
      }
   }
   TRACE(TSTATE,("result=%d",result))
   FUNCTION_FINISH(MHEG5_Open)
   return result;
}

E_MhegErr MHEG5_Close(void)
{
   E_MhegErr result;

   FUNCTION_START(x)
   if (task_handle == NULL)
   {
      result = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      MHEG5_Stop();

      DVB_MhegEventsStop();

    #ifdef INCLUDE_ICS
      /* Close the IC streamer */
      MHEG5StreamerClose();
    #endif

   #if defined(INCLUDE_IC)
      httpClose();
   #endif  /* INCLUDE_IC */

      VT_TimersExit();

      result = MHEG5Exit();

      MHEG5_Terminate();

   #ifndef CI_PLUS_ONLY
      MH5GlueDsmccClose();
   #endif  /* !CI_PLUS_ONLY */

      VQ_Close();

      DestroySyncs();

      MH5GlueMemoryTerminate();

      MG_Terminate();

   }
   FUNCTION_FINISH(x)
   return result;
}

/************************ Start / Stop Functions *********************************/

static void startEngine( S_StartDsmApp *params )
{
   S_DvbLocator locator;
#ifndef CI_PLUS_ONLY
   U32BIT carouselId;
   BOOLEAN clear;
#endif /*CI_PLUS_ONLY*/

   FUNCTION_START(x)
   if (DVB_MhegIndexToDvbLocator(params->serviceIndex, &locator) != MHERR_OK)
   {
      TRACE(TERROR, ("si=%x", params->serviceIndex))
   }
   else
   {
      TRACE(TSTATE, ("starting sid=0x%x", locator.service_id))
   #ifndef CI_PLUS_ONLY
      if ( !ciplus_request_ndt &&
           (locator.transport_stream_id != default_service.transport_stream_id ||
            locator.original_network_id != default_service.original_network_id))
      {
         clear = TRUE;
      }
      else
      {
         ciplus_request_ndt = FALSE;
         clear = FALSE;
      }
      carouselId = MHEG5tuneProcess(&locator, params->serviceIndex);
      if (MH5GlueDsmccStart(&locator, carouselId, clear) == MHERR_OK)
      {
         TRACE(TSTATE, ("Started service 0x%x (%d)", locator.service_id, locator.service_id))
      }
   #else
      TRACE(TSTATE, ("DSM-CC not build in"))
   #endif  /* !CI_PLUS_ONLY */
      /* Store default service information */
      default_service = locator;
      default_service_index = params->serviceIndex;
   }
   FUNCTION_FINISH(x)
}

/*******************************************************************************
 * @brief   This function starts MHEG5 engine on the current broadcast service.
 *          It will cause MHEG5 engine to start retrieving the associated
 *          service information (i.e. PMT) and launch an appropriate broadcast
 *          application. This should mean MHEG5 engine will mount an associated
 *          DSM-CC carousel for this application. If this should fail, MHEG5 engine
 *          will periodically try to mount the DSM-CC boot carousel in order to
 *          launch the default MHEG-5 auto boot application.
 *          This is a non-blocking function, which may return before completion.
 *          It should be called whenever a tuning process has completed and
 *          the external application is aware of a new broadcast service.
   @ @param   serviceIndex "Service Index" for the new service
 * @param   quietMode pointer to return channel change mode that MHEG5 requires
 *          of the external application. Can be NULL, if not interested in mode.
 * @return  MHERR_OK                   - Success
 *          MHERR_COMP_NOT_OPEN        - Component not ready to start.
 *          MHERR_COMP_ALREADY_STARTED - Component has already been started.
 *          MHERR_BAD_PARAMETER        - Invalid parameter.
 *******************************************************************************/
E_MhegErr MHEG5_Start( S32BIT serviceIndex, E_ChannelStartMode *quietMode )
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr err;
   E_ApiStatus prev_state;
   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      err = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      STB_OSMutexLock( api_mutex );
      if (started_state == VS_RUNNING)
      {
         TRACE(TERROR, ("MHEG5 already Started"));
         err = MHERR_COMP_ALREADY_STARTED;
      }
      else
      {
         prev_state = started_state;
         started_state = VS_RUNNING;
         err = MHERR_OK;
      }
      STB_OSMutexUnlock( api_mutex );
      if (err == MHERR_OK)
      {
      #ifndef CI_PLUS_ONLY
         if (quietMode != NULL)
         {
            *quietMode = MHEG5_GetTuningInfoMode(serviceIndex);
         }
      #endif
         TRACE(TSTATE, ("serviceIndex=%x", serviceIndex))
         event_msg.proc_msg_func = (F_MSG_PROCESS)startEngine;
         event_msg.data_type = DT_VALUE;
         event_msg.data.start.serviceIndex = serviceIndex;
         err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
         if (err != MHERR_OK)
         {
            STB_OSMutexLock( api_mutex );
            started_state = prev_state;
            STB_OSMutexUnlock( api_mutex );
            TRACE(TERROR, ("VQ_PutMsg Failed"));
         }
      }
   }
   return err;
}

static void stopEngine(MHEG5StopEventParams_t *params)
{
   U8BIT action = params->action;

   FUNCTION_START(x)
   TRACE(TSTATE, ("action=%d", action));
   action = MHEG5HandleEngineStopAction( action );
   if (action == STOP_ACTION_MHEG_TUNE)
   {
      running_state = VS_TUNING;
   }
   else
   {
      running_state = VS_STOPPED;
   }
   if (action == STOP_ACTION_CI_PLUS_NDT)
   {
      ciplus_request_ndt = TRUE;
   }
#ifndef CI_PLUS_ONLY
   /* Attempt carousel unload or boot stop */
   MH5GlueDsmccStop( action );
#endif  /* !CI_PLUS_ONLY */

   TRACE(TSTATE, ("Last serv_id=0x%x,net_id=0x%x", default_service.service_id, default_service.original_network_id))

   /* free 'string' block memory no longer required */
   STR_TidyUp();

   /*
      default_service.original_network_id = 0;
      default_service.transport_stream_id = 0;
    */
   default_service.service_id = 0;
   /* signal that caller task can resume */
   STB_OSSemaphoreSignal(stop_sema);
   TRACE(TSTATE, ("done"));
   FUNCTION_FINISH(x)
}

/*******************************************************************************
 * @brief   Tells MHEG5 engine to enter stop state (i.e. no broadcast service).
 *          This function should kill any currently running MHEG5 broadcast
 *          application, and release allocated memory and resources.
 *          This is a synchronous blocking function.
 * @return  MHERR_OK               - Success
 *          MHERR_COMP_NOT_STARTED - Component not ready to stop.
 *******************************************************************************/
E_MhegErr MHEG5_Stop( void )
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr cqu_err;
   E_ApiStatus prev_state;

   FUNCTION_START(x)
   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      cqu_err = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      STB_OSMutexLock( api_mutex );
      prev_state = started_state;
      if (started_state == VS_STOPPED)
      {
         TRACE(TERROR, ("MHEG5 Not Started"));
         cqu_err = MHERR_COMP_NOT_STARTED;
      }
      else
      {
         started_state = VS_STOPPED;
         cqu_err = MHERR_OK;
      }
      STB_OSMutexUnlock( api_mutex );
      if (cqu_err == MHERR_OK)
      {
         event_msg.proc_msg_func = (F_MSG_PROCESS)stopEngine;
         event_msg.data_type = DT_VALUE;
         event_msg.data.stop.action = STOP_ACTION_CLEAR_DSMCC;
         cqu_err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
         if (cqu_err != MHERR_OK)
         {
            STB_OSMutexLock( api_mutex );
            started_state = prev_state;
            STB_OSMutexUnlock( api_mutex );
            TRACE(TERROR, ("VQ_PutMsg Failed"));
         }
         else
         {
            /* Wait for notification that stop has been processed */
            STB_OSSemaphoreWait(stop_sema);
            TRACE(TSTATE, (" vgr done"));
         }
      }
   }
   FUNCTION_FINISH(x)
   return cqu_err;
}


/*******************************************************************************
 * @brief   Tells MHEG5 engine to enter stop state (i.e. no broadcast service).
 *          This function should kill any currently running MHEG5 broadcast
 *          application, and release allocated memory and resources.
 *          This is a synchronous blocking function.
 * @return  MHERR_OK               - Success
 *          MHERR_COMP_NOT_STARTED - Component not ready to stop.
 *******************************************************************************/
E_MhegErr MHEG5_StopWithoutKilling( void )
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr cqu_err;
   E_ApiStatus prev_state;

   FUNCTION_START(x)
   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      cqu_err = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      STB_OSMutexLock( api_mutex );
      prev_state = started_state;
      if (started_state == VS_STOPPED)
      {
         cqu_err = MHERR_COMP_NOT_STARTED;
      }
      else
      {
         started_state = VS_STOPPED;
         cqu_err = MHERR_OK;
      }
      STB_OSMutexUnlock( api_mutex );
      if (cqu_err == MHERR_OK)
      {
         event_msg.proc_msg_func = (F_MSG_PROCESS)stopEngine;
         event_msg.data_type = DT_VALUE;
         event_msg.data.stop.action = STOP_ACTION_CI_PLUS_NDT;
         cqu_err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
         if (cqu_err != MHERR_OK)
         {
            STB_OSMutexLock( api_mutex );
            started_state = prev_state;
            STB_OSMutexUnlock( api_mutex );
            TRACE(TERROR, ("VQ_PutMsg Failed"));
         }
         else
         {
            /* Wait for notification that stop has been processed */
            STB_OSSemaphoreWait(stop_sema);
            TRACE(TSTATE, (" vgr done"));
         }
      }
   }
   FUNCTION_FINISH(x)
   return cqu_err;
}

/*******************************************************************************
 * @brief   Suspend MHEG5 engine (while there is no valid broadcast service).
 *          This function should be called as an alternative to MHEG5_Stop, when
 *          the external application is performing a tune as requested by MHEG5.
 *          This may or may not kill the running MHEG application.
 *          This suspend state will remain in effect until MHEG5_Start or
 *          MHEG5_Stop is called.
 * @return  MHERR_OK               - Success
 *          MHERR_REQUEST_IGNORED  - Already suspended
 *          MHERR_COMP_NOT_STARTED - Component not ready to stop.
 *******************************************************************************/
E_MhegErr MHEG5_Suspend( void )
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr cqu_err;
   E_ApiStatus prev_state;

   FUNCTION_START(x)
   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      cqu_err = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      STB_OSMutexLock( api_mutex );
      prev_state = started_state;
      switch (started_state)
      {
         case VS_TUNING:
            cqu_err = MHERR_REQUEST_IGNORED;
            break;

         case VS_REBOOT:
         case VS_RUNNING:
            started_state = VS_TUNING;
            cqu_err = MHERR_OK;
            break;

         case VS_STOPPED:
            cqu_err = MHERR_COMP_NOT_STARTED;
      }
      STB_OSMutexUnlock( api_mutex );
      if (cqu_err == MHERR_OK)
      {
         event_msg.proc_msg_func = (F_MSG_PROCESS)stopEngine;
         event_msg.data_type = DT_VALUE;
         event_msg.data.stop.action = STOP_ACTION_MHEG_TUNE;
         cqu_err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
         if (cqu_err != MHERR_OK)
         {
            STB_OSMutexLock( api_mutex );
            started_state = prev_state;
            STB_OSMutexUnlock( api_mutex );
            TRACE(TERROR, ("VQ_PutMsg Failed"));
         }
         else
         {
            /* Wait for notification that stop has been processed */
            STB_OSSemaphoreWait(stop_sema);
            TRACE(TSTATE, (" vgr done"));
         }
      }
   }
   FUNCTION_FINISH(x)
   return cqu_err;
}

#ifndef CI_PLUS_ONLY

E_MhegErr MHEG5_Reboot( void )
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr cqu_err;
   STB_OSMutexLock( api_mutex );
   if (started_state == VS_RUNNING)
   {
      started_state = VS_REBOOT;
      cqu_err = MHERR_OK;
   }
   else
   {
      cqu_err = MHERR_COMP_NOT_STARTED;
      TRACE(TERROR, ("Not Started"));
   }
   STB_OSMutexUnlock( api_mutex );
   if (cqu_err == MHERR_OK)
   {
      event_msg.proc_msg_func = MHEG5StartReboot;
      event_msg.data_type = DT_NONE;
      cqu_err = VQ_PutMsg(&event_msg, PRTY_HIGH);
      if (cqu_err != MHERR_OK)
      {
         TRACE(TERROR, ("VQ_PutMsg Failed"));
      }
      else
      {
         TRACE(TMHBOOT, ("Starting reboot"));
      }
   }
   return cqu_err;
}

#endif  /* !CI_PLUS_ONLY */

/*********** Active State (Pause/Resume) Functions *********************************/

BOOLEAN MH5GlueActiveState(void)
{
   /* Only called by MHEG5 task*/
   return active_state;
}

static void Pause( void *params )
{
   FUNCTION_START(x)
   TRACE(TSTATE, ("state=%d", active_state))
   if (active_state)
   {
    #ifdef INCLUDE_ICS
      MHEG5StreamerSetActiveState(FALSE);
    #endif
      MHEG5Pause();
      active_state = FALSE;
   }
   STB_OSSemaphoreSignal( pause_sema );
   FUNCTION_FINISH(x)
}

static void Resume( void *params )
{
   FUNCTION_START(x)
   TRACE(TSTATE, ("state=%d", active_state))
   if (!active_state)
   {
      MHEG5Resume();
    #ifdef INCLUDE_ICS
      MHEG5StreamerSetActiveState(TRUE);
    #endif
      active_state = TRUE;
   }
   FUNCTION_FINISH(x)
}

E_MhegErr MHEG5_Pause(void)
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr cqu_err;
   FUNCTION_START(x)
   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      cqu_err = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      event_msg.proc_msg_func = Pause;
      event_msg.data_type = DT_NONE;
      cqu_err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
      if (cqu_err != MHERR_OK)
      {
         TRACE(TERROR, ("VQ_PutMsg Failed"));
      }
      else
      {
         /* Wait for notification that 'pause' has been processed */
         STB_OSSemaphoreWait(pause_sema);
         TRACE(TSTATE | TMHAPI, ("done"))
      }
   }
   FUNCTION_FINISH(x)
   return cqu_err;
}

E_MhegErr MHEG5_Resume(void)
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr cqu_err;

   FUNCTION_START(x)
   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      cqu_err = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      event_msg.proc_msg_func = Resume;
      event_msg.data_type = DT_NONE;
      cqu_err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
      if (cqu_err != MHERR_OK)
      {
         TRACE(TERROR, ("VQ_PutMsg Failed"));
      }
      else
      {
         TRACE(TSTATE | TMHAPI, ("..."))
      }
   }
   FUNCTION_FINISH(x)
   return cqu_err;
}

static void ResetScreen( MHEG5ResetResolutionParams_t *params )
{
   FUNCTION_START(x)

   *(params->pResult) = MHEG5ResetResolution( params->screenWidth, params->screenHeight );

   Pause( NULL );

   FUNCTION_FINISH(x)
}

E_MhegErr MHEG5_SetScreenResolution( U16BIT screenWidth, U16BIT screenHeight )
{
   MHEG5eventMessage_t event_msg;
   E_MhegErr err;

   FUNCTION_START(x)
   /* Structure for passing event to the component task */
   TRACE(TMHAPI, ("( %d, %d, %d )", screenWidth, screenHeight))

   if (task_handle == NULL)
   {
      TRACE(TERROR, ("MHEG5 Not Open"));
      err = MHERR_COMP_NOT_OPEN;
   }
   else if (screenWidth < 720 || screenHeight < 576)
   {
      TRACE(TERROR, ("Bad Resolution (%d,%d)",screenWidth,screenHeight));
      err = MHERR_BAD_PARAMETER;
   }
   else
   {
      restore_active = active_state;

      event_msg.proc_msg_func = (F_MSG_PROCESS)ResetScreen;
      event_msg.data_type = DT_VALUE;
      event_msg.data.resetRes.screenWidth = screenWidth;
      event_msg.data.resetRes.screenHeight = screenHeight;
      event_msg.data.resetRes.pResult = &err;
      err = VQ_PutMsg(&event_msg, PRTY_CRITICAL);
      if (err == MHERR_OK)
      {
         /* Wait for notification that msg has been processed */
         STB_OSSemaphoreWait(pause_sema);
      }
   }
   FUNCTION_FINISH(x)
   return err;
}

void MHEG5_RestoreScreen(void)
{
   if (restore_active)
   {
      MHEG5_Resume();
   }
}

E_MhegErr MHEG5_SetActiveState(BOOLEAN newActiveState)
{
   return (newActiveState == FALSE) ? MHEG5_Pause() : MHEG5_Resume();
}

void MHEG5GetDefaultService(S_DVB_LOCATOR *dvb_locator)
{
   *dvb_locator = default_service;
}

U16BIT MHEG5DefaultServiceId(void)
{
   return default_service.service_id;
}

S32BIT MHEG5GetCurrentServiceIndex(void)
{
    return default_service_index;
}