kpd_api.h

是一个手机功能的模拟程序

/**
 * @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 ([e-mail])
 * @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_cfg.h"

#include "rv_general.h"
#include "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.