/* SPDX-License-Identifier: LGPL-2.1-only OR BSD-3-Clause */
/******************************************************************************
 *
 * This file is provided under a dual license.  When you use or
 * distribute this software, you may choose to be licensed under
 * version 2.1 of the GNU Lesser General Public License
 * ("LGPLv2.1 License") or BSD License.
 *
 * LGPLv2.1 License
 *
 * Copyright(C) 2019 MediaTek Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of version 2.1 of the GNU Lesser General Public
 * License as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html for more
 * details.
 *
 * BSD LICENSE
 *
 * Copyright(C) 2019 MediaTek Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *  * Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *****************************************************************************/

/*----------------------------------------------------------------------------*/
/*! @file c_svctx.h 
 *  $File: //DTV/MP_BR/DTV_X_IDTV1501_002288_8_001_800_002/apollo/middleware/public/svctx/c_svctx.h $
 *  $Revision: #1 $
 *  $Date: 2015/11/10 $
 *  $Author: dtvbm11 $
 *  
 *  @par Description:
 *
 */
/*----------------------------------------------------------------------------*/
#ifndef _C_SVCTX_H_
#define _C_SVCTX_H_

/*-----------------------------------------------------------------------------
 *  include files
 *---------------------------------------------------------------------------*/
#include "u_svctx.h"
#include "u_evctx.h"
#include "u_scc.h"
#include "u_svl.h"
#include "u_brdcst.h"
#include "u_cm.h"
#ifdef ENABLE_MULTIMEDIA        
#include "u_mm_hdlr.h"
#endif
#ifdef SYS_RECORD_SUPPORT
#include "u_rec_hdlr.h"
#endif

/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_SVCTX
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

/*-----------------------------------------------------------------------------
 * functions declarations
 *---------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @brief  This API open a new service context from the service context
 *              pool or attaches to an existing service context if the name
 *              is existed. 
 *  @param  [in]  ps_svctx_name - References the service context name for the open.
 *  @param  [out] ph_svctx - Contains the service context handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - Invalid argument.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to open the service context.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - The Handle link operation is failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_open(
                    const CHAR*                     ps_svctx_name,    /* in  */
                    HANDLE_T*                       ph_svctx          /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API performs a close. If the handle is the last client's
 *              handle, this service context instance will return to the service
 *              context pool.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Failed to close the service context.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_close(
                    HANDLE_T                        h_svctx           /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  Selects a service to be presented in this service context
 *              instance in asynchronous way. If the instance is already
 *              presenting content, the new selection request will replace
 *              the previous request being presented. If the
 *              instance is not presenting, successful conclusion of this
 *              operation results in the instance entering the presenting
 *              state. Successful completion of the selection is notified
 *              via pf_nfy with
 *                  e_nfy_cond = SVCTX_COND_PRESENTING,
 *                  e_code     = SVCTX_NTFY_CODE_NORMAL
 *              If the signal is loss, the client will be notified via pf_nfy
 *                  e_nfy_cond = SVCTX_COND_READY,
 *                  e_code     = SVCTX_NTFY_CODE_SIGNAL_LOSS
 *              And in such case, the service context will try to re-connect.
 *
 *              In processing the selection, the client will be notified
 *              when the signal is locked (connection connected) via pf_nfy with
 *                  e_nfy_cond = SVCTX_COND_PENDING,
 *                  e_code     = SVCTX_NTFY_CODE_SIGNAL_LOCKED
 *              In processing the selection, the client will be notified
 *              when the service ls blocked after being checked by the x_svctx_svc_block_check_fct
 *              function provided by client in pt_snk_desc via pf_nfy with
 *                  e_nfy_cond = SVCTX_COND_PENDING,
 *                  e_code     = SVCTX_NTFY_CODE_SERVICE_BLOCKED
 *              In processing the selection, the client will be notified
 *              when a kind of stream is not existed in SCDB  via pf_nfy with
 *                  e_nfy_cond    = SVCTX_COND_PENDING,
 *                  e_code        = SVCTX_NTFY_CODE_NO_STREAM
 *                  e_stream_type = the actual stream type
 *              If the selection process fails becuase lack of resources
 *              the client will be notified via pf_nfy.
 *                  e_nfy_cond    = current service context state,
 *                  e_code        = SVCTX_NTFY_CODE_NO_RESOURCES
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  ui4_stream_mode - References the desired stream types for
 *                             the select operation. Client should use the
 *                             macros ST_MASK_AUDIO, ST_MASK_VIDEO,
 *                             ST_MASK_CLOSED_CAPTION and so on (defined in
 *                             u_common.h) to OR them for this input argument.
 *  @param  [in]  pt_src_desc - References the source description.
 *  @param  [in]  pt_snk_desc - References the sink description.
 *  @param  [in]  pf_nfy - References the service notify function. 
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function. 
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - Invalid argument.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Failed to send request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_svc(
                    HANDLE_T                        h_svctx,          /* in  */
                    UINT32                          ui4_stream_mode,  /* in  */
                    const SRC_DESC_T*               pt_src_desc,      /* in  */
                    const SNK_DESC_T*               pt_snk_desc,      /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API causes the service context instance to stop presenting
 *              content and enter the READY state in asynchronous way.
 *              Connection, SCDB, Session, and Streams used in the presentation
 *              will be released. The client
 *              that issues the service selection request will be notified
 *              via its pf_nfy (set in x_svctx_select_svc()) with
 *                  e_nfy_cond = SVCTX_COND_READY,
 *                  e_code     = SVCTX_NTFY_CODE_USER_STOP
 *              If the service is already in stopping, the client
 *              that issues the service selection request will still be notified
 *              via its pf_nfy (set in x_svctx_select_svc()) with
 *                  e_nfy_cond = SVCTX_COND_PENDING,
 *                  e_code     = SVCTX_NTFY_CODE_IN_STOPPING
 *              If the service context instance is in the READY state, the client
 *              that issues the service selection request will still be notified
 *              via its pf_nfy (set in x_svctx_select_svc()) with
 *                  e_nfy_cond = SVCTX_COND_READY,
 *                  e_code     = SVCTX_NTFY_CODE_STOPPED
 *              If the service context instance is in the POOLED state,
 *              no action is performed
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Failed to send request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_stop_svc(
                    HANDLE_T                        h_svctx           /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to check the service context instance is in
 *              running or not
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Failed to send request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_is_running (
                    HANDLE_T                    h_svctx,            /* in  */
                    BOOL*                       pb_result           /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API causes the service context instance to stop presenting
 *              content and enter the READY state synchronously.
 *              Connection, SCDB, Session,
 *              Streams used in the presention will be released. The client
 *              that issues the service selection request will be notified
 *              via its pf_nfy (set in x_svctx_select_svc()) with
 *              (SVCTX_COND_READY, SVCTX_NTFY_CODE_USER_STOP).
 *              This API completes asynchronously. No action is performed if the
 *              service context instance is already in the READY or POOLED state.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_sync_stop_svc(
                    HANDLE_T                        h_svctx,
                    UINT32                          ui4_time
                    );
/*-----------------------------------------------------------------------------
 * Name: c_svctx_sync_stop_selector_svc
 *
 * Description: this API is  only the  presenting SVC selector  can stop the svc, otherwise,  the
 *            presenting can't stopped. . This API causes the service context instance to stop presenting
 *              content and enter the READY state in synchronous way, Connection,
 *              SCDB, Session, Streams used in the presentation will be released
 *              and the return value is SVCTXR_OK. However, the client
 *              that issues the service selection request will still be notified
 *              via its pf_nfy (set in x_svctx_select_svc()) with
 *                  e_nfy_cond = SVCTX_COND_READY,
 *                  e_code     = SVCTX_NTFY_CODE_USER_STOP
 *              If the return value is SVCTXR_TIMEOUT, the stop operation is still
 *              processed in service context's thread. When the service
 *              is stopped, the client will receive the notification, too.
 *              If the service context instance is in the READY state, the client
 *              that issues the service selection request will still be notified
 *              via its pf_nfy (set in x_svctx_select_svc()) with
 *                  e_nfy_cond = SVCTX_COND_READY,
 *                  e_code     = SVCTX_NTFY_CODE_STOPPED
 *              If the service context instance is in the POOLED state,
 *              no action is performed
 * Inputs:  h_svctx            Contains a handle to a service context.
 *          ui4_time           maximum time duration in ms to wait the API
 *                             to finish. if it is zero, it will be set to
 *                             DEFAULT_STOP_SVC_TIMEOUT
 * Outputs: -
 *
 * Returns: SVCTXR_OK          Routine successful.
 *          SVCTXR_INV_HANDLE  Invalid service context handle.
 *          SVCTXR_NOT_INIT    The Service Context Module is not initialized yet.
 *          SVCTXR_TIMEOUT     Failed to stop the service within "ui4_time" duration.
 *          SVCTXR_FAIL        Failed to send request.
 *-----------------------------------------------------------------------------*/
extern INT32 c_svctx_sync_stop_selector_svc(
                    HANDLE_T                    h_svctx,
                    UINT32                      ui4_time
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the audio volume.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_volume_info - References to the structure containing the
 *                             scc audio volume information data.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG - pt_volume_info is NULL or
 *                             out port is SCC_AUD_OUT_PORT_2_CH but e_ch is not
 *                             one of SCC_AUD_CHANNEL_FRONT_LEFT,
 *                             SCC_AUD_CHANNEL_FRONT_RIGHT, and
 *                             SCC_AUD_CHANNEL_ALL.
 *  @retval SVCTXR_FAIL - The operation for accessing device is failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_volume(
                    HANDLE_T                        h_svctx,          /* in  */
                    const SCC_AUD_VOLUME_INFO_T*    pt_volume_info    /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get the audio volume.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_volume_info - References to the structure containing the
 *                             scc audio volume information data.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG - pt_volume_info is NULL
 *  @retval SVCTXR_FAIL - The operation for accessing device is failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_volume(
                    HANDLE_T                        h_svctx,            /* in  */
                    SCC_AUD_VOLUME_INFO_T*          pt_volume_info      /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the audio to mute or unmute.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  b_is_mute - Contains a boolean value for setting audio
 *                             to mute or unmute.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - The operation for accessing device is failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_mute(
                    HANDLE_T                        h_svctx,          /* in  */
                    BOOL                            b_is_mute         /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to check the audio is mute or unmute.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pb_is_mute - References to a boolean value for retrieving audio
 *                             is mute or unmute.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pb_is_mute is NULL
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - The operation for accessing device is failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_mute(
                    HANDLE_T                        h_svctx,          /* in  */
                    BOOL*                           pb_is_mute        /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API retrieves the stream id and stream data from
 *              stream component database by a specific type and a filter
 *              function provided by caller. If the data is not populated into
 *              stream component database, caller will get a SVCTXR_WRONG_STATE
 *              return value.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream component type for filtering.
 *  @param  [in]  pf_filter - References to the filter function provided by caller.
 *                             It can't be NULL.
 *  @param  [in]  pv_fltr_tag - References to a caller-defined tag. It will pass to
 *                             to caller when the pf_filter is invoked.
 *  @param  [out] pt_comp_id - References to the structure containing the
 *                             stream component id. It can't be NULL.
 *  @param  [out] pt_scdb_rec - References to the structure containing the
 *                             stream component data.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pf_filter or pt_comp_id is NULL.
 *  @retval SVCTXR_WRONG_STATE - If related SCDB is not ready and opened.
 *  @retval SVCTXR_NOT_EXIST - The stream component is not existed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_stream_comp_id(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type,        /* in  */
                    x_svctx_strm_comp_filter_fct    pf_filter,          /* in  */
                    VOID*                           pv_fltr_tag,        /* in  */
                    STREAM_COMP_ID_T*               pt_comp_id,         /* out */
                    SCDB_REC_T*                     pt_scdb_rec         /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API retrieves the selected stream of a specific type from
 *              a presenting service context object.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream component type for filtering.
 *  @param  [out] pt_scdb_rec - Contains the stream component type for filtering.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pt_scdb_rec is NULL.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NOT_EXIST - The stream component is not existed.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_using_scdb_rec(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type,        /* in  */
                    SCDB_REC_T*                     pt_scdb_rec         /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API retrieves the strm_req_type of a presenting stream.
 *
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream component type for filtering.
 *  @param  [out] pe_strm_req_type  - Contains the stream req type.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pt_scdb_rec is NULL.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NOT_EXIST - The stream component is not existed.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_strm_req_type(
                    HANDLE_T                        h_svctx,          /* in  */
                    STREAM_TYPE_T                   e_strm_type,      /* in  */
                    STRM_REQ_TYPE_T*                pe_strm_req_type  /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This APIis used to stop a specific stream via stream type
 *              in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] e_strm_type - Contains the stream type for stopping.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_stream(
                    HANDLE_T                        h_svctx,            /* in  */
                    const STREAM_COMP_ID_T*         pt_comp_id,         /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,             /* in  */
                    VOID*                           pv_nfy_tag          /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to selects a specific stream via PID
 *              in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type for selecting.
 *  @param  [in]  t_mpeg_2_pid - Contains the MPEG2 PID value.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 *  @retval SVCTXR_INV_ARG - pt_comp_id is NULL.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_EXIST - The related SCDB record is not existed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_mpeg_stream_by_pid(
                    HANDLE_T                        h_svctx,        /* in  */
                    STREAM_TYPE_T                   e_strm_type,    /* in  */
                    MPEG_2_PID_T                    t_mpeg_2_pid,   /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,         /* in  */
                    VOID*                           pv_nfy_tag      /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to selects a specific stream via PID
 *              in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_stream_info - References the stream info data structure.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 *  @retval SVCTXR_INV_ARG - pt_comp_id is NULL.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_EXIST - The related SCDB record is not existed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_mpeg_stream_by_pid_ex(
                    HANDLE_T                        h_svctx,          /* in  */
                    SVCTX_STREAM_INFO_T*            pt_stream_info,   /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );                                     

/*------------------------------------------------------------------*/
/*! @brief  This API is used to selects a specific AD stream via PID
 *              in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_stream_info - References the stream info data structure.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 *  @retval SVCTXR_INV_ARG - pt_comp_id is NULL.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_EXIST - The related SCDB record is not existed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_mpeg_ad_stream_by_pid(
                    HANDLE_T                        h_svctx,
                    SVCTX_STREAM_INFO_T*            pt_stream_info,
                    x_svctx_select_nfy_fct          pf_nfy,
                    VOID*                           pv_nfy_tag
                    );
/*------------------------------------------------------------------*/
/*! @brief  This APIis used to stop a specific stream via stream type
 *              in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type for stopping.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_stop_stream(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type         /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This APIis used to stop a specific stream via stream type
 *              in synchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type for stopping.
 *  @param  [in]  ui4_time - duration of stop
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_sync_stop_stream(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type,        /* in  */
                    UINT32                          ui4_time            /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific audio stream via ISO639 language
 *              code in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_lang - References to the structure containing the
 *                             language code.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 *  @retval SVCTXR_INV_ARG - pt_lang is NULL.
 *  @retval SVCTXR_NOT_EXIST - The stream component is not existed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_audio_stream(
                    HANDLE_T                        h_svctx,            /* in  */
                    const ISO_639_LANG_T*           pt_lang,            /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,             /* in  */
                    VOID*                           pv_nfy_tag          /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects specific main audio stream and supplementary audio stream via 
 *              stream comp id in asynchronous way.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_main_comp_id - References to the structure containing the main audio comp id.
 *  @param  [in]  pt_sup_comp_id - References to the structure containing the supplementary audio comp id.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 *  @retval SVCTXR_INV_ARG - pt_lang is NULL.
 *  @retval SVCTXR_NOT_EXIST - The stream component is not existed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_audio_stream_ex(
                    HANDLE_T                        h_svctx,          /* in  */
                    const STREAM_COMP_ID_T*         pt_main_comp_id,  /* in  */
                    const STREAM_COMP_ID_T*         pt_sup_comp_id,   /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific closed captioning stream in
 *              asynchronous way. If the cc stream is selected successfully,
 *              caller will be notified via the pf_nfy with
 *                  e_nfy_cond    = SVCTX_COND_PRESENTING,
 *                  e_code        = SVCTX_NTFY_CODE_STREAM_STARTED
 *                  e_stream_type = ST_CLOSED_CAPTION
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_cc_gl_plane - Contains a handle to a graphic plane for closed
 *                             captioning handler to draw.
 *  @param  [in]  pt_cc_filter - References to the structure containing the
 *                             cc filter data.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_cc_filter is NULL or h_cc_gl_plane is NULL_HANDLE.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_cc_stream(
                    HANDLE_T                        h_svctx,          /* in  */
                    HANDLE_T                        h_cc_gl_plane,    /* in  */
                    const SM_CC_FILTER_T*           pt_cc_filter,     /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific closed captioning stream in
 *              asynchronous way. If the cc stream is selected successfully,
 *              caller will be notified via the pf_nfy with
 *                  e_nfy_cond    = SVCTX_COND_PRESENTING,
 *                  e_code        = SVCTX_NTFY_CODE_STREAM_STARTED
 *                  e_stream_type = ST_CLOSED_CAPTION
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_cc_gl_plane - Contains a handle to a graphic plane for closed
 *                             captioning handler to draw.
 *  @param  [in]  pt_cc_filter - References to the structure containing the
 *                             cc filter data.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_cc_filter is NULL or h_cc_gl_plane is NULL_HANDLE.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_isdb_caption_stream(
                    HANDLE_T                        h_svctx,          /* in  */
                    HANDLE_T                        h_gl_plane,       /* in  */
                    UINT32                          ui4_caption_idx,  /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific closed captioning stream in
 *              asynchronous way. If the cc stream is selected successfully,
 *              caller will be notified via the pf_nfy with
 *                  e_nfy_cond    = SVCTX_COND_PRESENTING,
 *                  e_code        = SVCTX_NTFY_CODE_STREAM_STARTED
 *                  e_stream_type = ST_CLOSED_CAPTION
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_cc_gl_plane - Contains a handle to a graphic plane for closed
 *                             captioning handler to draw.
 *  @param  [in]  pt_cc_filter - References to the structure containing the
 *                             cc filter data.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_cc_filter is NULL or h_cc_gl_plane is NULL_HANDLE.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_isdb_text_stream(
                    HANDLE_T                        h_svctx,          /* in  */
                    HANDLE_T                        h_gl_plane,       /* in  */
                    UINT32                          ui4_text_idx,     /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific subtitle stream in
 *              asynchronous way. If the subtitle stream is selected successfully,
 *              caller will be notified via the pf_nfy with
 *                  e_code        = SVCTX_NTFY_CODE_STREAM_STARTED
 *                  e_stream_type = ST_SUBTITLE
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_gl_plane - Contains a handle to a graphic plane for closed
 *                             captioning handler to draw.
 *  @param  [in]  pt_lang - References to the structure containing the
 *                             language code.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_lang is NULL or h_gl_plane is NULL_HANDLE.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_subtitle_stream(
                    HANDLE_T                        h_svctx,          /* in  */
                    HANDLE_T                        h_gl_plane,       /* in  */
                    const ISO_639_LANG_T*           pt_lang,          /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific subtitle stream in
 *              asynchronous way. If the subtitle stream is selected successfully,
 *              caller will be notified via the pf_nfy with
 *                  e_code        = SVCTX_NTFY_CODE_STREAM_STARTED
 *                  e_stream_type = ST_SUBTITLE
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_gl_plane - Contains a handle to a graphic plane for closed
 *                             captioning handler to draw.
 *  @param  [in]  pt_comp_id - References to the structure containing the
 *                             stream component id.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_lang is NULL or h_gl_plane is NULL_HANDLE.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_subtitle_stream_by_comp_id(
                    HANDLE_T                        h_svctx,          /* in  */
                    HANDLE_T                        h_gl_plane,       /* in  */
                    const STREAM_COMP_ID_T*         pt_comp_id,       /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API selects a specific subtitle stream in
 *              asynchronous way. If the subtitle stream is selected successfully,
 *              caller will be notified via the pf_nfy with
 *                  e_code        = SVCTX_NTFY_CODE_STREAM_STARTED
 *                  e_stream_type = ST_SUBTITLE
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_gl_plane - Contains a handle to a graphic plane for closed
 *                             captioning handler to draw.
 *  @param  [in]  pt_sbtl_info - Contains extern information for subtitle playback.
 *  @param  [in]  pt_comp_id - References to the structure containing the
 *                             stream component id.
 *  @param  [in]  pf_nfy - References the stream notify function.
 *  @param  [in]  pv_nfy_tag - References the tag passed to the notify function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_lang is NULL or h_gl_plane is NULL_HANDLE.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_select_subtitle_stream_by_comp_id_ex(
                    HANDLE_T                        h_svctx,          /* in  */
                    HANDLE_T                        h_gl_plane,       /* in  */
                    const SM_SBTLH_STREAM_INFO*     pt_sbtl_info,     /* in  */
                    const STREAM_COMP_ID_T*         pt_comp_id,       /* in  */
                    x_svctx_select_nfy_fct          pf_nfy,           /* in  */
                    VOID*                           pv_nfy_tag        /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get service list record by channel id and
 *              surfing mode, i.e. next channel, previous channel, or this channel.
 *  @param  [in]  h_svl - Contains a handle to a service list.
 *  @param  [in]  ui4_nw_mask - Contains the network mask for filtering service
 *                                  record.
 *  @param  [in]  e_surf_mode - Contains the surfing mode.
 *  @param  [in]  pui4_channel_id - References to the variable containing the
 *                                  channel id.
 *  @param  [out] pui4_channel_id - References to the variable containing the
 *                                  resulted channel id.
 *  @param  [out] pt_svl_rec - References to the structure containing the
 *                                  service list record data.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pui4_channel_id or pt_svl_rec is NULL.
 *  @retval SVCTXR_NO_RECORD - There's no any record in this service list
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_svc_rec_by_channel_id(
                    HANDLE_T                        h_svl,              /* in */
                    UINT32                            ui4_nw_mask,        /* in */
                    SURF_MODE_T                     e_surf_mode,        /* in */
                    UINT32*                         pui2_channel_id,    /* i/o*/
                    SVL_REC_T*                      pt_svl_rec          /* out*/
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set video plane to normal, blank or quat-video.
 *          The details about e_mode should refer to stream manager's
 *          SCC_VID_MODE_T.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_mode - Contains the mode to set the video plane.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_WRONG_STATE - The Service Context object is blocked.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_video_plane(
                    HANDLE_T                        h_svctx,
                    SCC_VID_MODE_T                  e_mode
                    );

/*------------------------------------------------------------------*/
/*! @brief  This function is used to set the attribuites of a session.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Contains the pipe type.
 *  @param  [in]  e_set_type - Contains the type of attributes to set.
 *  @param  [in]  pv_set_info - References to the data information of the set type.
 *  @param  [in]  ui4_set_info_size - Contains the size of data information of the
 *                            set type.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_SUPPORT - The e_set_type is not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_session_attr(
                    HANDLE_T                    h_svctx,
                    STREAM_TYPE_T               e_pipe_type,
                    SM_SET_TYPE_T               e_set_type,
                    VOID*                       pv_set_info,
                    SIZE_T                      z_set_info_size
                    );

/*------------------------------------------------------------------*/
/*! @brief  This function is used to get the attribuites of a session.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Contains the pipe type to get.
 *  @param  [in]  e_get_type - Contains the type of attributes to get.
 *  @param  [in]  pv_get_info - References to the data information of the get type.
 *  @param  [in]  pui4_get_info_size - References to the size of data information of
 *                             the get type.
 *  @param  [out] pv_get_info - content of information
 *  @param  [out] pui4_get_info_size - size of information
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_session_attr(
                    HANDLE_T                    h_svctx,
                    STREAM_TYPE_T               e_pipe_type,
                    SM_GET_TYPE_T               e_get_type,
                    VOID*                       pv_get_info,            /* IN/OUT */
                    SIZE_T*                     pz_get_info_size        /* IN/OUT */
                    );
/*------------------------------------------------------------------*/
/*! @brief  This function is used to set the attribuites of a stream.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type.
 *  @param  [in]  e_set_type - Contains the type of attributes to set.
 *  @param  [in]  pv_set_info - References to the data information of the set type.
 *  @param  [in]  ui4_set_info_size - Contains the size of data information of the
 *                            set type.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_SUPPORT  - The stream type is not supported in this service
 *                             context object.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_stream_attr(
                    HANDLE_T                    h_svctx,
                    STREAM_TYPE_T               e_strm_type,
                    SM_SET_TYPE_T               e_set_type,
                    VOID*                       pv_set_info,
                    SIZE_T                      z_set_info_size
                    );

/*------------------------------------------------------------------*/
/*! @brief  This function is used to get the attribuites of a stream.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type.
 *  @param  [in]  e_set_type - Contains the type of attributes to set.
 *  @param  [in]  pv_set_info - References to the data information of the set type.
 *  @param  [in]  ui4_set_info_size - Contains the size of data information of the
 *                            set type.
 *  @param  [out] pv_get_info - content of information
 *  @param  [out] pui4_get_info_size - size of information
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_SUPPORT  - The stream type is not supported in this service
 *                             context object.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_stream_attr(
                    HANDLE_T                    h_svctx,
                    STREAM_TYPE_T               e_strm_type,
                    SM_GET_TYPE_T               e_get_type,
                    VOID*                       pv_get_info,            /* IN/OUT */
                    SIZE_T*                     pz_get_info_size        /* IN/OUT */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get audio information.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_resolution - References to the variable containing the
 *                          ASH_AUDIO_INFO_T.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_resolution is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_audio_info(
                    HANDLE_T                    h_svctx,
                    ASH_AUDIO_INFO_T*           pt_info
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get video source's resolution.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_resolution - References to the variable containing the
 *                          VSH_SRC_RESOLUTION_INFO_T.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_resolution is NULL
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_video_src_resolution(
                    HANDLE_T                        h_svctx,
                    VSH_SRC_RESOLUTION_INFO_T*      pt_resolution
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to unblock a blocked service (all streams are stopped).
 *              If b_force_unblock is TRUE, the blocked service will be unblocked
 *              and streams will be played. If b_force_unblock is FALSE, the client
 *              provided x_svctx_svc_block_check_fct function (if any) will be invoked
 *              again to check the service can be unblocked or not.
 *              If the service presented in the service context is not blocked,
 *              no action is performed.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  b_force_unblock - Contains the boolean to force unblock or not.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_ALREADY_STOPPED - The service conetxt is already stopped.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_unblock_svc(
                    HANDLE_T                        h_svctx,
                    BOOL                            b_force_unblock
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the default parameters for service context.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  ui4_stream_mode - Contains the default desired stream types.
 *  @param  [in]  e_vid_mode - Contains the default desired stream types.
 *  @param  [in]  b_able_set_pmx_bg - Specifiy to be able to set pmx bg.
 *  @param  [in]  pf_block_check_fct- Contains the block check fucntion pointer.
 *  @param  [in]  ps_src_grp_name - Contains the connection source name.
 *  @param  [in]  ps_snk_grp_name - Contains the sink group name.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_default_parameters(
                    HANDLE_T                    h_svctx,
                    UINT32                      ui4_stream_mode,
                    SCC_VID_MODE_T              e_vid_mode,
                    BOOL                        b_able_set_pmx_bg,
                    x_svctx_svc_block_check_fct pf_block_check_fct,
                    const CHAR*                 ps_src_grp_name,
                    const CHAR*                 ps_snk_grp_name,
                    const CHAR*                 ps_snk_grp_name_ext
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set stream's default filter function and tag.
 *              When select proper streams to play, if client doesn't provide
 *              filter funtion, this filter will be used.
 *              SCC_VID_MODE_T.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream component type for filtering.
 *  @param  [in]  pf_filter - References to the filter function provided by caller.
 *                             It can't be NULL.
 *  @param  [in]  pv_fltr_tag - References to a caller-defined tag. It will pass to
 *                             to caller when the pf_filter is invoked.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_INV_ARG - pt_filter_fct is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_default_strm_filter(
                    HANDLE_T                        h_svctx,
                    STREAM_TYPE_T                   e_strm_type,
                    x_svctx_strm_comp_filter_fct    pt_filter_fct,
                    VOID*                           pv_filter_tag
                    );

/*------------------------------------------------------------------*/
/*! @brief  his API is used to set screen mode.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_scr_mode - Contains the screen mode.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_screen_mode(
                    HANDLE_T                    h_svctx,
                    SCC_VID_SCREEN_MODE_T       e_scr_mode
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set screen mode.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pe_scr_mode - References to the variable containing the
 *                             SCC_VID_SCREEN_MODE_T.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pe_scr_mode is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_screen_mode(
                    HANDLE_T                    h_svctx,
                    SCC_VID_SCREEN_MODE_T*      pe_scr_mode
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get tuner's signal level.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pui1_signal_level - References to the variable containing signal 
 *                                                           level.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_signal_level(
                    HANDLE_T                    h_svctx,
                    UINT8*                      pui1_signal_level
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get tuner's DBM signal level.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pui1_signal_level - References to the variable containing signal 
 *                                                           level.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_dbm_signal_level(
                    HANDLE_T                    h_svctx,
                    INT16*                      pi2_dbm_signal_level
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get tuner's status.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pui1_tuner_status - References to the variable containing tuner's 
 *                             status.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pi2_dbm_signal_level is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_tuner_status(
                    HANDLE_T                    h_svctx,
                    UINT8*                      pui1_tuner_status
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get display's resolution.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_resolution - References to the variable containing the
 *                          SCC_DISP_RESOLUTION_T.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_resolution is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_display_resolution(
                    HANDLE_T                    h_svctx,
                    SCC_DISP_RESOLUTION_T*      pt_resolution
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set display's resolution.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_resolution - References to the variable containing the
 *                          SCC_DISP_RESOLUTION_T.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_resolution is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_display_resolution(
                    HANDLE_T                    h_svctx,
                    SCC_DISP_RESOLUTION_T*      pt_resolution
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to query it is signal loss or not.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pb_signal_loss - Contains the vairable for signal loss or not.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_is_signal_loss(
                    HANDLE_T                    h_svctx,
                    BOOL*                       pb_signal_loss
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get display's aspect ratio.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pe_aspect_ratio - References to the variable containing the
 *                          SCC_DISP_ASPECT_RATIO_T.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_resolution is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_display_aspect_ratio(
                    HANDLE_T                    h_svctx,
                    SCC_DISP_ASPECT_RATIO_T*    pe_aspect_ratio
                    );
/*------------------------------------------------------------------*/
/*! @brief  This API is used to set display's aspect ratio.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_aspect_ratio - Contains the value of SCC_DISP_ASPECT_RATIO_T
 *                                                      value.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_display_aspect_ratio(
                    HANDLE_T                    h_svctx,
                    SCC_DISP_ASPECT_RATIO_T     e_aspect_ratio
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the number of records for a specific
 *              stream type. Note: for closed caption, it only return the
 *              amount that detected in the caption_service_descriptor.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type value.
 *  @param  [out] pui2_num_recs - References to the variable containing the number of
 *                           records
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 *  @retval SVCTXR_WRONG_STATE - f related SCDB is not ready and opened.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_scdb_num_recs(
                    HANDLE_T                     h_svctx,            /* in  */
                    STREAM_TYPE_T                e_strm_type,        /* in  */
                    UINT16*                      pui2_num_recs       /* in  */
                    );
           
/*------------------------------------------------------------------*/
/*! @brief  This API retrieves the data of selected stream of a specific type from
 *              a presenting service context object.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream component type for filtering.
 *  @param  [out] pt_comp_id - References to the structure containing the
 *                             stream component id.
 *  @param  [out] pt_scdb_rec - References to the structure containing the
 *                             stream component data.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_scdb_rec is NULL.
 *  @retval SVCTXR_NOT_EXIST - The stream component is not existed.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 *  @retval SVCTXR_WRONG_STATE-  The operation is not permitted in current
 *                               scenaro.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_using_strm_data(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type,        /* in  */
                    STREAM_COMP_ID_T*               pt_comp_id,         /* out */
                    SCDB_REC_T*                     pt_scdb_rec         /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the listener for monitoring service
 *              context's activities.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out]  
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_listener(
                    HANDLE_T                        h_svctx,            /* in  */
                    x_svctx_listener_nfy_fct        pf_listener_fct,    /* in  */
                    VOID*                           pv_nfy_tag          /* in  */
                    );
/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the listener for monitoring service
 *              context's activities.
 *  @param  [out]  *pui2_idx - indicated the listener index , client can use it 
 *                                         to unregister the listener by x_svctx_unregister_generic_listener 
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_register_generic_listener(
                     x_svctx_generic_listener_nfy_fct pf_listener_fct,
                     VOID*                            pv_nfy_tag,
                     UINT16*                          pui2_idx
                     );
/*------------------------------------------------------------------*/
/*! @brief  This API is used to unregister the listener for monitoring service
 *              context's activities.
 *  @param  [out]  ui2_idx - indicated the listener index to unregister
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_unregister_generic_listener(
                     UINT16                          ui2_idx
                     );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the listener for monitoring service
 *              context's activities, without svctx semaphore lock.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out]  
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_listener_no_lock(
                    HANDLE_T                        h_svctx,            /* in  */
                    x_svctx_listener_nfy_fct        pf_listener_fct,    /* in  */
                    VOID*                           pv_nfy_tag          /* in  */
                    );
                    
/*------------------------------------------------------------------*/
/*! @brief  This API is used to surf service from current service. It only allows
 *              the client already invoking c_svctx_select_svc to obtain the control of
 *              the service context. This API will uses the latest cached service
 *              selection parameters (source information, sink information, notification
 *              callback fucntion, notification tag) to surf service.
 *
 *              Basically, it will find the target service list record based on current
 *              service record id cached in current service context objcet,
 *              e_surf_mode (SURF_MODE_THIS, SURF_MODE_NEXT, and SURF_MODE_PREV),
 *              and ui4_nw_chk_mask and ui4_nw_chk_value.
 *
 *              The possible tagret service list record's ui4_nw_mask will be used to
 *              decide it is target service list record or not. For example,
 *              ui4_nw_chk_mask  = 0x00000007
 *              ui4_nw_chk_value = 0x00000073
 *              The API will find the service list record's ui4_nw_mask & ui4_nw_chk_mask
 *              is equals to ui4_nw_chk_mask & ui4_nw_chk_value,
 *              i.e. the first  bit of service list record's ui4_nw_mask = 1
 *                   the second bit of service list record's ui4_nw_mask = 1
 *                   the third bit of service list record's ui4_nw_mask  = 0
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  ui4_nw_mask - Contains the target svl record's network check mask.
 *  @param  [in]  ui4_nw_value - Contains the target svl record's network value for
 *                             comparison.
 *  @param  [in]  e_surf_mode - Contains the variable for surf service direction.
 *  @param  [out] pt_svl_rec - References to the structure containing the
 *                             target svl record.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_nw_chk_mask = 0
 *  @retval SVCTXR_NO_RECORD - Cannot find any service list record to surf.
 *  @retval SVCTXR_NO_RESOURCE - No enough memory to allocate this request.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_surf_svc(
                    HANDLE_T                        h_svctx,            /* in  */
                    UINT32                          ui4_nw_chk_mask,    /* in  */
                    UINT32                          ui4_nw_chk_value,   /* in  */
                    SURF_MODE_T                     e_surf_mode,        /* in  */
                    SVL_REC_T*                      pt_svl_rec          /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to grab the ownership.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out]
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_grab_ownership(
                    HANDLE_T                        h_svctx             /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to release the ownership.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out]  
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - ui4_delay_in_ms is zero.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_release_ownership(
                    HANDLE_T                        h_svctx             /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get CP(Copy Protection) information for
 *              a specific stream. Normally, it is used when SVCTX_NTFY_CODE_CP
 *              is received.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type value.
 *  @param  [out] pt_cp_info - References to the variable containing the Copy
 *                          Protection information.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_cp_info is NULL.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_cp_info(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type,        /* in  */
                    CP_INFO_LIST_T*                 pt_cp_info          /* out  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get CA(Conditional Access) information
 *              for a specific stream. Normally, it is used when
 *              SVCTX_NTFY_CODE_CA is received.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_strm_type - Contains the stream type value.
 *  @param  [out] pt_ca_info - References to the variable containing the CA 
 *                                                information.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_ca_info is NULL.
 *  @retval SVCTXR_NOT_SUPPORT - The stream type is not supported in this service
 *                             context object.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_ca_info(
                    HANDLE_T                        h_svctx,            /* in  */
                    STREAM_TYPE_T                   e_strm_type,        /* in  */
                    SVCTX_CA_INFO_T*                pt_ca_info          /* out  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set the attribuites of a service context.
 *  @param  [in]  h_svctx - References to handle of a service context.
 *  @param  [in]  e_set_type - References to the type of attributes to set.
 *  @param  [in]  pv_set_info - References to the data information of the set type.
 *  @param  [in]  ui4_set_info_size - Contains the size of data information of the
 *                            set type.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set(
                    HANDLE_T                        h_svctx,            /* in  */
                    SVCTX_SET_TYPE_T                e_set_type,         /* in  */
                    VOID*                           pv_set_info,        /* in  */
                    SIZE_T                          z_set_info_size     /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get the attribuites of a service context.
 *  @param  [in]  h_svctx - References to handle of a service context.
 *  @param  [in]  e_set_type - References to the type of attributes to set.
 *  @param  [in]  pv_set_info - References to the data information of the set type.
 *  @param  [in]  ui4_set_info_size - Contains the size of data information of the
 *                            set type.
 *  @param  [out] pv_set_info - content of information.
 *  @param  [out] pv_set_info_size - size of information.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get(
                    HANDLE_T                        h_svctx,            /* in  */
                    SVCTX_GET_TYPE_T                e_get_type,         /* in  */
                    VOID*                           pv_get_info,        /* in/out */
                    SIZE_T*                         pz_get_info_size    /* in/out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to freeze svctx. The minimum frozen stream
 *              is video stream. If ui4_freeze_strm_mask doesn't include
 *              ST_MASK_VIDEO, this API will add video stream to freeze 
 *              automatically.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  ui4_freeze_strm_mask - Contains the mask to indicate which streams
 *                                 will be frozen.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_freeze(
                    HANDLE_T                        h_svctx,             /* in  */
                    UINT32                          ui4_freeze_strm_mask /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to unfreeze svctx.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_unfreeze(
                    HANDLE_T                        h_svctx             /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to check svctx is frozen or not.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pb_result - Contains a flag for the result.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG - pb_result is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_is_frozen(
                    HANDLE_T                        h_svctx,            /* in  */
                    BOOL*                           pb_result           /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get current event info's length.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_key_type - Event key type.
 *  @param  [in]  pv_key_info - Event key infor.
 *  @param  [out] pz_event_info_len - size of event info.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_current_event_info_len (
                    HANDLE_T                        h_svctx,            /* in  */
                    EVCTX_KEY_TYPE_T                e_key_type,         /* in  */
                    VOID*                           pv_key_info,        /* in  */
                    SIZE_T*                         pz_event_info_len   /* out */
                    );
/*------------------------------------------------------------------*/
/*! @brief  This API is used to get current event info.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_key_type - Event key type.
 *  @param  [in]  pv_key_info - Event key infor.
 *  @param  [out] pz_event_info_len - size of event info.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_current_event_info (
                    HANDLE_T                        h_svctx,            /* in  */
                    EVCTX_KEY_TYPE_T                e_key_type,         /* in  */
                    VOID*                           pv_key_info,        /* in  */
                    SIZE_T*                         pz_event_info_len,  /* out */
                    VOID*                           pv_event_info       /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get device profile record.
 *  @param  [in]  e_dev_type - device type.
 *  @param  [out] pt_profile - device content.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG - pt_profile is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_device_profile(                           
                    DEVICE_TYPE_T                   e_dev_type,         /* in  */
                    DEVICE_TYPE_PROFILE_T*          pt_profile          /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get well-defined video height.
 *  @param  [in]  ui4_raw_height - Contains the raw video height, e.g. 1088
 *  @param  [out] pui4_defined_height - Contains the well-defined video height. e.g. 1080
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pui4_defined_height is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_well_defined_video_heigh(
                    UINT32                          ui4_raw_height,
                    UINT32*                         pui4_defined_height
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get cc capability of a svctx.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_capablility - Contains the cc capable condition.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pt_capablility is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_cc_capability(
                    HANDLE_T                    h_svctx,
                    SVCTX_CAPABILITY_T*         pt_capablility
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get subtile capability of a svctx.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_capablility - Contains the subtile capable condition.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pt_capablility is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_subtitle_capability(
                    HANDLE_T                    h_svctx,
                    SVCTX_CAPABILITY_T*         pt_capablility
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get ttx capability of a svctx.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_capablility - Contains the ttx capable condition.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pt_capablility is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_teletext_capability(
                    HANDLE_T                    h_svctx,
                    SVCTX_CAPABILITY_T*         pt_capablility
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get event capability of a svctx.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out] pt_capablility - Contains the event capable condition.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_INV_ARG - pt_capablility is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_event_capability(
                    HANDLE_T                    h_svctx,
                    UINT32                      ui4_event_key_mask,
                    SVCTX_CAPABILITY_T*         pt_capablility
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API returns a handle to the SCDB object for a specified svctx.
 *             Basically, it is a help function to let caller to handle
 *             the SCDB by itself, but the return value is SVCTXR_XXX
 *              not SMR_XXX.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Additional info for specifing pipe. it could be ST_VIDEO,
 *                         ST_AUDIO, or ST_UNKNOWN.
 *  @param  [in]  pv_tag - Private tag value associated with the calling client.
 *  @param  [in]  pf_nfy - Client notification function.
 *  @param  [out] ph_scdb - pointer to a SCDB handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - (SCDBR_INV_ARG)          ph_scdb is NULL.
 *  @retval SVCTXR_NO_RESOURCE - (SCDBR_OUT_OF_HANDLE)    No more handle available,
 *                              (SCDBR_OUT_OF_MEM)       or Out of memory.
 *  @retval SVCTXR_WRONG_STATE - connection is not available to create SCDB.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_open_scdb(
                    HANDLE_T                        h_svctx,
                    STREAM_TYPE_T                   e_pipe_type,
                    HANDLE_T*                       ph_scdb,
                    VOID*                           pv_tag,
                    x_scdb_nfy_fct                  pf_nfy
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API frees the specified handle to the SCDB database.
 *              Basically, it is a help function to let caller to handle
 *              the SCDB by itself, but the return value is SVCTXR_XXX
 *              not SMR_XXX.
 *  @param  [in]  h_scdb - handle to be freed.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_close_scdb(
                    HANDLE_T                        h_scdb
                    );

/*------------------------------------------------------------------*/
/*! @brief  This function is used to open a stream in a specific svctx.
 *              Basically, it is a help function to let caller to handle
 *              the stream by itself, but the return value  is SVCTXR_XXX
 *              not SMR_XXX.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Additional info for specifing pipe. it could be ST_VIDEO,
 *                          ST_AUDIO, or ST_UNKNOWN.
 *  @param  [in]  pt_strm_comp_id - References to the component ID aquired from SCDB.
 *  @param  [in]  pt_cmd - References to the command sets to initialize the stream.
 *  @param  [in]  pf_strm_nfy - References to a stream event callback function,
 *                          which is implemented by the caller.
 *  @param  [in]  pv_strm_nfy_tag - References to a tag to be pass to the stream event
 *                          callback function.
 *  @param  [in]  b_auto_play - Indicate if the stream sould play automatically.
 *  @param  [out] ph_stream - References to the stream handle created by Stream
 *                                                Manager.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - (SMR_INV_ARG)        The argument ph_stream, 
 *                                                  pf_strm_nfy,or pt_strm_comp_id is invalid.
 *  @retval SVCTXR_NOT_SUPPORT - (SMR_NOT_SUPPORT)    There is no stream handler 
 *                                                  that support this type of stream.
 *  @retval SVCTXR_WRONG_STATE - session is not available.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_open_stream(
                    HANDLE_T                        h_svctx,
                    STREAM_TYPE_T                   e_pipe_type,
                    const STREAM_COMP_ID_T*         pt_strm_comp_id,
                    const SM_COMMAND_T*             pt_cmd_sets,
                    x_stream_nfy_fct                pf_strm_nfy,
                    VOID*                           pv_strm_nfy_tag,
                    BOOL                            b_auto_play,
                    HANDLE_T*                       ph_stream
                    );

/*------------------------------------------------------------------*/
/*! @brief  This function is used to open a stream in a specific svctx.
 *              Basically, it is a help function to let caller to handle
 *              the stream by itself, but the return value  is SVCTXR_XXX
 *              not SMR_XXX.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Additional info for specifing pipe. it could be ST_VIDEO,
 *                          ST_AUDIO, or ST_UNKNOWN.
 *  @param  [in]  pt_strm_comp_id - References to the component ID aquired from SCDB.
 *  @param  [in]  pt_cmd - References to the command sets to initialize the stream.
 *  @param  [in]  pf_strm_nfy - References to a stream event callback function,
 *                          which is implemented by the caller.
 *  @param  [in]  pv_strm_nfy_tag - References to a tag to be pass to the stream event
 *                          callback function.
 *  @param  [in]  b_auto_play - Indicate if the stream sould play automatically.
 *  @param  [out] ph_stream - References to the stream handle created by Stream
 *                                                Manager.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - (SMR_INV_ARG)        The argument ph_stream, 
 *                                                  pf_strm_nfy,or pt_strm_comp_id is invalid.
 *  @retval SVCTXR_NOT_SUPPORT - (SMR_NOT_SUPPORT)    There is no stream handler 
 *                                                  that support this type of stream.
 *  @retval SVCTXR_WRONG_STATE - session is not available.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_open_stream_ex(
                    HANDLE_T                        h_svctx,
                    STREAM_TYPE_T                   e_pipe_type,
                    const STREAM_COMP_ID_T*         pt_strm_comp_id,
                    const SM_COMMAND_T*             pt_cmd_sets,
                    x_stream_nfy_fct                pf_strm_nfy,
                    VOID*                           pv_strm_nfy_tag,
                    BOOL                            b_auto_play,
                    UINT32                          ui4_serial_num,
                    HANDLE_T*                       ph_stream
                    );

/*------------------------------------------------------------------*/
/*! @brief  This function is used to close a stream of Stream Manager.
 *              Basically, it is a help function to let caller to handle
 *              the stream by itself, but the return value  is SVCTXR_XXX
 *              not SMR_XXX.
 *  @param  [in]  h_stream - References to the handle of the stream.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_close_stream(
                    HANDLE_T                        h_stream
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API gets information about a connection.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Additional info for specifing pipe. it could be ST_VIDEO,
 *                         ST_AUDIO, or ST_UNKNOWN.
 *  @param  [in]  e_ctrl - Contains the control code, and it is defined in CM's header file.
 *  @param  [out] pv_ctrl_data - Contains information about the connection.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NO_RESOURCE - No more handle available,
 *                               or Out of memory.
 *  @retval SVCTXR_WRONG_STATE - connection is not available.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_conn_attr(
                    HANDLE_T                        h_svctx,
                    STREAM_TYPE_T                   e_pipe_type,
                    CM_CTRL_TYPE_T                  e_ctrl,
                    VOID*                           pv_ctrl_data
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API sets some attributes of a connection.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_pipe_type - Additional info for specifing pipe. it could be ST_VIDEO,
 *                         ST_AUDIO, or ST_UNKNOWN
 *  @param  [in]  e_ctrl - Contains the control code, and it is defined in CM's header file.
 *  @param  [in]  pv_ctrl_data - References a data structure which content depends on
 *                         e_ctrl.
 *  @param  [out] pv_ctrl_data - Contains values that may have been modified.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_NO_RESOURCE - No more handle available,
 *                               or Out of memory.
 *  @retval SVCTXR_WRONG_STATE - connection is not available.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_conn_attr(
                    HANDLE_T                        h_svctx,
                    STREAM_TYPE_T                   e_pipe_type,
                    CM_CTRL_TYPE_T                  e_ctrl,
                    VOID*                           pv_ctrl_data
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API sets analog tuner out attributes.
 *  @param  [in]  pt_tuner_out - References a data structure which content tuner out
 *                         parameters.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_analog_tuner_out_attr(
                    TUNER_OUT_DESC_T*               pt_tuner_out
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to perfrom service block check, however, this
 *      API is just a check, it doesn't perfrom anu service block/unblock
 *      operation.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_check_guide - Contains the block check guide.
 *  @param  [in]  ps_src_name - Contains the source group name.
 *  @param  [in]  pt_svl_rec - Contains the SVL record if source is TV.
 *  @param  [in]  pv_evn_rating -  Contains the event's rating buffer obtained from EVctx.
 *  @return return block value
 *  @retval SVC_BLOCK_COND_T - the check result.
 */
/*------------------------------------------------------------------*/
extern SVC_BLOCK_COND_T c_svctx_svc_block_check(
                    HANDLE_T                        h_svctx,
                    SVC_BLOCK_CHECK_GUDIE_T         e_check_guide, 
                    const CHAR*                     ps_src_name,   
                    const SVL_REC_T*                pt_svl_rec,  
                    const VOID*                     pv_evn_rating
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set aux audio enable or not
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  b_enable - Contains set value.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_ad_state(
                    HANDLE_T                        h_svctx,          /* in  */
                    BOOL                            b_enable          /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API tries to open an ad stream specified by *pt_scdb_rec.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_scdb_rec - References to the structure containing the
 *                               scdb data of the ad stream.
 *  @return return the error code
 *  @retval SVCTXR_OK         -  Routine successful.
 *  @retval SVCTXR_INV_ARG    -  pt_scdb_rec is NULL.
 *  @retval SVCTXR_NOT_SUPPORT-  The stream type is not supported in this service
 *                       context object.
 *  @retval SVCTXR_NOT_EXIST  -  The stream component is not existed.
 *  @retval SVCTXR_NOT_INIT   -  The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE -  Invalid service context handle.
 *  @retval SVCTXR_FAIL       -  SCDB error, can not get the record
 *  @retval SVCTXR_WRONG_STATE-  The operation is not permitted in current
 *                               scenaro.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_set_ad_state_ex(
                    HANDLE_T                        h_svctx,          /* in  */
                    const SCDB_REC_T*               pt_scdb_rec       /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get aux audio enable or not
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out]  pb_enable - Contains return value.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_ad_state(
                    HANDLE_T                        h_svctx,          /* in  */
                    BOOL*                           pb_enable         /* out */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API tries to set audio type.
 *  @Note: This API is advised not to used with x_svctx_set_ad_state and x_svctx_set_ad_state_ex.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  t_audio_type - References to the enum definition SVCTX_AUDIO_TYPE_T.
 *  @return return the error code
 *  @retval SVCTXR_OK          Routine successful.
 *  @retval SVCTXR_INV_ARG     pt_scdb_rec is NULL or the ui2_num_recs is zero.
 *  @retval SVCTXR_NOT_SUPPORT The stream type is not supported in this service context object.
 *  @retval SVCTXR_NOT_EXIST   The stream component is not existed.
 *  @retval SVCTXR_NOT_INIT    The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE  Invalid service context handle.
 *  @retval SVCTXR_FAIL        SCDB error, can not get the record
 *  @retval SVCTXR_NOT_SUPPORT The operation is not supported in current scenaro.
 *-----------------------------------------------------------------------------*/
extern INT32 c_svctx_set_audio_type(
                    HANDLE_T                        h_svctx,          /* in  */
                    SVCTX_AUDIO_TYPE_T              t_audio_type      /* in  */
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get audio type.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [out]  pt_audio_type - Contains return value.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_get_audio_type(
                    HANDLE_T                        h_svctx,          /* in  */
                    SVCTX_AUDIO_TYPE_T*             pt_audio_type     /* out */
                    );

#ifdef ENABLE_MULTIMEDIA        
/*------------------------------------------------------------------*/
/*! @brief  This API is used to perfrom media file open function 
 *      it would scan media content to check the content correctness
 *      and generate the service list for AP further service selection. 
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pt_cmd - Commands list should include src_type , svl_name,svl_id and
 *               media_path
 *  @param  [in]  pf_nfy - Callback function when open finished.
 *  @param  [in]  pv_tag - Tag.
 *  @param  [out]  ph_media - Contains return media handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Media open fail.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_media_open(
                    HANDLE_T                        h_svctx,
                    MM_SVC_COMMAND_T*               pt_cmd,
                    x_svctx_media_prc_nfy_fct       pf_nfy,
                    VOID*                           pv_tag,
                    HANDLE_T*                       ph_media                      
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to perfrom media file or clip close function.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_svctx - Contains a handle to a media.
 *  @param  [out] 
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Send request failed.
 */
/*------------------------------------------------------------------*/
 extern INT32 c_svctx_media_close(
                    HANDLE_T                        h_svctx,
                    HANDLE_T                        h_media
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to perfrom media search function.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  pf_nfy - Callback function when open finished.
 *  @param  [in]  pv_tag - Tag.
 *  @param  [in]  pt_pos_info - Position to be seeked to.
 *  @param  [out] 
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_media_seek(
                    HANDLE_T                        h_svctx,
                    x_svctx_select_nfy_fct          pf_nfy,
                    VOID*                           pv_tag,
                    MM_SVC_POS_INFO_T*              pt_pos_info
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to load video thumbnail.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_media - Contains media handle.
 *  @param  [in]  pt_thumbnail_info - Contains the thumbnail information.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_media_load_thumbnail(
                    HANDLE_T                        h_svctx,
                    HANDLE_T                        h_media,
                    SVCTX_VIDEO_THUMBNAIL_INFO_T*   pt_thumbnail_info
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to sync cancel the loading of video thumbnail.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_media - Contains media handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_media_sync_cancel_load_thumbnail(
                    HANDLE_T                        h_svctx,
                    HANDLE_T                        h_media
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get media information.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_media - Contains media handle.
 *  @param  [in]  t_svctx_get_type - Get type.
 *  @param  [in]  z_get_info_size - Return value size.
 *  @param  [out]  pv_get_info - Return value to be stored.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
INT32 c_svctx_media_get_info(
    HANDLE_T h_svctx,                  
    HANDLE_T h_media,
    SVCTX_GET_TYPE_T t_svctx_get_type,
    VOID* pv_get_info,
    SIZE_T z_get_info_size);

/*------------------------------------------------------------------*/
/*! @brief  This API is used to get media information.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_media - Contains media handle.
 *  @param  [in]  t_svctx_set_type - Set type.
 *  @param  [in]  z_set_info_size - Set value size.
 *  @param  [in]  pv_set_info - Value to be set.
 *  @note   
 *  @see    
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
INT32 c_svctx_media_set_info(
                             HANDLE_T           h_svctx,                  
                             HANDLE_T           h_media,
                             SVCTX_SET_TYPE_T   t_svctx_set_type,
                             VOID*              pv_set_info,
                             SIZE_T             z_set_info_size);
/*------------------------------------------------------------------*/
/*! @brief  This API is used to get generic media information. It doesn't need to open media first.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_media - Contains media handle.
 *  @param  [in]  t_svctx_get_type - Get type.
 *  @param  [in]  z_get_info_size - The size of the buffer to store return value.
 *  @param  [out]  pv_get_info - Return value to be stored.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
INT32 c_svctx_generic_get_info(
    HANDLE_T h_svctx,                  
    HANDLE_T h_media,
    SVCTX_GET_TYPE_T t_svctx_get_type,
    VOID* pv_get_info,
    SIZE_T z_get_info_size);

/*------------------------------------------------------------------*/
/*! @brief  This API is used to set generic media information. It doesn't need to open media first.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_media - Contains media handle.
 *  @param  [in]  t_svctx_get_type - Get value type.
 *  @param  [in]  pv_get_info - Return value to be stored.
 *  @param  [in]  z_get_info_size - The size of the buffer to store return value.
 *  @param  [out] pv_get_info - Return value.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Routine failed.
 */
/*------------------------------------------------------------------*/
INT32 c_svctx_generic_set_info(
    HANDLE_T h_svctx,                  
    HANDLE_T h_media,
    SVCTX_SET_TYPE_T t_svctx_set_type,
    VOID* pv_set_info,
    SIZE_T z_set_info_size);
#endif

/*------------------------------------------------------------------*/
/*! @brief  This API is used to create association instance for a svctx instance.
 *  @param  [in]  ps_name - Svctx instance name.
 *  @param  [in]  pt_assc_cfg - Association Configuration.
 *  @param  [out]  ph_svctx - Return a association instance.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_NO_RESOURCE - No more handle available,
 *                               or Out of memory.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_create_associate(
                    const CHAR*                     ps_name,
                    const SVCTX_ASSC_CFG_T*         pt_assc_cfg,
                    HANDLE_T*                       ph_svctx);


/*------------------------------------------------------------------*/
/*! @brief  This API is used to add association instance for a svctx instance.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_svctx_excl - Contains a exclustion handle to a service context.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - Svctx don't init.
 *  @retval SVCTXR_INV_ARG - ui4_excl_src_mask == 0.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_add_associate(
                    HANDLE_T                        h_svctx,
                    HANDLE_T                        h_svctx_assc);

/*------------------------------------------------------------------*/
/*! @brief  This API is used to add exclustion instance for a svctx instance.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  h_svctx_excl - Contains a exclustion handle to a service context.
 *  @param  [in]  ui4_excl_src_mask - Mask for exclustion source. 
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - Svctx don't init.
 *  @retval SVCTXR_INV_ARG - ui4_excl_src_mask == 0.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_add_exclusion(
                    HANDLE_T                        h_svctx,
                    HANDLE_T                        h_svctx_excl,
                    UINT32                          ui4_excl_src_mask);

/*------------------------------------------------------------------*/
/*! @brief  This API is used to enter pip/pop status.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_src_type - SRC_TYPE_BRDCST_SVL, SRC_TYPE_BRDCST_FREQ.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - Svctx don't init.
 *  @retval SVCTXR_NO_RIGHT - Handle isn't owner.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_start_exclusion(
                    HANDLE_T                        h_svctx,
                    SRC_TYPE_T                      e_src_type);

/*------------------------------------------------------------------*/
/*! @brief  This API is used to exit pip/pop status.
 *  @param  [in]  h_svctx - Contains a handle to a service context.
 *  @param  [in]  e_src_type - SRC_TYPE_BRDCST_SVL, SRC_TYPE_BRDCST_FREQ.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - Svctx don't init.
 *  @retval SVCTXR_NO_RIGHT - Handle isn't owner.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_stop_exclusion(
                    HANDLE_T                        h_svctx,
                    SRC_TYPE_T                      e_src_type);

#if (defined(SYS_RECORD_SUPPORT) || defined(MW_AV_RECORD_SUPPORT))
/*------------------------------------------------------------------*/
/*! @brief  This API creates a Recrod SVCTX.
 *  @param  [in]  ps_svctx_name - Specifies the service context name for the create.
 *                         The name must be unique to other SVCTX.
 *  @param  [in]  pt_rec_attr - Contains the attributes for Record SVCTX.
 *  @param  [out] ph_svctx_rec - Contains the Record SVCTX handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_FAIL - Send request failed.
 *  @retval SVCTXR_INV_ARG - pt_rec_attr is NULL.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory to open the service context.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_rec_create (
                    const CHAR*                     ps_svctx_name,    
                    const SVCTX_REC_ATTR_T*         pt_rec_attr,      
                    HANDLE_T*                       ph_svctx_rec);    

/*------------------------------------------------------------------*/
/*! @brief  This API starts the recording session.
 *  @param  [in]  h_svctx_rec - Specifies the Record SVCTX handle.
 *  @param  [in]  pt_config - Contains the config for recording.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_INV_ARG - pt_config is NULL.
 *  @retval SVCTXR_WRONG_STATE - Invalid service context state to start recording.
 *  @retval SVCTXR_NO_RESOURCE - Not enough memory / resource.
 *          < 0                 Other errors. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_rec_start (
                    HANDLE_T                        h_svctx_rec, 
                    const SVCTX_REC_CONFIG_T*       pt_config    
                    );

/*------------------------------------------------------------------*/
/*! @brief  This API stops the recording session. 
 *  @param  [in]  h_svctx_rec - Specifies the Record SVCTX handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_WRONG_STATE - Invalid service context state to stop recording.
 *          < 0                 Other errors. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_rec_stop (
                    HANDLE_T                        h_svctx_rec  
                    );               

/*------------------------------------------------------------------*/
/*! @brief  This API pauses the recording session.
 *  @param  [in]  h_svctx_rec - Specifies the Record SVCTX handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_WRONG_STATE - Invalid service context state to pause recording.
 *          < 0                 Other errors. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_rec_pause (
                    HANDLE_T                        h_svctx_rec  
                    );               

/*------------------------------------------------------------------*/
/*! @brief  This API resumes the recording session.
 *  @param  [in]  h_svctx_rec - Specifies the Record SVCTX handle.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_HANDLE - Invalid service context handle.
 *  @retval SVCTXR_WRONG_STATE - Invalid service context state to pause recording.
 *          < 0                 Other errors.
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_rec_resume (
                    HANDLE_T                        h_svctx_rec  
                    );               

#endif

/*------------------------------------------------------------------*/
/*! @brief  This API to register the pre-select stream.
 *  @param  [in]  pf_pre_select_stream_fct - Specifies pre-select stream function.
 *  @return return the error code
 *  @retval SVCTXR_OK - Routine successful.
 *  @retval SVCTXR_NOT_INIT - The Service Context Module is not initialized yet.
 *  @retval SVCTXR_INV_ARG  - pf_pre_select_stream_fct is NULL.
 
 */
/*------------------------------------------------------------------*/
extern INT32 c_svctx_reg_pre_select_stream_cb(
                   x_svctx_pre_select_stream_nfy_fct pf_pre_select_stream_fct /* in*/
                   );
extern VOID c_svctx_prepare_process_env(
                   BOOL *pb_same_process
                   );

/*----------------------------------------------------------------------------*/
/*! @} */                                           /* end of groupMW_SVCTX */
/*----------------------------------------------------------------------------*/

/*!@page pageMW_MM_HDLR Mluti Media Handlr Detailed Description
 *  @par
 *  @section secMW_MM_HDLR_1  1. Introduction
 *      In order to provide the multi media(both vedio and audio) playback operations, such as .rm format playback. Multi media handler provide a uniform interface to operate middleware, by this, multi media handler could have a simple way to monitor playback status and control all playback flow.
 *      Multi media handler  can validate media content correctness and extract media information(parse media info,for example) via medai utility, it also use middleware module CM/SM to playback audio and video and subtitle.When the media playback,it supports media seek operation(set attributies like fast-forward,for example) and media trick playback,also allow client to get media information(get duration, for example).
 *  @par 
 *  @section secMW_MM_HDLR_2  2. Concept
 *      The multi media handler will use utility to confirm media format, parse media information, create a key index table. Then select the relevent media handler to playback. When playback,user can get media information and do some operations(close media, fast forward,for example).
 *  @par
 *  @section secMW_MM_HDLR_3  3. Brief Design
 *  @subsection ssecMW_MM_HDLR_3_1  3.1. Selector
 *      The selector will select corresponding handler to achieve the media operation according to the media foramt. 
 *  @par
 *  @subsection ssecMW_MM_HDLR_3_2  3.2. User operation
 *      User can do some operations like media playback, close media, get media information,etc.
 *  @par
 *  @section secMW_MM_HDLR_4  4. Typical Case
 *  @subsection ssecMW_MM_HDLR_4_1  4.1. media open 
 *	To open a video or audio media, the c_svctx_media_open function will be called, it will confirm media format and get media information.
 *  @par	
 *  	static INT32 _nav_rec_tshift_media file_open(VOID) 
 *	{
 *  @par
 *    MM_SVC_COMMAND_T		t_mm_cmd[2];
 *  @par
 *    INT32	i4_ret;
 *  @par
 *    t_mm_cmd[0].e_code = MM_SVC_CMD_CODE_SRC_TYPE
 *    t_mm_cmd[0].u.ui1_data  = SRC_TYPE_MEDIA_TIME_SHIFT;
 *    t_mm_cmd[1].e_code      = MM_SVC_CMD_CODE_END;
 *  @par
 *	//h_svctx is the media pointer.
 *  @par
 *    i4_ret = c_svctx_media_open(h_svctx,
 *						t_mm_cmd,
 *						_nav_rec_tshift_media_open_nfy,
 *						NULL,
 *						h_media_tshift)
 *  @par
 *    if (i4_ret != SVCTX_OK) 
 * 	{
 *  @par
 *     return NAVR_FAIL;
 *    }
 *    }
 *  @subsection ssecMW_MM_HDLR_4_2  4.2. media close
 *	If user want to stop the media, c_svctx_media_close will be called, it will stop the current media.
 *  @par
 *     static INT32 _nav_rec_tshift_media_file_close(VOID)
 *    {
 *  @par
 *	INT32	i4_ret;
 *  @par
 *     if(h_media_tshift == NULL)
 *	{
 *  @par
 *     return NAVR_OK;
 *	}
 *  @par
 *     i4_ret = c_svctx_media_close(h_svctx,
 *                               h_media_tshift);
 *  @par
 *	if(i4_ret != SVCTXR_OK)
 *	{
 *  @par
 *	return NAVR_FAIL;
 *	}
 *	}
 *  @subsection ssecMW_MM_HDLR_4_3  4.3. media play
 *	If user want to play media, c_svctx_select_svc will be called, Selector will selects a service to be presented in this service context instance in asynchronous way. If the instance is already presenting content, the new selection request will replace the previous request being presented. If the instance is not presenting, successful conclusion of this operation results in the instance entering the presenting state. Successful completion of the selection is notified via pf_nfy with e_nfy_cond = SVCTX_COND_PRESENTING, e_code = SVCTX_NTFY_CODE_NORMAL 
 *  @par
 *	INT32 _video_engine_start2play(
 *					_MMP_VE_PLAY_INST_PTR_T		pt_this,
 *					MMP_VE_DIVX_CERT_PTR_T		ui4_time_ofs
 *					)
 *    {
 *  @par
 *	SRC_DESC_T					t_src_desc = {0};
 *  @par
 *     SNK_DESC_T					t_snk_desc = {0};
 *  @par
 *     UINT32						ui4_stream_mode = ST_MASK_AUDIO;
 *  @par
 *     INT32						i4_ret = 0;
 *  @par
 *     _MMP_VE_ELMT_INFO_PTR_T	pt_elmt = _MMP_VE_GET_1ST_ELMT(pt_this);
 *  @par
 *	if (_MMP_VE_ELMT_TYPE_VIDEO == pt_elmt->e_elmt_type)
 *	{
 *  @par
 *	ui4_stream_mode |= ST_MASK_VIDEO;
 	}
 *  @par	
 *	t_src_desc.e_type = SRC_TYPE_MEDIA_STORGE;
 *  @par
 *	t_src_desc.u_info.t_mm = t_mm;
 *  @par
 *	t_snk_desc.pt_video_region        = &t_vide_rgn;
 *  @par	
 *	t_snk_desc.pt_disp_region         = &t_disp_rgn;
 *  @par
 *	t_snk_desc.pt_video_plane_order   = &t_vpla_ord;
 *  @par
 *	t_snk_desc.pt_video_strm_fltr_fct = _video_engine_strm_comp_filter;  
 *  @par
 *	t_snk_desc.pv_video_strm_fltr_tag = NULL;
 *  @par
 *	t_snk_desc.pt_audio_strm_fltr_fct = _video_engine_strm_comp_filter;
 *  @par	
 *	t_snk_desc.pv_audio_strm_fltr_tag = NULL;
 *  @par
 *	t_snk_desc.ps_snk_grp_name        = SN_PRES_MAIN_DISPLAY;
 *  @par
 *	if (NULL_HANDLE != pt_this->t_osd_info.h_sub_plane)
 *   	{
 *  @par
 *    t_snk_desc.u_text_strm.t_subtitle.h_gl_plane = pt_this->t_osd_info.h_sub_plane;
 *   	}
 *  @par
 *    	else
 *  	{
 *  @par
 *    t_snk_desc.u_text_strm.t_subtitle.h_gl_plane = pt_this->t_osd_info.h_canvas_ex;
 *   	}
 *  @par
 *    	i4_ret = c_svctx_select_svc(
 *                	pt_this->h_svctx_hdl,
 *                  ui4_stream_mode,
 *                  &t_src_desc,
 *                  &t_snk_desc,
 *                  _svctx_media_play_nfy_fct,
 *                  (VOID*)pt_this
 *                  );
 *   @par
 *   	if (SVCTXR_OK != i4_ret)
 *    {
 *   @par
 *    return MMPR_FAIL;
 *    }
 *   @par
 *    pt_elmt->e_elmt_stat = _MMP_VE_ELMT_STAT_PLAY;
 *   @par
 *    return MMPR_OK;
 *	}
 *  @subsection ssecMW_MM_HDLR_4_4  4.4. media set
 *	This function will called when user set the attribuites of a service context. it contains pause, fast-forward, rewind, seek by timecode, repeat between A-B points.
 *	When users want to pause fast-forward and rewind, they all set speed to driver; when user wants to seek by timecode, the function will set trick play; when user wants to repeat from A to B, they need to set A and B position,then the media will repeat playback between A-B points.
 *  @par
 *  	static INT32 _video_engine_set_trick(
 *					_MMP_VE_PLAY_INST_PTR_T         pt_this, 
 *					MM_SPEED_TYPE_T                 e_spd_type 
 * 					)
 *	{
 *  @par
 *	//e_spd_type are the speed of media, pause fast-forword rewind, for example.
 *  @par
 *	MM_SPEED_TYPE_T e_spd_type = MM_SPEED_TYPE_PAUSE;
 *  @par
 *	MM_SVC_TRICK_INFO_T t_trick = {e_spd_type};
 *  @par
 *    	i4_ret = c_svctx_set(
 *                	pt_this->h_svctx_hdl,
 *                  SVCTX_MM_SET_TYPE_TRICK,
 *                  (VOID*)&t_trick,
 *                  sizeof(MM_SVC_TRICK_INFO_T)
 *                  );
 *   @par
 *   	if (SVCTXR_OK != i4_ret)
 *    {
 *   @par
 *    return MMPR_FAIL;
 *    }
 *   @par
 *    return i4_ret;
 *	}
 *  @subsection ssecMW_MM_HDLR_4_5  4.5. media get
 *	This function will called when user get the attribuites of a service context. it contains duration, timecode, file size and position, DRAM information, meta data.
 *  @par
 *	INT32 video_engine_get_duration(
 *					MMP_VE_PLAY_INST_PTR_T          pt_play_inst,
 *					MMP_VE_DUR_TYPE_T               t_dur_type,  
 *					UINT64*                         pui8_dur_val   
 * 					)
 *	{
 *  @par
 *	MM_SVC_DUR_INFO_T					t_dur;
 *  @par
 *	UINT32								i4_ret = 0;
 *  @par
 *	if(MMP_VE_DUR_TYPE_TIME == t_dur_type)
 *	{
 *  @par
 *	if(MMP_VE_DUR_TYPE_TIME == t_dur_type)
 *	}
 *  @par
 *	else
 *	{
 *  @par
 *	t_dur.t_dur_type = MM_SVC_DUR_TYPE_ALL_OFFSET;
 *	}
 *  @par
 * 	t_dur.ui2_idx = (UINT16)0;
 *  @par
 *    	i4_ret = c_svctx_get(
 *                	pt_this->h_svctx_hdl,
 *                  SVCTX_MM_GET_TYPE_DUR,
 *                  (VOID*)&t_dur,
 *                  sizeof(MM_SVC_DUR_INFO_T)
 *                  );
 *   @par
 *   	if (SVCTXR_OK != i4_ret)
 *    {
 *   @par
 *    return MMPR_FAIL;
 *    }
 *   @par
 *    return i4_ret;
 *	}
 *  @subsection ssecMW_MM_HDLR_4_6  4.6. media load thumbnail
 *     static INT32 _mmp_ve_info_thumb_load(
 *					_MMP_VE_PLAY_INST_PTR_T					pt_this,
 *					_MMP_VE_INFO_INST_PTR_T					pt_this_obj,
 *					MMP_FP_INFO_CMD_PARAM_LOAD_THUMB_T*	pt_param
 *					)
 *    {
 *  @par
 *	GL_RECT_T						t_bound_rect;
 *  @par
 *     GL_RECT_T						t_thumb_rect;
 *  @par
 *     SVCTX_VIDEO_THUMBNAIL_INFO_T	t_thumb_info;
 *  @par
 *     UINT32							ui4_crnt_load_ver = VIDEO_ENGINE_LOAD_VER_INVALID;
 *  @par
 *     UINT32							i4_ret;
 *  @par
 *	if (_MMP_VE_ELMT_STAT_INIT == pt_this_obj->e_elmt_stat)
 *	{
 *  @par
 *	if(NULL == pt_param->pt_rect || WGL_RECT_IS_EMPTY(pt_param->pt_rect))
 *	{
 *  @par	
 *	return MMPR_INV_ARG;
 *	}
 *  @par
 *	t_bound_rect = *pt_param->pt_rect;
 *  @par
 *	mmp_drc_convert_rect_coord(pt_param->e_coords, &t_bound_rect);
 *  @par	
 *	pt_this_obj->t_bound_rect = t_bound_rect;
 *  @par
 *	pt_this_obj->e_elmt_stat = _MMP_VE_ELMT_STAT_WAIT;
 *  @par
 *     return MMPR_OK;
 *    	}
 *  @par
 *	else if (_MMP_VE_ELMT_STAT_READY != pt_this_obj->e_elmt_stat)
 *	{
 *  @par
 *	return MMPR_OK;
 *	}
 *  @par	
 *	if (VIDEO_ENGINE_INFO_FLAG_LOADING & pt_this_obj->ui1_flag)
 *	{
 *  @par
 *	return MMPR_RES_NOT_READY;
 *	}
 *  @par
 *	if(VIDEO_ENGINE_INFO_FLAG_LOADING & pt_this_obj->ui1_flag)
 *  	{
 *  @par
 *	return MMPR_OK;
 *	}
 *  @par
 *     i4_ret = _mmp_ve_info_thumb_lock_buf(pt_this, TRUE);
 *  @par
 *	if (i4_ret != MMPR_OK)
 *	{
 *  @par
 *     return i4_ret;
 *	}
 *  @par
 *     t_bound_rect = pt_this_obj->t_bound_rect;
 *  @par
 *     t_thumb_info.h_sruf = pt_this->pt_buf_thumb_show->h_surf;
 *  @par
 *	t_thumb_info.ui4_thumbnail_x = (UINT32)t_bound_rect.i4_left;
 *  @par
 *     t_thumb_info.ui4_thumbnail_y = (UINT32)t_bound_rect.i4_top;
 *  @par
 *     t_thumb_info.ui4_thumbnail_width = (UINT32)WGL_RECT_GET_WIDTH(&t_bound_rect);
 *  @par
 *     t_thumb_info.ui4_thumbnail_height =(UINT32) WGL_RECT_GET_HEIGHT(&t_bound_rect);
 *  @par
 *     t_thumb_info.pf_nfy = _mmp_ve_info_thumb_load_nfy_fct;
 *  @par
 *	t_thumb_info.pv_tag = pt_this_obj;
 *  @par
 *     t_thumb_info.ui8_pic_idx = 1;
 *  @par
 *     i4_ret = c_svctx_media_load_thumbnail(
 *                 pt_this->h_svctx_hdl,
 *                 pt_this_obj->h_elmt_hdl,
 *                 &t_thumb_info
 *                 );
 *  @par
 *     if (i4_ret != SVCTXR_ASYNC_NFY && i4_ret != SVCTXR_OK)
 *	{
 *  @par
 *     pt_this_obj->ui4_crnt_load_ver = VIDEO_ENGINE_LOAD_VER_INVALID;
 *  @par
 *	return i4_ret;
 *	}
 *  @par
 *     pt_this_obj->e_elmt_stat = _MMP_VE_ELMT_STAT_PLAY;
 *  @par
 *     t_thumb_rect = t_bound_rect;
 *  @par
 *     pt_this_obj->t_thumb_rect = t_thumb_rect;
 *  @par
 *     pt_this_obj->ui4_crnt_load_ver = ui4_crnt_load_ver;
 *  @par
 *	pt_this_obj->ui1_flag &= ~VIDEO_ENGINE_INFO_FLAG_STOPING;
 *  @par
 *     pt_this_obj->ui1_flag |=  VIDEO_ENGINE_INFO_FLAG_LOADING;
 *  @par
 *	return MMPR_OK;
 *	}
 *  @subsection ssecMW_MM_HDLR_4_7  4.7. media sync cancel load thumbnail
 *     INT32 _video_engine_thumb_full_stop(
 *					_MMP_VE_PLAY_INST_PTR_T					pt_this
 * 					)
 *    {
 *  @par
 *	_MMP_VE_ELMT_INFO_PTR_T		pt_elmt = _MMP_VE_GET_1ST_ELMT(pt_this);
 *  @par
 *     INT32 i4_ret;
 *  @par
 *     if ((NULL == pt_this) || (NULL == pt_elmt))
 *	{
 *  @par
 *     return MMPR_INTERNAL_ERROR;
 *	}
 *  @par
 *     UINT32							i4_ret;
 *  @par
 *	if (_MMP_VE_ELMT_STAT_INIT == pt_this_obj->e_elmt_stat &&
 *		NULL_HANDLE != pt_this->h_svctx_hdl &&
 *		NULL_HANDLE != pt_elmt->h_elmt_hdl)
 *	{
 *  @par
 *	ii4_ret = c_svctx_media_sync_cancel_load_thumbnail(
 *                         pt_this->h_svctx_hdl, 
 *                         pt_elmt->h_elmt_hdl);
 *  @par	
 *	if (i4_ret != SVCTXR_OK)
 *	{
 *  @par
 *	pt_elmt->e_elmt_stat = _MMP_VE_ELMT_STAT_STOP;
 *	}
 *  @par
 *	if (NULL != pt_this->pt_buf_thumb_show)
 *	{
 *  @par	
 *	i4_ret = mmp_drc_unlock_buf(pt_this->pt_buf_thumb_show);
 *  @par
 *	if(MMPR_OK != i4_ret)
 *	{
 *  @par
 *     return i4_ret;
 *    	}
 *  @par
 *	pt_this->pt_buf_thumb_show = NULL;
 *	}
 *  @par
 *	return MMPR_OK;
 *	}
 */

#endif /* _C_SVCTX_H_ */


