src/phOsalNfc_Timer.h

   1 /*
   2  * Copyright (C) 2010 NXP Semiconductors
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * \file  phOsalNfc_Timer.h
  19  * \brief Timer Implementation.
  20  *
  21  * Project: NFC-FRI 1.1
  22  *
  23  * $Date: Mon Mar 16 20:30:44 2009 $
  24  * $Author: ing01697 $
  25  * $Revision: 1.19 $
  26  * $Aliases: NFC_FRI1.1_WK912_R21_1,NFC_FRI1.1_WK914_PREP1,NFC_FRI1.1_WK914_R22_1,NFC_FRI1.1_WK914_R22_2,NFC_FRI1.1_WK916_R23_1,NFC_FRI1.1_WK918_R24_1,NFC_FRI1.1_WK920_PREP1,NFC_FRI1.1_WK920_R25_1,NFC_FRI1.1_WK922_PREP1,NFC_FRI1.1_WK922_R26_1,NFC_FRI1.1_WK924_PREP1,NFC_FRI1.1_WK924_R27_1,NFC_FRI1.1_WK926_R28_1,NFC_FRI1.1_WK928_R29_1,NFC_FRI1.1_WK930_R30_1,NFC_FRI1.1_WK934_PREP_1,NFC_FRI1.1_WK934_R31_1,NFC_FRI1.1_WK941_PREP1,NFC_FRI1.1_WK941_PREP2,NFC_FRI1.1_WK941_1,NFC_FRI1.1_WK943_R32_1,NFC_FRI1.1_WK949_PREP1,NFC_FRI1.1_WK943_R32_10,NFC_FRI1.1_WK943_R32_13,NFC_FRI1.1_WK943_R32_14,NFC_FRI1.1_WK1007_R33_1,NFC_FRI1.1_WK1007_R33_4,NFC_FRI1.1_WK1017_PREP1,NFC_FRI1.1_WK1017_R34_1,NFC_FRI1.1_WK1017_R34_2,NFC_FRI1.1_WK1023_R35_1 $
  27  *
  28  */
  29 #ifndef PHOSALNFC_TIMER_H
  30 #define PHOSALNFC_TIMER_H
  31
  32 /* -----------------Include files ---------------------------------------*/
  33 #include <phNfcTypes.h>
  34 #ifdef PH_NFC_CUSTOMINTEGRATION
  35 #include <phNfcCustomInt.h>
  36 #else
  37 #ifdef NXP_MESSAGING
  38 #include <nfc_osal_deferred_call.h>
  39 #endif
  40
  41 #ifdef NXP_MESSAGING
  42 /**
  43  * \ingroup grp_osal_nfc
  44  *\brief Deferred message specific info declaration.
  45  * This type information packed as WPARAM  when \ref PH_OSALNFC_MESSAGE_BASE type windows message
  46  * is posted to message handler thread.
  47  */
  48 //typedef struct phOsalNfc_DeferedCalldInfo
  49 //{
  50 //              nfc_osal_def_call_t  pDeferedCall;/**< pointer to Deferred callback */
  51 //              void                            *pParam;/**< contains timer message specific details*/
  52 //}phOsalNfc_DeferedCalldInfo_t;
  53 typedef phLibNfc_DeferredCall_t phOsalNfc_DeferedCalldInfo_t;
  54 #endif
  55
  56 /* ---------------- Macros ----------------------------------------------*/
  57 /**
  58 *\ingroup grp_osal_nfc
  59 * OSAL timer message .This message type will be posted to calling application thread.
  60 */
  61 //#define PH_OSALNFC_TIMER_MSG                    (0x315)
  62 #define PH_OSALNFC_TIMER_MSG                      PH_LIBNFC_DEFERREDCALL_MSG
  63
  64 /**
  65  * \ingroup grp_osal_nfc
  66  * Invalid timer ID type.This ID used indicate timer creation is failed.
  67  */
  68 #define PH_OSALNFC_INVALID_TIMER_ID               (0xFFFF)
  69
  70 /*!
  71  * \ingroup grp_osal_nfc
  72  * \brief Timer callback interface which will be called once registered timer
  73  * timeout expires.
  74  * \param[in] TimerId  Timer Id for which callback is called.
  75  * \retval  None
  76  */
  77 typedef void (*ppCallBck_t)(uint32_t TimerId, void *pContext);
  78
  79 /* -----------------Structures and Enumerations -------------------------*/
  80 /**
  81  * \ingroup grp_osal_nfc
  82  **\brief Timer message structure definition.
  83  * Timer Message Structure contains timer specific informations like timer identifier
  84  * and timer callback.
  85  *
  86  */
  87 typedef struct phOsalNfc_TimerMsg
  88 {
  89    uint32_t                     TimerId;/**< Timer ID*/
  90    ppCallBck_t          pCallBck;/**< pointer to Timer Callback*/
  91    void*                        pContext;   /**< Timer Callback context*/
  92 }phOsalNfc_Timer_Msg_t,*pphOsalNfc_TimerMsg_t;
  93
  94 /* -----------------Exported Functions----------------------------------*/
  95 /**
  96  * \ingroup grp_osal_nfc
  97  * \brief Allows to create new timer.
  98  *
  99  * This API creates a cyclic timer. In case a valid timer is created returned
 100  * timer ID will be other than \ref PH_OSALNFC_INVALID_TIMER_ID. In case returned
 101  * timer id is \ref PH_OSALNFC_INVALID_TIMER_ID, this indicates timer creation
 102  * has failed.
 103  *
 104  * When a timer is created, it is not started by default. The application has to
 105  * explicitly start it using \ref phOsalNfc_Timer_Start().
 106  *
 107  * \param[in] void
 108  * \retval Created timer ID.
 109  * \note If timer ID value is PH_OSALNFC_INVALID_TIMER_ID, it indicates
 110  * an error occured during timer creation.
 111  *
 112  * \msc
 113  *  Application,phOsalNfc;
 114  *  Application=>phOsalNfc [label="phOsalNfc_Timer_Create()",URL="\ref phOsalNfc_Timer_Create"];
 115  *  Application<<phOsalNfc [label="Returns Valid timer ID"];
 116  * \endmsc
 117  */
 118 uint32_t phOsalNfc_Timer_Create (void);
 119
 120 /**
 121  * \ingroup grp_osal_nfc
 122  * \brief Allows to start an already created timer.
 123  *
 124  * This function starts the requested timer. If the timer is already running,
 125  * timer stops and restarts with the new timeout value and new callback function
 126  * in case any.
 127  *
 128  * \note The old timeout and callback reference are not valid any more if timer
 129  * is restarted. Notifications are periodic and stop only when timer is stopped.
 130  *
 131  * \param[in]  TimerId          valid timer ID obtained during timer creation.
 132  * \param[in]  RegTimeCnt       Requested time out in Milliseconds.
 133  * \note  In windows environment timer resolution should be more than
 134  *        50 mSec. In case time out value is below 50 mSec accuracy of timer
 135  *        behaviouer is not gauranteed.
 136  * \param[in]  Application_callback  Application Callback interface to be called
 137  * when timer expires.
 138  *
 139  * \msc
 140  *  Application,phOsalNfc;
 141  *  Application=>phOsalNfc [label="phOsalNfc_Timer_Create()", URL="\ref phOsalNfc_Timer_Create"];
 142  *  Application<<phOsalNfc [label="TIMERID"];
 143  *  Application=>phOsalNfc [label="phOsalNfc_Timer_Start(TIMERID, TIMEOUT, CB)", URL="\ref phOsalNfc_Timer_Start"];
 144  *  --- [label=" : On timer time out expired "];
 145  *  phOsalNfc=>phOsalNfc [label="CB()"];
 146  *  Application<-phOsalNfc[label="PH_OSALNFC_TIMER_MSG"];
 147  * \endmsc
 148  */
 149 void phOsalNfc_Timer_Start(uint32_t     TimerId,
 150                            uint32_t     RegTimeCnt,
 151                            ppCallBck_t  Application_callback,
 152                            void         *pContext);
 153
 154 /**
 155  * \ingroup grp_osal_nfc
 156  * \brief Stop an already started timer.
 157  *
 158  * This API allows to stop running timers. In case the timer is stopped, its callback will not be
 159  * notified any more.
 160  *
 161  * \param[in] TimerId               valid timer ID obtained suring timer creation.
 162  * \param[in] Application_callback   Application Callback interface to be called when timer expires.
 163  *
 164  * \msc
 165  *  Application,phOsalNfc;
 166  *  Application=>phOsalNfc [label="phOsalNfc_Timer_Create()",URL="\ref phOsalNfc_Timer_Create"];
 167  *  Application<<phOsalNfc [label="TIMERID"];
 168  *  Application=>phOsalNfc [label="phOsalNfc_Timer_Start(TIMERID, TIMEOUT, CB)",URL="\ref phOsalNfc_Timer_Start"];
 169  *  --- [label=" : On timer time out expired "];
 170  *  phOsalNfc=>phOsalNfc [label="CB()"];
 171  *  Application=>phOsalNfc [label="phOsalNfc_Timer_Stop(TIMERID)",URL="\ref phOsalNfc_Timer_Stop"];
 172  \endmsc
 173  */
 174 void phOsalNfc_Timer_Stop(uint32_t TimerId);
 175
 176 /**
 177  * \ingroup grp_osal_nfc
 178  * \brief Allows to delete the timer which is already created.
 179  *
 180  * This API allows to delete a timer. Incase timer is running
 181  * it is stopped first and then deleted. if the given timer ID is invalid, this
 182  * function doesn't return any error. Application has to explicitly ensure
 183  * timer ID sent is valid.
 184  *
 185  * \param[in]  TimerId  timer identieir to delete the timer.
 186  */
 187 void phOsalNfc_Timer_Delete(uint32_t TimerId);
 188
 189 #endif
 190 #endif /* PHOSALNFC_TIMER_H */