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 #include <hardware/bluetooth.h>
  31
  32 #include "stack/include/bt_types.h"
  33
  34 /*****************************************************************************
  35 **  Constants & Macros
  36 ******************************************************************************/
  37
  38 /* Generic Enter/Exit state machine events */
  39 #define BTIF_SM_ENTER_EVT 0xFFFF
  40 #define BTIF_SM_EXIT_EVT  0xFFFE
  41
  42 /*****************************************************************************
  43 **  Type definitions and return values
  44 ******************************************************************************/
  45 typedef UINT32 btif_sm_state_t;
  46 typedef UINT32 btif_sm_event_t;
  47 typedef void* btif_sm_handle_t;
  48 typedef BOOLEAN(*btif_sm_handler_t)(btif_sm_event_t event, void *data);
  49
  50 /*****************************************************************************
  51 **  Functions
  52 **
  53 **  NOTE: THESE APIs SHOULD BE INVOKED ONLY IN THE BTIF CONTEXT
  54 **
  55 ******************************************************************************/
  56
  57 /*****************************************************************************
  58 **
  59 ** Function     btif_sm_init
  60 **
  61 ** Description  Initializes the state machine with the state handlers
  62 **              The caller should ensure that the table and the corresponding
  63 **              states match. The location that 'p_handlers' points to shall
  64 **              be available until the btif_sm_shutdown API is invoked.
  65 **
  66 ** Returns      Returns a pointer to the initialized state machine handle.
  67 **
  68 ******************************************************************************/
  69 btif_sm_handle_t btif_sm_init(const btif_sm_handler_t *p_handlers,
  70                                btif_sm_state_t initial_state);
  71
  72 /*****************************************************************************
  73 **
  74 ** Function     btif_sm_shutdown
  75 **
  76 ** Description  Tears down the state machine
  77 **
  78 ** Returns      None
  79 **
  80 ******************************************************************************/
  81 void btif_sm_shutdown(btif_sm_handle_t handle);
  82
  83 /*****************************************************************************
  84 **
  85 ** Function     btif_sm_get_state
  86 **
  87 ** Description  Fetches the current state of the state machine
  88 **
  89 ** Returns      Current state
  90 **
  91 ******************************************************************************/
  92 btif_sm_state_t btif_sm_get_state(btif_sm_handle_t handle);
  93
  94 /*****************************************************************************
  95 **
  96 ** Function     btif_sm_dispatch
  97 **
  98 ** Description  Dispatches the 'event' along with 'data' to the current state handler
  99 **
 100 ** Returns      Returns BT_STATUS_OK on success, BT_STATUS_FAIL otherwise
 101 **
 102 ******************************************************************************/
 103 bt_status_t btif_sm_dispatch(btif_sm_handle_t handle, btif_sm_event_t event,
 104                                 void *data);
 105
 106 /*****************************************************************************
 107 **
 108 ** Function     btif_sm_change_state
 109 **
 110 ** Description  Make a transition to the new 'state'. The 'BTIF_SM_EXIT_EVT'
 111 **              shall be invoked before exiting the current state. The
 112 **              'BTIF_SM_ENTER_EVT' shall be invoked before entering the new state
 113 **
 114 **
 115 ** Returns      Returns BT_STATUS_OK on success, BT_STATUS_FAIL otherwise
 116 **
 117 ******************************************************************************/
 118 bt_status_t btif_sm_change_state(btif_sm_handle_t handle, btif_sm_state_t state);
 119
 120 #endif /* BTIF_SM_H */