aw_command.h

来自「AMLOGIC DPF source code」· C头文件 代码 · 共 194 行

/*****************************************************************
**                                                             	**
**  Copyright (C) 2004 Amlogic,Inc.                            	**
**  All rights reserved                                        	**
**        Filename : aw_command.h /Project:AVOS  				** 
**        Revision : 1.0                                       	**
**                                                             	**
*****************************************************************/
#ifndef _AW_COMMAND_H
#define _AW_COMMAND_H

/**
 * @file aw_command.h
 * @author LiChao, [e-mail]
 *
 * What's command? Why we need command? As you know, the applications are service supplier, 
 * how to use these service is application stub's business. There are two ways normally, one 
 * is function call; another is message transfer. We use the second one, because it's more 
 * flexible and less coupling. So, we know, command is a special message which send to application 
 * to request a service from application stub(customized code). One command can execute one 
 * basic service, but some time we need exectue a serial commands to complete a special 
 * operation, only all commands exectued success than the operation is success, otherwise this 
 * operation is failure, that's like the transaction of DB. So we import the concept of Command 
 * Set, one Command Set can have a few commands, every command have a parameter which will send 
 * to application too, the parameter type should be supplied by application spec with the command 
 * spec. Every command have a timeout value(second) too, if timeout value biger than 0, that means 
 * we must wait for the response before send next command to application, If the application cannot 
 * have any response in the timeout value, system'll deal with this command as failed and call this
 * command set's ExecuteResultProcess call back function to transfer failure message to customer. 
 * If the timeout value is 0, we don't wait for the response and send next command to application
 * at once. When the all commands in command set executed, go on next command set.
 */

/** @defgroup application_cmd Application command manage routines.
 * @ingroup gui
 */
 
///define the max commands in a command set
#define MAX_COMMANDS	1

/**
 * @brief Following is the status defination of command set
 */
///Define the command set not execute
#define COMMAND_READY		0
///Define the command set is executeing now
#define COMMAND_EXECUTEING	1
///Define the command set have executed
#define COMMAND_DONE		2

#define GO_ON_EXECUTE_COMMAND		0
#define BREAK_EXECUTE_COMMAND		1

#define FLAG_WAIT_UNTIL_ALL_COMMAND_DONE	0x1
#define FLAG_COMMAND_ON_WAIT				0x2

typedef struct _commandset *PCMDSET;
typedef INT8U 	(*CMDSETRESULTHANDLE)(AWMSG *pMsg, PCMDSET cmd_set) ;
/**
 * @brief Following struct is the command set data struct, command set is a basic function set, which 
 * will send to application to execute. It can have MAX_COMMANDS commands, you can see the help of 
 * application to see what's parameter needed for every command and what's means of this command.
 */
typedef struct _commandset {
	list_t	command_list ;
	///command nums in this command set, user will set it
	INT8U	command_num;
	////the command crrent should be execute or execting now or executed, depend on the 
	///command set execute status (comand_flag)				
	INT8U	curr_executed_cmd_num;
	///the application which will receive this command set and do it, user set it		
	INT8U	app_id;
	///this command set internal execute status
	INT8U	comand_flag ;
	///commands of this command set, user set it
	INT16U	commands[MAX_COMMANDS] ;
	///parameters for every command, one by one, user set it
	INT32U 	commands_para[MAX_COMMANDS];
	///the timer(second) to wait for the application respons, if out of time, 
	//system generate a failure. If timer is 0, means this command don't wait the 
	///resopns from application, user set it.
	INT8U	cmd_timeout_value[MAX_COMMANDS]; 
	///reserved, Task which send this command
	INT16U	sou_task_id ; 				
	///reserved, Task ID which will receive this command
	INT16U  des_task_id ;
        /// message identification
        INT16U counting;
	///this is a call back function, when we get the command set execute result,
	///system will call this function to handle the result.	user set it			
	CMDSETRESULTHANDLE ExecuteResultProcess; 
} COMMANDSET ;	

//#define AW_DYNAMIC_MALLOC_COMMAND_SET
#ifdef AW_DYNAMIC_MALLOC_COMMAND_SET
	#define AWCommandSetMalloc()	(PCMDSET)AVMem_umalloc(sizeof(COMMANDSET))
	#define AWCommandSetFree(a)	 AVMem_ufree((void *)a)	
#else
/**
 * @brief Malloc new command set.
 * @return If have enough space, return a COMMANDSET data point, otherwise return NULL 
 */
	PCMDSET AWCommandSetMalloc(void) ;
	void AWCommandSetFree(PCMDSET pAWCmdSet) ;
#endif

/**
 * @brief Initial the Command routine, shoule be called before any other command function.
 */
void AWCommandSetInit(void) ;

/**
 * @brief Add a command set to list and wait it send to the application. This command set 
 * will added to the tail of Command Set List.
 * @param [in] pAddSet it's the command set point which will added to the list.
 *
 * //Following function send a normal play command to application 
 *void PlayCDDA(void)
 *{
 *	PCMDSET pCDDACmd ;
 *	pCDDACmd = AWCommandSetMalloc() ;
 *	pCDDACmd->command_num = 1 ;
 *	pCDDACmd->curr_executed_cmd_num = 0 ;
 *	pCDDACmd->commands[0] = CM_BACK_TO_NORMAL_PLAY ;
 *	pCDDACmd->commands_para[0] = 0 ;
 *	pCDDACmd->cmd_timeout_value[0] = 1 ; 
 *	AWGetAppID(MEDIA_CDDA, &pCDDACmd->app_id) ;
 *  pCDDACmd->ExecuteResultProcess = CDDA_END_PAUSE_Response ;
 *	AWAddCommandSet(pCDDACmd) ;
 *}	
 */
INT32S AWAddCommandSet(PCMDSET pAddSet) ;

/**
 * @brief Add the command set to the list head and wait it send to the application. This 
 * command set will added to the head of Command Set List. When you want your command set 
 * be executed more quickly, use this function.
 * @param [in] pAddSet it's the command set point which will added to the list.
 * @return If success, return 0; If not enough memory space to hold these new 
 * command(malloc command set fail), return 1;
 */
void AWAddCommandSetToHead(PCMDSET pAddSet) ;

/**
 * @brief Add a command set to the tail of Command Set List.
 * The difference from AWAddCommandSet is this function will malloc commanset for you,
 * you just input some parameter, this function will generate a command set for you.
 * @param [in] iCmdNum define the command numbers which should be added to a command set.
 * @param [in] pCmds[] The array of commands which will be added to command set.
 * @param [in] pCmdsParam[] The array of commands' parameter, these parameters' type is 
 * defined by the commands, different command have different parameter type, which defined 
 * by application help.
 * @param [in] pCmdTimeOut[] The array of time out value, define the every command's time 
 * out value. If biger than 0, system will wait for the response when the command sended to 
 * application, if no response return in time, system deal with this command as fail command. 
 * If equal 0, system will send next command to application at once and don't wait response.
 * @param [in] iDestApp Define the application which will receive these commands.
 * @param [in] pHandle Customize call back function, if the commands executed success or fail, 
 * system will call this function to do some action customer want to.
 * @return If success, return 0; If not enough memory space to hold these new 
 * command(malloc command set fail), return 1; If the iCmdNum exceed the max number commands of 
 * Command Set, return 2.
 
 * See Also 
 * AWAddCommandSet, AWAddCommandSetToHead
 */
INT32S AWAddCmdSet(INT8U iCmdNum, INT16U pCmds[], INT32U pCmdsParam[], INT8U pCmdTimeOut[], INT8U iDestApp, CMDSETRESULTHANDLE pHandle);

/**
 * @brief Check if a command set is valid. 
 * AWIsCommandSetValid(pCmdSet) should be called to check if pCmdSet is valid before calling AWAddCommandSet(pCmdSet)
 * @return If valid, return 1; If not valid, return 0,AWAddCommandSet(pCmdSet) can not be called in this case ;*/
INT8U AWIsCommandSetValid(PCMDSET pCmdSet);

INT8U AWExecuteInstantCmd(PCMDSET pAddSet, INT32U timeout, INT32U* retvalue );

/**
 * Following functions are internal function list, customer may don't use it.
 */
 
 
PCMDSET AWGetCurrentCommandSet() ;
INT32S AWIfCurrentCommandSetDone(void);
PCMDSET AWGetWaitCommandSet(AWMSG *pMsg);
void AWCancleCommandExecuteTimer(void);
void AWPrepareNextCommand() ;
void AWRemoveCommandSet(PCMDSET pRemoveSet) ;
INT32S AWIfWaitCommandSetDone(PCMDSET pWaitCmdSet) ;
void AWDeleteWaitCommandSet(PCMDSET pDeleteSet);
INT8U AWDispatchCommand(void) ;
void AWDeleteCommandSet(PCMDSET pDeleteSet);
INT8U AWDispCmd(PCMDSET pAddSet);
void AWClearCommandSet(list_t* disp_que);
#endif