DVD

开发平台：
C/C++

machblue_tv_porting.h：源码内容
							/*-----------------------------------------------------------------------------
 | @(#) machblue_tv_porting.h
 |
 |  JSWF: The Portable SWF Engine For Embedded Devices,
 |  Copyright (c) 2002-2006, BlueStreak Technology Inc., All Rights Reserved.
 |
 +----------------------------------------------------------------------------*/
#ifndef _MACHBLUE_TV_PORTING_H_
#define _MACHBLUE_TV_PORTING_H_
/*----------------------------------------------------------
 | Include definition below this line
 +----------------------------------------------------------*/
#include "machblue_tv_defines.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/*----------------------------------------------------------
 | Macro definition below this line
 +----------------------------------------------------------*/
/*----------------------------------------------------------
 | Type definition below this line
 +----------------------------------------------------------*/
/*----------------------------------------------------------
 | Functions definition below this line
 +----------------------------------------------------------*/
/*
 * ======================= TV Porting Layer Init API====================================
 */
/** @defgroup init_group TV Porting Layer Init API
 *  @{
 * This API is used by Machblue to initialize or delete the 
 * tv porting layer.
 */
/**
 * Invoked by Machblue to initialize the tv porting layer. This
 * will be called before any calls to the tv porting layer. After 
 * this call Machblue expects that any asynchronous query will be perfomed
 * by the system with the shortest response time possible. On most systems
 * responding to these queries in a short time implies a heavy caching 
 * of network signalization tables. This caching mechnism is supposed to be
 * enabled by the middleware at the latest before the completion of 
 * mb_tv_porting_layer_init.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_tv_porting_layer_init
( 
    mb_tv_notify_f *tv_notify_f,   /**< machblue tv notification function that will be called
                                        for all asynchronous notifications */
    void           *nf_client_data /**< notification function client data to pass as-is to the 
                                        notification function */
);
/**
 * Invoked by Machblue to delete the tv porting layer. Machblue will 
 * not make any calls to the tv porting layer after this call
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_tv_porting_layer_delete( void );
/** @} */
/*
 * ======================= TV Service List API ===========================================
 */
/** @defgroup svl_group TV Service List API
 *  @{
 * This API is used by Machblue to retrieve the system's 
 * service lists.
 */
/**
 * This function returns the number of service lists available on the platform.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_list_count_get
( 
    int *svl_count /**< user provided int to store service list count */ 
);
/**
 * This function retrieves a service list object from the system.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_LISTS_GET notification once the request is completed.
 * The "All Channel" service list should always be at index 0 (MB_TV_SVL_ALL_ID).
 * @see MB_TV_NR_SERVICE_LISTS_GET 
 * @see MB_TV_SVL_ALL_ID
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_lists_get
( 
    int                     first_svl_pos,   /**< position of the first service list to get (0 based) */
    int                    *svl_count,       /**< pointer to number of service lists to retrieve. This
                                                  pointer should be updated with number of service lists
                                                  actually returned. */ 
    mb_tv_service_list_t   *svl_list         /**< user provided list (array) of service list pointers to update */
);
/**
 * This function releases a service list object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svl_release
( 
    mb_tv_service_list_t   svl      /**< service list object to release */
);
/**
 * This function retrieves a service list info from the system.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svl_info_get
( 
    mb_tv_service_list_t   svl,      /**< service list to query */
    mb_tv_svl_info_t      *svl_info  /**< service info structure to update */
);
/**
 * This function returns the number of services available in a service list.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svl_service_count_get
( 
    mb_tv_service_list_t   svl,          /**< service list to query */
    int                   *service_count /**< pointer to int to store service count */ 
);
/**
 * This function retrieves service objects from a service list.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICES_GET notification once the request is completed.
 * @see MB_TV_NR_SERVICES_GET
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svl_services_get
( 
    mb_tv_service_list_t    svl,                /**< service list to retrieve service from */
    int                     first_service_pos,  /**< position of the first service to retrieve (0 based) */
    int                    *service_count,      /**< pointer to number of service to retrieve. This
                                                     pointer should be updated with number of services
                                                     actually retrieved */                                        
    mb_tv_service_t        *service_list        /**< user provided list (array) of service pointers to update */
);
/** @} */
/*
 * ======================= TV Service API ===========================================
 */
/** @defgroup service_group TV Service API
 *  @{ 
 * This API is used by Machblue to retrieve a service object 
 * attributes including its present event, following event 
 * and event schedule list objects.
 */
/**
 * This function releases a service object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_release
( 
    mb_tv_service_t   service      /**< service object to release */
);
/**
 * This function retrieves a service object from a service url. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_GET_FROM_URL notification once the request 
 * is completed.
 * @see MB_TV_NR_SERVICE_GET_FROM_URL
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_get_from_url
( 
    const mb_char_t        *url,  /**< url of the service object to retrieve. The following
                                   service url syntax should be used:
                                   @li To get a service object from a DVB triplet: 
                                   @c "dvb://network_id.transport_id.service_id"
                                   @li To get a service object from an SDP url:
                                   @c "sdp://hostname:port/path"
                                   @li To get a service object from an RTSP url:
                                   @c "rtsp://hostname:port/path" */
    mb_tv_service_t *service  /**< pointer to service object to update */
);
/**
 * This function retrieves a service info from the system.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_info_get
( 
    mb_tv_service_t        service,      /**< service to query */
    mb_tv_service_info_t  *service_info  /**< service info structure to update */
);
/**
 * This function retrieves a given service authorization flags.
 * Note this does not indicate if the program event currently 
 * running on the service is authorized. It only indicates the
 * service' status.  The list of authorization flags is enumerated
 * in mb_tv_authorization_flag_t.
 * @see mb_tv_authorization_flag_t.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_auth_flags_get
( 
    mb_tv_service_t  service,    /**< service to query */
    unsigned int    *auth_flags  /**< pointer to service authorization flags to update.
                                      @see mb_tv_authorization_flag_t. */
);
/**
 * This function retrieves the current event of a service. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_CURRENT_EVENT_GET notification once the request 
 * is completed.
 * @see MB_TV_NR_SERVICE_CURRENT_EVENT_GET
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_current_event_get
( 
    mb_tv_service_t  service, /**< service to query */
    mb_tv_event_t   *event    /**< pointer to event to update */
);
/**
 * This function retrieves the following event of a service. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_FOLLOWING_EVENT_GET notification once the 
 * request is completed.
 * @see MB_TV_NR_SERVICE_FOLLOWING_EVENT_GET
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_following_event_get
( 
    mb_tv_service_t  service,  /**< service to query */
    mb_tv_event_t   *event     /**< pointer to event to update */
);
/**
 * This function returns an event schedule object representing a
 * section of the service complete event schedule. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_EVENT_SCHEDULE_GET notification once the request 
 * is completed.
 * @see MB_TV_NR_SERVICE_EVENT_SCHEDULE_GET
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_event_schedule_get
( 
    mb_tv_service_t          service,        /**< service to query */
    mb_time_t                start_time,     /**< requested start time of the event schedule query 
                                                  window in seconds since 01/01/1970 UTC. 
                                                  If set to 0 or if the requested start time is smaller 
                                                  than the start time of the first available event of the 
                                                  event schedule cache then the first available event start 
                                                  time should be used for the query. */
    mb_time_t                end_time,       /**< requested end time of the event schedule query 
                                                  window in seconds since 01/01/1970 UTC. 
                                                  If set to 0 or if the requested end time is greater 
                                                  than the end time of the last available event of the 
                                                  event schedule cache then the last available event start 
                                                  time should be used for the query.*/
    mb_tv_event_schedule_t  *event_schedule  /**< pointer to event schedule object to update */
);
/**
 * This function retrieves the service list object containing 
 * the provided object if any. If the service is a recorded or 
 * vod service that has no associated service list 
 * MB_TV_INVALID_SERVICE_LIST should be returned. The function also 
 * retrieve the index of the service object in the service list.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_svl_get
( 
    mb_tv_service_t         service,      /**< service to query */
    mb_tv_service_list_t   *svl,          /**< pointer to service list object to update */
    int                    *index         /**< pointer to the service index to update */
);
/** @} */
/*
 * ======================= TV Event Information API ===========================================
 */
/** @defgroup event_info_group TV Event Information API
 *  @{
 * This API is used by Machblue to retrieve event information 
 * from an event objects.
 */
/**
 * This function releases an event schedule object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_evs_release
( 
    mb_tv_event_schedule_t  evs      /**< event schedule object to release */
);
/**
 * This function retrieves the number of events of an event schedule object. 
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_evs_event_count_get
( 
    mb_tv_event_schedule_t  evs,        /**< event schedule to query */
    int                    *event_count /**< pointer to int to store event count */ 
);
/**
 * This function retrieves the index of the current event of an 
 * event schedule object if available. Otherwise returns -1 as
 * index if the query is not applicable (recording event 
 * schedule for instance). 
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_evs_current_event_index_get
( 
    mb_tv_event_schedule_t  evs,         /**< event schedule to query */
    int                    *index        /**< pointer to the current event index to update */
);
/**
 * This function retrieves events from an event schedule object. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_EVS_EVENTS_GET notification once the request is completed.
 * @see MB_TV_NR_EVS_EVENTS_GET
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_evs_events_get
( 
    mb_tv_event_schedule_t  evs,             /**< event schedule to query */
    int                     first_event_pos, /**< position of the first event to get (0 based) */
    int                    *event_count,     /**< pointer to number of event to retrieve. This
                                                  pointer should be updated with number of events
                                                  actually retrieved */                                        
    mb_tv_event_t          *event_list       /**< pointer to list (array) of events to update */ 
);
/**
 * This function releases an event object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_event_release
( 
    mb_tv_event_t  event      /**< event to release */
);
/**
 * This function retrieves an event's attributes.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_event_attributes_get
( 
    mb_tv_event_t              event,        /**< event object to query */
    mb_tv_event_attributes_t  *event_attrib  /**< event attributes structure to update */
);
/**
 * This function retrieves a given event authorization flags.
 * The list of authorization flags is enumerated in 
 * mb_tv_authorization_flag_t.
 * @see mb_tv_authorization_flag_t
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_event_auth_flags_get
( 
    mb_tv_event_t   event,       /**< event object to query */ 
    unsigned int    *auth_flags  /**< pointer to event authorization flags to update.
                                      @see mb_tv_authorization_flag_t. */
);
/**
 * This function retrieves an event' service.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_event_service_get
( 
    mb_tv_event_t     event,   /**< event object to query */
    mb_tv_service_t  *service  /**< pointer to event service to update */
);
/** @} */
/*
 * ======================= TV Service Context API ===========================================
 */
/** @defgroup service_context_group TV Service Context API
 *  @{
 * This API is used by Machblue to access and control 
 * the system' service contexts.
 */
/**
 * This function returns the number of service contexts
 * available on the platform.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_context_count_get
( 
    int *svc_count /**< user provided int to store service context count */ 
);
/**
 * This function retrieves service context objects from the system.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_CONTEXTS_GET notification once the request is 
 * completed.
 * @see MB_TV_NR_SERVICE_CONTEXTS_GET
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_contexts_get
( 
    int                      first_sc_pos,   /**< position of the first service context to retrieve (0 based) */
    int                     *sc_count,       /**< pointer to number of service contexts to retrieve. This
                                                  pointer should be updated with number of service context
                                                  actually retrieved */                                                                  
    mb_tv_service_context_t *svc_list        /**< pointer to list (array) of service contexts update */
);
/**
 * This function retrieves the service context object associated
 * to a client if any.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svc_get_from_client
( 
    mb_client_t               client,       /**< client handle to query */
    mb_tv_service_context_t *client_svc     /**< pointer to service context to update with client's service 
                                                 context if any, otherwise MB_TV_INVALID_SERVICE_CONTEXT should 
                                                 be returned */
);
/**
 * This function releases a service context object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svc_release
( 
    mb_tv_service_context_t  svc      /**< service context object to release */
);
/**
 * This function retrieves a service info from the system.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_svc_info_get
( 
    mb_tv_service_context_t        svc,      /**< service to query */
    mb_tv_service_context_info_t  *svc_info  /**< service context info structure to update */
);
/**
 * This function gets a service context viewport attributes
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */ 
extern mb_error_t mb_tv_svc_viewport_get
(
    mb_tv_service_context_t  svc,       /**< service context to query */
    mb_tv_viewport_t        *viewport   /**< pointer to viewport coordinates to update */ 
);
/**
 * This function sets a service context viewport attributes.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */ 
extern mb_error_t mb_tv_svc_viewport_set
(
    mb_tv_service_context_t  svc,       /**< service context to modify */
    mb_tv_viewport_t        *viewport   /**< pointer to viewport coordinates to set */ 
);
/**
 * This function retrieves a service object representing 
 * the service that is currently active in a service context. 
 * If the context is idle, null is returned.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */ 
extern mb_error_t mb_tv_svc_service_get
(
    mb_tv_service_context_t svc,       /**< service context to query */
    mb_tv_service_t        *service   /**< pointer to service context service to update */
);
/**
 * This function selects a service (tune in the case of a 
 * braodcast service). The currently running service if any 
 * is replaced with the selected service.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_SELECTED or an MB_TV_NR_SERVICE_ERROR 
 * notification once the request is completed.
 * @see MB_TV_NR_SERVICE_SELECTED
 * @see MB_TV_NR_SERVICE_ERROR
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */ 
extern mb_error_t mb_tv_svc_service_select
(
    mb_tv_service_context_t  svc,           /**< service context to modify */
    mb_tv_service_t          service,       /**< service to select */
    int                      enable_streams /**< 1 if default streams should be enabled after service 
                                                 selection, 0 otherwise. */ 
);
/**
 * This function retrieves the stream controller associated 
 * to a service context.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */ 
extern mb_error_t mb_tv_svc_stream_controller_get
(
    mb_tv_service_context_t    svc,              /**< service context to query */
    mb_tv_stream_controller_t *stream_controller /**< pointer to service context stream controller 
                                                      to update */
);
/** @} */
/*
 * ======================= TV Stream Controller API ===========================================
 */
/** @defgroup stream_controller_group TV Stream Controller API
 *  @{
 * This API is used by Machblue DVB Player to control the 
 * streams running in a service context.
 */
/**
 * This function releases a stream controller object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_release
( 
    mb_tv_stream_controller_t  stream_controller     /**< stream controller object to release */
);
/**
 * This function retrieves the number of streams of a stream 
 * controller object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_stream_count_get
( 
    mb_tv_stream_controller_t  stream_controller,  /**< stream_controller managing the streams */
    int                       *stream_count        /**< pointer to int to store stream count */ 
);
/**
 * This function retrieves streams' descriptions from a stream 
 * controller object.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_STREAMS_INFO_GET notification once the request is completed.
 * @see MB_TV_NR_STREAMS_INFO_GET
 * @return MB_SUCCESS on success MB_FAILURE 
 * otherwise.
 */
extern mb_error_t mb_tv_stc_streams_info_get
( 
    mb_tv_stream_controller_t stream_controller,  /**< stream controller to query */
    int                       start_stream_pos,   /**< position of the first stream info to get (0 based) */
    int                      *stream_count,       /**< pointer to number of stream info to retrieve. This
                                                       pointer should be updated with number of stream info
                                                       actually retrieved */                                        
    mb_tv_stream_info_t      *stream_info_list    /**< pointer to stream info list to update with streams */ 
);
/**
 * This function retrieves the state of a given stream type.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_stream_state_get
( 
    mb_tv_stream_controller_t  stream_controller, /**< stream controller to query */
    mb_tv_stream_type_t        stream_type,       /**< stream type */
    mb_tv_stream_state_t      *state              /**< pointer to state enum to update */
);
/**
 * This function enables a given stream type.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_STREAM_ENABLED or an MB_TV_NR_STREAM_ERROR 
 * notification once the request is completed.
 * @see MB_TV_NR_STREAM_ENABLED
 * @see MB_TV_NR_STREAM_ERROR
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_stream_enable
( 
    mb_tv_stream_controller_t stream_controller, /**< stream controller to use */
    mb_tv_stream_type_t       stream_type,       /**< type of stream to enable */
    mb_char_t                *stream_tag         /**< tag of stream to enable */        
);
/**
 * This function disables a given stream type.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_STREAM_DISABLED or an MB_TV_NR_STREAM_ERROR notification 
 * once the request is completed.
 * @see MB_TV_NR_STREAM_DISABLED
 * @see MB_TV_NR_STREAM_ERROR
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_stream_disable
( 
    mb_tv_stream_controller_t stream_controller,  /**< stream controller to use */
    mb_tv_stream_type_t       stream_type         /**< type of stream to disable */
);
/**
 * This function sends a trick play command to a stream controller.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_TRICK_PLAY notification once the request is completed.
 * @see MB_TV_NR_TRICK_PLAY
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_trick_play
( 
    mb_tv_stream_controller_t  stream_controller, /**< stream controller to use */
    mb_tv_trick_play_cmd_t     command,           /**< trick play command to execute */
    long                       param              /**< trick play command parameter */            
);
/**
 * This function retrieves the current trick play state of a stream 
 * controller.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_playback_speed_get
(
    mb_tv_stream_controller_t  stream_controller, /**< stream controller to use */ 
    int                       *pb_speed           /**< pointer to the playback speed integer to update
                                                       hundredths of normal speed */            
);
/**
 * This function returns the current playback position in the 
 * currently running video stream.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_playback_position_get
(
    mb_tv_stream_controller_t  stream_controller,    /**< stream controller to query */
    mb_system_time_t          *pb_buffer_start,      /**< pointer to start of the playback buffer to update in nano-seconds.
                                                          @li For a VOD or Recording playback the playback buffer start time
                                                          should be set to 0.
                                                          @li For a live stream on a PVR system, this correspond to the start
                                                          time of the review buffer in nano-seconds since 01/01/1970 UTC.
                                                          @li For a live stream on a non PVR system, this corresponds to the 
                                                          current time in nano-seconds since 01/01/1970 UTC. */
    mb_system_time_t          *pb_buffer_end,        /**< pointer to end of the playback buffer to update in nano-seconds.
                                                          @li For a VOD or Recording playback the playback buffer end time
                                                          should be set to the VOD playback or recording duration in 
                                                          nano-seconds.
                                                          @li For a live stream on a PVR system, this correspond to the end time
                                                          time of the review buffer ("live" position) in nano-seconds since 
                                                          01/01/1970 UTC.
                                                          @li For a live stream on a non PVR system, this corresponds to the 
                                                          current time in nano-seconds since 01/01/1970. */
    mb_system_time_t          *pb_current_pos        /**< pointer to the current playback position in the playback buffer to 
                                                          update in nano-seconds.
                                                          @li For a VOD or Recording playback this corresponds to the distance 
                                                          in nano-seconds between the playback head and the playback buffer start.
                                                          @li For a live stream on a PVR system this corresponds to the recorded 
                                                          timestamp in nano-seconds since 01/01/1970 UTC at the current location
                                                          of the playback head.
                                                          @li For a live stream on a non PVR system, the current time in 
                                                          nano-seconds since 01/01/1970 should be returned. */
);
/**
 * This function sets a video playback position notification request. 
 * The system should send an MB_TV_NR_PLAYBACK_POSITION_NOTIFY 
 * notification to the player as soon as the requested video
 * playback position value is reached.
 * @see MB_TV_NR_PLAYBACK_POSITION_NOTIFY
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_stc_playback_position_notify
(
    mb_tv_stream_controller_t   stream_controller, /**< stream controller to use */
    mb_system_time_t           *pb_pos_value       /**< video playback position value to watch for in nano-seconds.
                                                        @li For a VOD or Recording playback this corresponds to the distance 
                                                        in nano-seconds between the trigger and the playback buffer start.
                                                        @li For a live stream on a PVR system this corresponds to the recorded 
                                                        timestamp in nano-seconds since 01/01/1970 UTC at the location of the 
                                                        trigger.
                                                        @li For a live stream on a non PVR system, this corresponds to the time 
                                                        in nano-seconds since 01/01/1970 of the trigger. */
);
/** @}*/
/*
 * ======================= TV Recorder API ===========================================
 */
/** @defgroup recorder_group TV Recorder API
 *  @{
 * This API is used by Machblue DVB Player to access the 
 * system's Recorder engine.
 */
/**
 * This function gets the system's recording space information.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_space_get
(
    unsigned long *used,       /**< pointer to long to store total recording space used in KB */
    unsigned long *remaining   /**< pointer to long to store total recording space remaining in KB */
);
/**
 * This function retrieves the number of recordings available 
 * in the system. 
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_count_get
( 
    int *recording_count /**< pointer to int to store event count */ 
);
/**
 * This function retrieves recordings from the system.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_RECORDINGS_GET notification once the request is completed.
 * @see MB_TV_NR_RECORDINGS_GET
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recordings_get
( 
    int                first_recording_pos, /**< position of the first recording to get (0 based) */
    int               *recording_count,     /**< pointer to number of recordings to retrieve. This
                                                 pointer should be updated with number of recordings
                                                 actually retrieved */
    mb_tv_recording_t *recording_list       /**< pointer to list of recordings to update */ 
);
/**
 * This function releases a recording object. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_release
( 
    mb_tv_recording_t  recording     /**< recording object to release */
);
/**
 * This function records the specified event. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_EVENT_RECORD notification once the request is completed.
 * @see MB_TV_NR_EVENT_RECORD
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_event_record
( 
    mb_tv_event_t        event,          /**< event to record */ 
    unsigned long        extra_time,     /**< additional time in seconds to record after the event 
                                              as a safety gap for overflowing events */
    mb_tv_periodicity_t  periodicity,    /**< recording periodicity. i.e. if the event belongs to a 
                                              series how often should we record it */
    mb_tv_recording_t   *recording       /**< pointer to newly created recording to update */
);
/**
 * This function records the specified service. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_SERVICE_RECORD notification once the request is completed.
 * @see MB_TV_NR_SERVICE_RECORD
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_service_record
( 
    mb_tv_service_t      service,        /**< service to record */ 
    mb_time_t            start_time,     /**< recording start time in seconds since 01/01/70 UTC.
                                              If set to 0, then the recording should start imediately */
    mb_time_t            stop_time,      /**< recording stop time in seconds since 01/01/70 UTC.
                                              If set to 0, then the service will be recorded until
                                              stop is invoked on the recording. */
    mb_tv_periodicity_t  periodicity,    /**< recording periodicity. i.e. should we repeat this
                                              manual recording daily, weekly, etc.  */
    mb_tv_recording_t   *recording       /**< pointer to newly created recording to update */
);
/**
 * This function specifies a list of recordings to delete in order 
 * to resolve the specified conflict. 
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_conflict_resolve
( 
    mb_tv_conflict_t   conflict,       /**< conflict to resolve */ 
    mb_tv_recording_t *recording_list  /**< MB_TV_INVALID_RECORDING terminated list of recordings 
                                            to delete to solve conflict */
);
/** @} */
/*
 * ======================= TV Recording API ===========================================
 */
/** @defgroup recording_group TV Recording API
 *  @{
 * This API is used by Machblue DVB Player to manipulate 
 * recordings.
 */
/**
 * This function retrieves a recordings attributes.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_attributes_get
( 
    mb_tv_recording_t              recording,        /**< recording object to query */
    mb_tv_recording_attributes_t  *recording_attrib  /**< recording attributes structure to update */
);
/**
 * This function retrieves a recording synthetized service.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_service_get
( 
    mb_tv_recording_t  recording,  /**< recording object to query */
    mb_tv_service_t   *service     /**< pointer to recording service to update */
);
/**
 * This function retrieves a recording state. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_state_get
( 
    mb_tv_recording_t        recording,  /**< recording object to query */
    mb_tv_recording_state_t *state       /**< pointer to recording state to update */
);
/**
 * This function stops a recording. This only afects recordings 
 * in MB_TV_RECORDING_STATE state.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_stop
( 
    mb_tv_recording_t  recording  /**< recording object to stop */
);
/**
 * This function deletes a recording.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_recording_delete
( 
    mb_tv_recording_t  recording   /**< recording object to delete */
);
/** @} */
/*
 * ======================= TV VOD Session API ===========================================
 */
/** @defgroup vod_group TV VOD Session API
 *  @{
 * This API is used by Machblue DVB Player to establish VOD 
 * sessions.
 */
/**
 * This function setups a vod session. 
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_VOD_SESSION_CONNECTED or an MB_TV_NR_VOD_SESSION_ERROR 
 * notification once the request is completed.
 * @see MB_TV_NR_VOD_SESSION_CONNECTED
 * @see MB_TV_NR_VOD_SESSION_ERROR
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_vod_session_setup
( 
    const mb_char_t     *asset_id,       /**< id of the vod asset to launch in vod session */
    const mb_char_t     *server_name,    /**< vod server to connect to */
    const mb_char_t     *private_data,   /**< system dependent private data to send with session 
                                              setup request */
    mb_tv_vod_session_t *session         /**< pointer to newly created session to update */
);
/**
 * This function releases a vod session. All objects associated to the
 * session including its service object will be deleted.
 * This function is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_VOD_SESSION_DISCONNECTED notification once the request is 
 * completed.
 * @see MB_TV_NR_VOD_SESSION_DISCONNECTED
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_vod_session_release
( 
    mb_tv_vod_session_t session         /**< vod session to delete */
);
/**
 * This function gets the service associated to a connected vod session.
 * @return MB_SUCCESS on success MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_vod_session_service_get
( 
    mb_tv_vod_session_t  session,        /**< vod session to query */
    mb_tv_service_t     *service         /**< pointer to vod service to update */
);
/**
  * This function gets the state of a vod session.
  * @return MB_SUCCESS on success MB_FAILURE otherwise.
  */
extern mb_error_t mb_tv_vod_session_state_get
( 
    mb_tv_vod_session_t        session, /**< vod session to query */
    mb_tv_vod_session_state_t *state    /**< pointer to vod session state to update */
);
/** @} */
/*
 * ======================= TV Miscellaneous API ===========================================
 */
/** @defgroup misc_group TV Miscellaneous API
 *  @{
 * TV Miscellaneous API
 */
/**
 * This function returns the currently selected screen 
 * language, as an ISO 639 language code string. The platform 
 * can also provides live notification of screen language changes 
 * through the MB_TV_NR_LANGUAGE_CHANGED notification event. 
 * @see MB_TV_NR_LANGUAGE_CHANGED
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_screen_language_get
( 
    mb_char_t *language  /**< user provided string pointer to update, the string
                             is at least MB_TV_LANGUAGE_STRING_LENGTH long */
);
/**
 * This function returns the default screen language, as an ISO 639 language
 * code string. The default language is a system-wide fall-back language
 * value. 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_default_screen_language_get
( 
    mb_char_t *language  /**< user provided string pointer to update, the string
                             is at least MB_TV_LANGUAGE_STRING_LENGTH long */
);
/**
 * This function returns the current rating block, as a string, formatted 
 * for display purposes using the local standards for displaying program ratings.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_rating_block_get
( 
    mb_char_t *ratings  /**< user provided string pointer to update, the string
                             is at least MB_TV_RATING_STRING_LENGTH long */
);
/**
 * This function retrieves a given asset authorization flags.
 * Note that services and program events have their own 
 * authorization methods.  This method is useful if an application 
 * is using the conditional access system for something other than a 
 * service or a program event, such as an interactive service.
 * The list of authorization flags is enumerated in 
 * mb_tv_authorization_flag_t.
 * @see mb_tv_authorization_flag_t
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_asset_auth_flags_get
( 
    const mb_char_t *asset_id,   /**< id of the assets to check */
    unsigned int    *auth_flags  /**< pointer to asset authorization flags to update
                                      @see mb_tv_authorization_flag_t */
);
/**
 * This function attempts to purchase the specified asset.
 * This operation is ASYNCHRONOUS, and may imply a roundtrip 
 * to the head-end for a credit check and actual processing.
 * It is expected that any user intervention, in the form of 
 * a confirmation, has been done prior to calling this method.
 * @see MB_TV_NR_ASSET_PURCHASE_STATUS 
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_asset_purchase
( 
    const mb_char_t *asset_id /**< id of the assets to purchase */
);
/**
 * This function validates the specified PIN. This method will 
 * cause the system to display a standard PIN entry form, and 
 * ask the subscriber to enter the appropriate PIN.
 * 
 * This method is ASYNCHRONOUS. The system should send an 
 * MB_TV_NR_PIN_VALIDATION_STATUS notification on completion of the 
 * request.The MB_TV_NR_PIN_VALIDATION_STATUS event contains a 
 * field indicating the success of the operation.
 * @see MB_TV_NR_PIN_VALIDATION_STATUS
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_pin_validate
( 
    mb_tv_pin_type_t  pin_type /**< pin type to validate */
);
/**
 * This function retrieves device info from the system.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_device_info_get
( 
    mb_tv_device_info_t  *device_info  /**< device info structure to update */
);
/**
 * This function retrieves the current device device state 
 * from the system.
 * @return MB_SUCCESS on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_tv_device_state_get
( 
    mb_tv_device_state_t  *device_state  /**< device state enum to update */
);
/** @} */
#ifdef __cplusplus
}      /* extern "C" */  
#endif /* __cplusplus */
#endif /* _MACHBLUE_TV_PORTING_H_ */

						