queue.h

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2011 Ocean Blue Software Ltd
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 * 
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 * 
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
#ifndef _QUEUE_H
#define _QUEUE_H

#include "hbbtv_types.h"

#define MAX_MSG_SIZE    32    /*bytes*/

typedef void (*F_QUE_NOTIFY)( void );

typedef enum
{
   PRTY_CRITICAL,    /*start/stop/key-press*/
   PRTY_NORMAL,      /*Events*/
   PRTY_RESULTS,     /*query results*/
   PRTY_DSMCC_HIGH,
   PRTY_DSMCC_LOW,
   PRTY_INVALID
} E_QUE_MESSAGE_PRIORITY;

typedef enum
{
   DT_NONE,
   DT_VALUE,
   DT_ALLOC,
   DT_CONTENT,
   DT_D_CONTENT,
   DT_F_CONTENT,
   DT_S_CONTENT
} E_QUE_DATA_TYPE;

/*******************************************************************************
 *@begin
 * NAME: F_QUE_FUNCTION
 *       Function to Process HbbTV engine message
 *
 * Returns : void
 *
 * Parameter     Flow    Description
 * ------------------------------------------------------------------------------
 *  data          IN     Pointer to msg data
 *
 *@end
 *******************************************************************************/
typedef void (*F_QUE_FUNCTION)( void *data );

typedef struct
{
   void *usr_ptr;
   U32BIT first32bit;
   U16BIT secnd16bit;
   U16BIT third16bit;
} S_QUE_GENERAL_PARAMS;

typedef struct
{
   U16BIT sid;
   U16BIT type;
   U16BIT pid;
} S_QUE_AIT_PARAMS;

typedef struct
{
   U16BIT serv_id;
   U16BIT trans_id;
   U16BIT onet_id;
   U32BIT status;
} S_QUE_CHANNEL_CHANGE_PARAMS;

typedef struct
{
   S_HBBTV_STRING url;
   void *eventPtr;
} S_QUE_STREAM_EVENT_REQUEST;

typedef struct
{
   U32BIT id;
   U32BIT event;
} S_QUE_RECORDING_EVENT_PARAMS;

typedef struct
{
   U32BIT first_number;
   U32BIT second_number;
   U8BIT *message;
   U32BIT length;
} S_QUE_DRM_PARAMS;

/* Event parameters. */
typedef struct
{
   F_QUE_FUNCTION proc_msg_func;
   E_QUE_DATA_TYPE data_type;
   union
   {
      S_QUE_GENERAL_PARAMS params;
      S_QUE_AIT_PARAMS ait;
      S_QUE_CHANNEL_CHANGE_PARAMS channel_change;
      S_QUE_STREAM_EVENT_REQUEST SEventRqst;
      S_QUE_RECORDING_EVENT_PARAMS recording_event;
      S_QUE_DRM_PARAMS drm;
   } data;
} S_QUE_MESSAGE;

/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueOpen
 *       Initialise component control and section queues. Allocates memory for,
 *       sets up and creates event (component control) and section queues.
 *
 * Returns : HBBTV_OK                  - Completed successfully.
 *           HBBTV_ERR_BAD_PARAMETER   - Invalid parameter.
 *           HBBTV_ERR_COMP_ALREADY_OPEN    - Component queues already open.
 *           HBBTV_ERR_ALLOCATING_MEMORY   - Not enough memory to allocate.
 *           HBBTV_ERR_INTERNAL    - System error.
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_QueOpen(void);


/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueClose
 *       Close component control and section queue component. Destroys all
 *       allocated memory and resources for event and section queues.
 *
 * Returns : void
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 * None.
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
void HBBTV_QueClose(void);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_QuePutMsg
 *       Post event or section message on queue. Copies data into queue.
 *
 * Returns : HBBTV_OK                   - Completed successfully.
 *           HBBTV_ERR_BAD_PARAMETER    - Invalid parameter.
 *           HBBTV_ERR_COMP_NOT_OPEN         - Component queues not open.
 *           HBBTV_ERR_INTERNAL     - System error.
 *           HBBTV_ERR_ALLOCATING_MEMORY    - Not enough memory to allocate.
 *           HBBTV_ERR_QUEUE_FULL       - Queue full.
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 * pMsg                 IN     Pointer to message.
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_QuePutMsg(S_QUE_MESSAGE *p_msg, E_QUE_MESSAGE_PRIORITY priority);


/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueGet
 *       Get an event or section from the component queues.
 *       This is a blocking function.
 *
 * Returns : HBBTV_OK                   - Completed successfully.
 *           HBBTV_ERR_COMP_NOT_OPEN         - Component queues not open.
 *           HBBTV_ERR_INTERNAL     - System error.
 *
 * Parameter      Flow    Description
 * ------------------------------------------------------------------------------
 * pElem          OUT     Pointer to event message
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_QueGetMsg(S_QUE_MESSAGE *pElem);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueGetSizeFree
 *       Get size available on a queue.
 *
 * Returns : number left in queue.
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 * pEvent              OUT     Pointer to component event or section data
 *                             structure.
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
U16BIT HBBTV_QueGetSizeFree(E_QUE_MESSAGE_PRIORITY priority);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueEventNeedsProcessing
 *       Check whether any events on component queues needs processing.
 *
 * Returns : TRUE  - if processing required
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
BOOLEAN HBBTV_QueEventNeedsProcessing(void);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueRegisterNormalNotify
 *
 * Returns : void
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 * critical_rcvd        IN     Pointer to function signalling a critical event
 * critical_done        IN     Pointer to function inform critical event done
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
void* HBBTV_QueRegisterNotify(F_QUE_NOTIFY normal_rcvd, F_QUE_NOTIFY critical_rcvd,
   F_QUE_NOTIFY critical_done);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_QueUnRegisterNotify
 *
 * Returns : void
 *
 * Parameter           Flow    Description
 * ------------------------------------------------------------------------------
 * normal_rcvd          IN     Pointer to function signalling an async event
 *
 * Additional information:
 * None.
 *
 *@end
 *******************************************************************************/
void HBBTV_QueUnRegisterNotify(void *qn);

#endif /*_QUEUE_H*/