FreeCalypso > hg > fc-selenite
view src/cs/drivers/drv_app/kpd/kpd_api.h @ 84:32bcc299ef55
gcc/ld-script.src: additional polish
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Fri, 20 Jul 2018 19:36:25 +0000 |
parents | b6a5e36de839 |
children |
line wrap: on
line source
/** * @file kpd_api.h * * API Definition for keypad driver. * * This file gathers all the constants, structure and functions declaration * useful for a keypad driver user. * * @author Laurent Sollier (l-sollier@ti.com) * @version 0.1 */ /* * History: * * Date Author Modification * ---------------------------------------- * 10/10/2001 L Sollier Create * * * (C) Copyright 2001 by Texas Instruments Incorporated, All Rights Reserved */ #ifndef _KPD_API_H_ #define _KPD_API_H_ #include "kpd/kpd_cfg.h" #include "rv/rv_general.h" #include "rvf/rvf_api.h" /** * @name External types * * Types used in API. * */ /*@{*/ /** Definition of the subscriber identification. */ typedef void* T_KPD_SUBSCRIBER; /** Definition of the virtual key identification. */ typedef UINT8 T_KPD_VIRTUAL_KEY_ID; /** Definition of the notification level (First press, long press, infinite repeat, release). */ typedef UINT8 T_KPD_NOTIF_LEVEL; /** Definition of a set of keys. */ typedef struct { UINT8 nb_notified_keys; T_KPD_VIRTUAL_KEY_ID notified_keys[KPD_NB_PHYSICAL_KEYS]; } T_KPD_VIRTUAL_KEY_TABLE; /*@}*/ /** Allowed values for T_KPD_NOTIF_LEVEL type. * If a key is defined with KPD_NO_NOTIF, this key will be deleted from the key list * notified to the client. * But client will can set later as KPD_RELEASE_NOTIF (for exemple) * without calling unsubscribe, subscribe functions. */ #define KPD_NO_NOTIF (0x00) /** Allowed values for T_KPD_NOTIF_LEVEL type. * If a key is defined with KPD_FIRST_PRESS_NOTIF, client will be notified by : * - The immediate key press */ #define KPD_FIRST_PRESS_NOTIF (0x01) /** Allowed values for T_KPD_NOTIF_LEVEL type. * If a key is defined with KPD_LONG_PRESS, client will be notified by : * - The long press if the key is still pressed for a defined time * (defined in kpd_define_repeat_keys function) */ #define KPD_LONG_PRESS_NOTIF (0x02) /** Allowed values for T_KPD_NOTIF_LEVEL type. * If a key is defined with KPD_INFINITE_REPEAT_NOTIF, client will be notified by : * - The long press if the key is still pressed for a defined time * (defined in kpd_define_repeat_keys function) * - The key pressed every defined time (defined in kpd_define_repeat_keys function), * until the key is released */ #define KPD_INFINITE_REPEAT_NOTIF (0x04) /** Allowed values for T_KPD_NOTIF_LEVEL type. * If a key is defined with KPD_RELEASE_NOTIF, client will be notified by : * - the key release */ #define KPD_RELEASE_NOTIF (0x08) /*************************************************************************/ /************************** FUNCTIONS PROTOTYPES *************************/ /*************************************************************************/ /** * @name API functions * * API functions declarations. */ /*@{*/ /** * function: kpd_subscribe * * This function is called by the client before any use of the keypad driver services * It is called only once. * * @param subscriber_p Subscriber identification value (OUT). * @param mode Mode used by the keypad client. * @param notified_keys_p Define all the keys the client want to be notified. * @param return_path Return path for key pressed. * @return * - RV_OK if operation is successfull, * - RV_INTERNAL_ERR if * - the max of subscriber is reached, * - the software entity is not started, not yet initialized or initialization has * failed * - RV_INVALID_PARAMETER if number of virtual keys is not correct. * - RV_MEMORY_ERR if memory reach its size limit. * * Message returned: KPD_STATUS_MSG with operation = KPD_SUBSCRIBE_OP. * Available values for status_value are: * - KPD_PROCESS_OK if asynchronous operation is successfull, * - KPD_ERR_KEYS_TABLE if at least one key is not available in the requested mode, * - KPD_ERR_RETURN_PATH_EXISTING if subscriber return path is already defined by * another subscriber, * - KPD_ERR_INTERNAL if an internal error occured. * * @note * - If number of notified key is KPD_NB_PHYSICAL_KEYS, client has not to fulfill * the structure, this will be automatically done by the software entity. */ T_RV_RET kpd_subscribe(T_KPD_SUBSCRIBER* subscriber_p, T_KPD_MODE mode, T_KPD_VIRTUAL_KEY_TABLE* notified_keys_p, T_RV_RETURN return_path); /** * function: kpd_unsubscribe * * This function unsubscribes a client from the keypad driver. * * @param subscriber_p Subscriber identification value (IN/OUT). * @return * - RV_OK if operation is successfull, * - RV_INVALID_PARAMETER if subscriber identification is incorrect. * - RV_MEMORY_ERR if memory reach its size limit. * * - Message: No message is returned for asynchronous processing. */ T_RV_RET kpd_unsubscribe( T_KPD_SUBSCRIBER* subscriber_p); /** * function: kpd_define_key_notification * * This function defines notification type for a set of keys. * By default, all the keys are defined as KPD_RELEASE_NOTIF. * It's not mandatory that all the key defined in the notif_key_table be * notified to the subscriber. If at least one key is set in this table but * is not notified to the subscriber, this will have no effect. * * @param subscriber Subscriber identification value. * @param notif_key_table_p Set of keys for level notification definition. * @param notif_level Define level of notification is set for all the keys. * @param long_press_time Time in tenth of seconds before long press time notification (>0). * @param repeat_time Time in tenth of seconds for key repetition (>0). * @return * - RV_OK if operation is successfull * - RV_INVALID_PARAMETER if : * - subscriber identification is incorrect, * - number of virtual keys is incorrect, * - long_press_time = 0 and repeat_level = KPD_LONG_PRESS_NOTIF or KPD_INFINITE_REPEAT_NOTIF, * - repeat_time = 0 and repeat_level = KPD_INFINITE_REPEAT_NOTIF. * - RV_MEMORY_ERR if memory reach its size limit. * * Message returned: KPD_STATUS_MSG with operation = KPD_REPEAT_KEYS_OP. * Available values for status_value are: * - KPD_PROCESS_OK if asynchronous operation is successfull, * - KPD_ERR_KEYS_TABLE if at least one key is not available in the subscriber mode. * * @note - Values for long_press_time and repeat_time are available for the subscriber but * for all the keys defined in repeat mode. So, if a subscriber call the function * twice with different values of long_press_time and repeat_time, only the latest * values will be taken into account. * - If number of notified key is KPD_NB_PHYSICAL_KEYS, client has not to fulfill * the structure, this will be automatically done by the software entity. * - If the client set a key to KPD_INFINITE_REPEAT_NOTIF, it will be notified of * the long key pressed and the repeat press. */ T_RV_RET kpd_define_key_notification(T_KPD_SUBSCRIBER subscriber, T_KPD_VIRTUAL_KEY_TABLE* notif_key_table_p, T_KPD_NOTIF_LEVEL notif_level, UINT16 long_press_time, UINT16 repeat_time); /** * function: kpd_change_mode * * This function changes the mode for the specific client. * * @param subscriber Subscriber identification value. * @param notified_keys_p Define all the keys the client want to be notified in the new mode. * @param new_mode New mode in which the client want to switch. * @return * - RV_OK if operation is successfull * - RV_INVALID_PARAMETER if : * - subscriber identification is incorrect, * - number of virtual keys is incorrect. * - RV_MEMORY_ERR if memory reach its size limit. * * Message returned: KPD_STATUS_MSG with operation = KPD_CHANGE_MODE_OP. * Available values for status_value are: * - KPD_PROCESS_OK if asynchronous operation is successfull, * - KPD_ERR_KEYS_TABLE if at least one key is not available in the new requested mode, * * @note - Call to this function cancel, for the subscriber, all the repeat mode defined * for the all thekeys with the function kpd_define_repeat_keys. * - If the subscriber was the owner of the keypad, this privilege is cancelled and * keypad is set in multi-notified mode. * - If RV_INVALID_PARAMETER is returned, the current mode for the subscriber is * the old mode and the subscriber is still the keypad owner if it was. * - If number of notified key is KPD_NB_PHYSICAL_KEYS, client has not to fulfill * the structure, this will be automatically done by the software entity. */ T_RV_RET kpd_change_mode( T_KPD_SUBSCRIBER subscriber, T_KPD_VIRTUAL_KEY_TABLE* notified_keys_p, T_KPD_MODE new_mode); /** * function: kpd_own_keypad * * This function allows a subscriber being the only client to be notified by action * on keypad (less CPU time used). * After this call, the keypad is in the "single notified" state. * This action is cancelled when: * - The function is called with parameter is_keypad_owner to FALSE, * - The subscriber (keypad owner) unsubscribe from keypad, * - The subscriber (keypad owner) changes its mode. * * Note that keypad is in the "multi notified" state if there is no subscriber (particularly * at the keypad initialisation). * * @param subscriber Subscriber identification value. * @param is_keypad_owner Define the state to change. * TRUE: keypad pass in "single notified" state * FALSE: keypad pass in "multi notified" state * @param keys_owner_p Set of keys only notified to the subscriber that call this function. * This is mandatory a subset of the keys defined at subscription. * @return * - RV_OK if operation is successfull * - RV_INVALID_PARAMETER if : * - subscriber identification is incorrect, * - number of virtual keys is incorrect. * - RV_MEMORY_ERR if memory reach its size limit. * * Message returned: KPD_STATUS_MSG with operation = KPD_OWN_KEYPAD_OP. * Available values for status_value are: * - KPD_PROCESS_OK if asynchronous operation is successfull, * - KPD_ERR_KEYS_TABLE if at least one key is not defined in the subscriber mode, * - KPD_ERR_SN_MODE if keypad driver is already in SN mode, * - KPD_ERR_ID_OWNER_KEYPAD if the subscriber try to remove own keypad privilege * whereas it is not the keypad owner. */ T_RV_RET kpd_own_keypad( T_KPD_SUBSCRIBER subscriber, BOOL is_keypad_owner, T_KPD_VIRTUAL_KEY_TABLE* keys_owner_p); /** * function: kpd_set_key_config * * This function allows setting dynamically a configuration for new or existing virtual keys. * The two tables define a mapping between each entry (new_keys[1] is mapped with reference_keys[1], * new_keys[2] is mapped with reference_keys[2], ...). * The call of this function doesn't change the mode of the client. * * @param subscriber Subscriber identification value. * @param reference_keys_p Set of keys available on keypad in default mode. * @param new_keys_p Set of keys which must map with the reference keys. * @return * - RV_OK if operation is successfull, * - RV_INVALID_PARAMETER if : * - subscriber identification is incorrect, * - at least one reference key is not defined in the default mode, * - number of virtual keys is incorrect (in reference keys or new keys table, * - RV_NOT_SUPPORTED if configurable mode is not supported. * - RV_MEMORY_ERR if memory reach its size limit. * * Message returned: KPD_STATUS_MSG with operation = KPD_SET_CONFIG_MODE_OP. * Available values for status_value are: * - KPD_PROCESS_OK if asynchronous operation is successfull, * - KPD_ERR_CONFIG_MODE_USED if config mode is used by some subscribers. */ T_RV_RET kpd_set_key_config(T_KPD_SUBSCRIBER subscriber, T_KPD_VIRTUAL_KEY_TABLE* reference_keys_p, T_KPD_VIRTUAL_KEY_TABLE* new_keys_p); /** * function: kpd_get_available_keys * * This function allows knowing all the available keys in default mode. * * @param available_keys_p Set of keys available on keypad in default mode. The structure * must be declared by the caller, and is filled by the function (OUT). * @return RV_OK. */ T_RV_RET kpd_get_available_keys( T_KPD_VIRTUAL_KEY_TABLE* available_keys_p); /** * function: kpd_get_ascii_key_code * * This function return associated ASCII value to defined key. * * @param key Key identification value. * @param mode Mode in which is defined the link between "key" and "ascii code". * @param ascii_code Associated ASCII code to parameter "key" (OUT). * @return * - RV_OK if operation is successfull, * - RV_INVALID_PARAMETER if : * - mode is different of KPD_DEFAULT_MODE or KPD_ALPHANUMERIC_MODE, * - the key doesn't exist in the defined mode. * * @note If return value is RV_INVALID_PARAMETER, empty string is set in ascii_code_pp variable. */ T_RV_RET kpd_get_ascii_key_code( T_KPD_VIRTUAL_KEY_ID key, T_KPD_MODE mode, char** ascii_code_pp); /** * function: KP_Init * * This function is defined for backward compatibility with Condat. * It register two functions which notify Condat that Power key is long pressed. * It is used by PWR SWE. * * @param pressed Callback function to notify that Power key is long pressed. * @param released Callback function to notify that Power key is released. */ void KP_Init( void(pressed(T_KPD_VIRTUAL_KEY_ID)), void(released(void)) ); /*@}*/ /*************************************************************************/ /************************** MESSAGES DEFINITION **************************/ /*************************************************************************/ /** * The message offset must differ for each SWE in order to have * unique msg_id in the system. */ #define KPD_MESSAGES_OFFSET (0x36 << 10) /** * @name KPD_KEY_EVENT_MSG * * This message is sent to a subscriber when a key is pressed or released. * * Message issued by KPD to a subscriber. */ /*@{*/ /** Definition of the key state (pressed or released). */ typedef UINT8 T_KPD_KEY_STATE; /** Definition of the key press state (first press, long press, repeat press). */ typedef UINT8 T_KPD_PRESS_STATE; /** Information sent to a client for a key notification. */ typedef struct { T_KPD_VIRTUAL_KEY_ID virtual_key_id; T_KPD_KEY_STATE state; T_KPD_PRESS_STATE press_state; char* ascii_value_p; } T_KPD_KEY_INFO; /** Allowed values for T_KPD_KEY_STATE type. */ #define KPD_KEY_PRESSED (0) /** Allowed values for T_KPD_KEY_STATE type. */ #define KPD_KEY_RELEASED (1) /** Allowed value for T_KPD_PRESS_STATE type. */ #define KPD_FIRST_PRESS (0) /** Allowed value for T_KPD_PRESS_STATE type. */ #define KPD_LONG_PRESS (1) /** Allowed value for T_KPD_PRESS_STATE type. */ #define KPD_REPEAT_PRESS (2) /** Allowed value for T_KPD_PRESS_STATE type (when state==KPD_KEY_RELEASED). */ #define KPD_INSIGNIFICANT_VALUE (0xff) /** Message ID. */ #define KPD_KEY_EVENT_MSG (KPD_MESSAGES_OFFSET | 0x001) /** Message structure. */ typedef struct { /** Message header. */ T_RV_HDR hdr; /** Informations about key event. */ T_KPD_KEY_INFO key_info; } T_KPD_KEY_EVENT_MSG; /*@}*/ /** * @name KPD_STATUS_MSG * * Status message. * * Message issued by KPD to a subscriber. * This message is used to return the status of an asynchronous process * requested by a subscriber. */ /*@{*/ /* Allowed values for 'operation" field */ #define KPD_SUBSCRIBE_OP 1 #define KPD_REPEAT_KEYS_OP 2 #define KPD_CHANGE_MODE_OP 3 #define KPD_OWN_KEYPAD_OP 4 #define KPD_SET_CONFIG_MODE_OP 5 /* Available values for "status_value" field */ /* This define value is set when asynchronous process is successfull. */ #define KPD_PROCESS_OK 1 /* This define value is set in a status message (KPD_STATUS_MSG) when a client try to subscribe whereas keypad is in single-notified mode. Subscription is so rejected. */ #define KPD_ERR_SN_MODE 2 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client try to modify configuration mode whereas this mode is already used. */ #define KPD_ERR_CONFIG_MODE_USED 3 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client try to change keypad state from single-notified to multi-notified whereas it is not the keypad owner. */ #define KPD_ERR_ID_OWNER_KEYPAD 4 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client defines a key table which is not correct. */ #define KPD_ERR_KEYS_TABLE 5 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client try to subscribe to the keypad driver with a return path which is already defined by another subscriber. */ #define KPD_ERR_RETURN_PATH_EXISTING 6 /* This defined value is set in a status message (KPD_STATUS_MSG) when an internal error cause the failure of the process. */ #define KPD_ERR_INTERNAL 7 /** Message ID. */ #define KPD_STATUS_MSG (KPD_MESSAGES_OFFSET | 0x002) /** Message structure. */ typedef struct { /** Message header. */ T_RV_HDR hdr; /** Operation. */ UINT8 operation; /** Return status value. */ UINT8 status_value; } T_KPD_STATUS_MSG; /*@}*/ #endif /* #ifndef _KPD_API_H_ */