resource/csdk/connectivity/src/bt_le_adapter/linux/peripheral.h

   1 /******************************************************************
   2  *
   3  * Copyright 2015 Intel Corporation All Rights Reserved.
   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 #ifndef CA_BLE_LINUX_PERIPHERAL_H
  20 #define CA_BLE_LINUX_PERIPHERAL_H
  21
  22 #include "context.h"
  23 #include "advertisement.h"
  24
  25 #include "cacommon.h"
  26
  27
  28 /**
  29  * @internal
  30  *
  31  * Linux BLE "peripheral" context.
  32  */
  33 typedef struct _CAPeripheralContext
  34 {
  35     /**
  36      * Base context.
  37      *
  38      * The base context contains core state used throughout the Linux
  39      * BLE adapter implementation.
  40      */
  41     CALEContext * base;
  42
  43     /// D-Bus bus name owner ID.
  44     guint owner_id;
  45
  46     /**
  47      * LE advertising information.
  48      *
  49      * The LE advertising information will be registered with BlueZ,
  50      * which BlueZ will then use to add advertising data to each of
  51      * the detected Bluetooth hardware adapters.  Only one set of
  52      * advertising data is needed since the data is the same for all
  53      * adapters.
  54      */
  55     CALEAdvertisement advertisement;
  56
  57     /**
  58      * List of @c CAGattService objects containing information for all
  59      * exported and registered IoTivity BlueZ GATT related D-Bus
  60      * objects.
  61      */
  62     GList * gatt_services;
  63
  64     /**
  65      * Glib event loop that drives peripheral D-Bus signal
  66      * handling.
  67      *
  68      * @note A seperate thread drives this event loop.  This is
  69      *       necessitated by the need for signal subscriptions to be
  70      *       done in what the GLib documentation refers to as the
  71      *       "thread-default main context".  By the time the
  72      *       peripheral is started it's too late the use the main loop
  73      *       that was run when this Linux BLE transport adapter itself
  74      *       was started through @c CASelectNetwork() and the @c
  75      *       CAAdapterStart() callback the peripheral must have its
  76      *       own main loop.
  77      */
  78     GMainLoop * event_loop;
  79
  80     /// Mutex used to synchronize access to context fields.
  81     oc_mutex lock;
  82
  83     /**
  84      * Service registration condition variable.
  85      *
  86      * This condition variable is used to delay service registration
  87      * until the thread performing service initialization completes.
  88      * Initialization is performed in the same thread that will run
  89      * the peripheral's event loop.
  90      *
  91      * @see @c GMainLoop documentation for further details.
  92      */
  93     oc_cond condition;
  94
  95 } CAPeripheralContext;
  96
  97 /**
  98  * Initialize global state.
  99  */
 100 void CAPeripheralInitialize();
 101
 102 /**
 103  * Finalize global state.
 104  */
 105 void CAPeripheralFinalize();
 106
 107 /**
 108  * Initialize and start a Linux BLE "peripheral".
 109  *
 110  * Initialize all Linux BLE "peripheral" state (i.e. a global
 111  * @c CAPeripheralContext instance), as well as register the OIC
 112  * GATT transport service with BlueZ to begin advertising.
 113  *
 114  * @param[in] context Base context.
 115  *
 116  * @return @c CA_STATUS_OK on success.
 117  */
 118 CAResult_t CAPeripheralStart(CALEContext * context);
 119
 120 /**
 121  * Stop the Linux BLE "peripheral".
 122  *
 123  * @return @c CA_STATUS_OK on success.
 124  */
 125 CAResult_t CAPeripheralStop();
 126
 127 /**
 128  * Invoke function @a func for each registered GATT service.
 129  *
 130  * For each registered GATT service, invoke the function @a func,
 131  * where the first (data) paramter will be a pointer to the
 132  * ::CAGattService object, and the second will be the @a user_data
 133  * argument provided to this function call.
 134  *
 135  * @param[in] func      Function to be invoked for each
 136  *                      ::CAGattService.
 137  * @param[in] user_data User provided data passed as the second
 138  *                      argument to the function @a func.
 139  *
 140  * @note This function exists to avoid exposing the BLE peripheral
 141  *       internals.
 142  */
 143 void CAPeripheralForEachService(GFunc func, void * user_data);
 144
 145
 146 #endif  /* CA_BLE_LINUX_PERIPHERAL_H */