btif/include/btif_sm.h

   1 /******************************************************************************
   2  *
   3  *  Copyright (C) 2009-2012 Broadcom Corporation
   4  *
   5  *  Licensed under the Apache License, Version 2.0 (the "License");
   6  *  you may not use this file except in compliance with the License.
   7  *  You may obtain a copy of the License at:
   8  *
   9  *  http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software
  12  *  distributed under the License is distributed on an "AS IS" BASIS,
  13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *  See the License for the specific language governing permissions and
  15  *  limitations under the License.
  16  *
  17  ******************************************************************************/
  18
  19 /*****************************************************************************
  20  *
  21  *  Filename:      btif_sm.h
  22  *
  23  *  Description:   Generic BTIF state machine API
  24  *
  25  *****************************************************************************/
  26
  27 #ifndef BTIF_SM_H
  28 #define BTIF_SM_H
  29
  30 /*****************************************************************************
  31 **  Constants & Macros
  32 ******************************************************************************/
  33
  34 /* Generic Enter/Exit state machine events */
  35 #define BTIF_SM_ENTER_EVT 0xFFFF
  36 #define BTIF_SM_EXIT_EVT  0xFFFE
  37
  38
  39 /*****************************************************************************
  40 **  Type definitions and return values
  41 ******************************************************************************/
  42 typedef UINT32 btif_sm_state_t;
  43 typedef UINT32 btif_sm_event_t;
  44 typedef void* btif_sm_handle_t;
  45 typedef BOOLEAN(*btif_sm_handler_t)(btif_sm_event_t event, void *data);
  46
  47
  48 /*****************************************************************************
  49 **  Functions
  50 **
  51 **  NOTE: THESE APIs SHOULD BE INVOKED ONLY IN THE BTIF CONTEXT
  52 **
  53 ******************************************************************************/
  54
  55 /*****************************************************************************
  56 **
  57 ** Function     btif_sm_init
  58 **
  59 ** Description  Initializes the state machine with the state handlers
  60 **              The caller should ensure that the table and the corresponding
  61 **              states match. The location that 'p_handlers' points to shall
  62 **              be available until the btif_sm_shutdown API is invoked.
  63 **
  64 ** Returns      Returns a pointer to the initialized state machine handle.
  65 **
  66 ******************************************************************************/
  67 btif_sm_handle_t btif_sm_init(const btif_sm_handler_t *p_handlers,
  68                                btif_sm_state_t initial_state);
  69
  70 /*****************************************************************************
  71 **
  72 ** Function     btif_sm_shutdown
  73 **
  74 ** Description  Tears down the state machine
  75 **
  76 ** Returns      None
  77 **
  78 ******************************************************************************/
  79 void btif_sm_shutdown(btif_sm_handle_t handle);
  80
  81 /*****************************************************************************
  82 **
  83 ** Function     btif_sm_get_state
  84 **
  85 ** Description  Fetches the current state of the state machine
  86 **
  87 ** Returns      Current state
  88 **
  89 ******************************************************************************/
  90 btif_sm_state_t btif_sm_get_state(btif_sm_handle_t handle);
  91
  92 /*****************************************************************************
  93 **
  94 ** Function     btif_sm_dispatch
  95 **
  96 ** Description  Dispatches the 'event' along with 'data' to the current state handler
  97 **
  98 ** Returns      Returns BT_STATUS_OK on success, BT_STATUS_FAIL otherwise
  99 **
 100 ******************************************************************************/
 101 bt_status_t btif_sm_dispatch(btif_sm_handle_t handle, btif_sm_event_t event,
 102                                 void *data);
 103
 104 /*****************************************************************************
 105 **
 106 ** Function     btif_sm_change_state
 107 **
 108 ** Description  Make a transition to the new 'state'. The 'BTIF_SM_EXIT_EVT'
 109 **              shall be invoked before exiting the current state. The
 110 **              'BTIF_SM_ENTER_EVT' shall be invoked before entering the new state
 111 **
 112 **
 113 ** Returns      Returns BT_STATUS_OK on success, BT_STATUS_FAIL otherwise
 114 **
 115 ******************************************************************************/
 116 bt_status_t btif_sm_change_state(btif_sm_handle_t handle, btif_sm_state_t state);
 117
 118 #endif /* BTIF_SM_H */