plugins/iwmx.h

   1 /*
   2  *
   3  *  Connection Manager
   4  *
   5  *  Copyright (C) 2007-2009  Intel Corporation. All rights reserved.
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License version 2 as
   9  *  published by the Free Software Foundation.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  */
  21
  22 /*
  23  *
  24  * The plugin is broken in two main parts: the glue to connman
  25  * (iwmx_cm_*() functions) and the glue to the libiWmxSdk (iwmx_sdk_*()
  26  * functions). They connect using a well defined interface.
  27  *
  28  * The plugin is state based and operates reactively to state
  29  * transtitions on the WiMAX device or to user requests, even from
  30  * external control tools that are not aware of connman.
  31  *
  32  * When the user requests connman to do something, it goes into a call
  33  * implemented by the 'struct connman_driver iwmx_cm_driver' (or
  34  * iwmx_cm_network_driver) that will instruct libiWmxSDK to change the
  35  * device's state.
  36  *
  37  * When the device changes state, a state change callback is sent back
  38  * by libiWmxSDK, which gets fed to iwmx_cm_state_change(), which
  39  * evaluates the state change and updates connman's internal state in
  40  * response.
  41  *
  42  * This allows the device to be also controlled by external tools
  43  * without driving connman out of state.
  44  *
  45  * Device's state changes can be caused through:
  46  *
  47  *  - connman (by user request)
  48  *
  49  *  - any other external utility (eg: WmxSDK's wimaxcu)
  50  *
  51  *  - external stimuli: network connection broken when going out of
  52  *    range
  53  *
  54  * Functions named __*() normally indicate that require locking. See
  55  * their doc header.
  56  *
  57  * ENUMERATION
  58  *
  59  * When we receive a normal probe request [iwmx_cm_probe()] from
  60  * connman, we ignore it (we can tell based on the connman device
  61  * having NULL data).
  62  *
  63  * The plugin has registered with the WiMAX Network Service and it
  64  * will listen to its device add/rm messages [iwmx_sdk_addremove_cb()]
  65  * and use that to create a  device [iwmx_sdk_dev_add()] which will be
  66  * registered with connman. [iwmx_cm_dev_add()]. Then connman will
  67  * enumerate the device, call again iwmx_cm_probe() and at this time,
  68  * we'll recognize it, pass through iwmx_sdk_setup() and complete the
  69  * probe process.
  70  *
  71  * If the daemon dies, in theory the plugin will realize and remove
  72  * the WiMAX device.
  73  */
  74
  75 struct wmxsdk {
  76         struct WIMAX_API_DEVICE_ID device_id;
  77         struct connman_device *dev;
  78
  79         GStaticMutex network_mutex;
  80
  81         WIMAX_API_DEVICE_STATUS status;
  82         GMutex *status_mutex;
  83
  84         /*
  85          * nw points to the network we are connected to. connecting_nw
  86          * points to the network we have requested to connect.
  87          */
  88         GMutex *connect_mutex;
  89         struct connman_network *connecting_nw, *nw;
  90
  91         char name[100];
  92         char ifname[16];
  93 };
  94
  95 /* Initialize a [zeroed] struct wmxsdk */
  96 static inline void wmxsdk_init(struct wmxsdk *wmxsdk)
  97 {
  98         g_static_mutex_init(&wmxsdk->network_mutex);
  99
 100         wmxsdk->status = WIMAX_API_DEVICE_STATUS_UnInitialized;
 101         wmxsdk->status_mutex = g_mutex_new();
 102         g_assert(wmxsdk->status_mutex);
 103
 104         wmxsdk->connect_mutex = g_mutex_new();
 105         g_assert(wmxsdk->connect_mutex);
 106 }
 107
 108 /* Misc utilities */
 109 #define ARRAY_SIZE(a) (sizeof(a)/sizeof(a[0]))
 110 #define container_of(pointer, type, member)                             \
 111 ({                                                                      \
 112         type *object = NULL;                                            \
 113         size_t offset = (void *) &object->member - (void *) object;     \
 114         (type *) ((void *) pointer - offset);                           \
 115 })
 116
 117 /* Misc values */
 118 enum {
 119         /**
 120          * Time we wait for callbacks: 5s
 121          *
 122          * I know, it is huge, but L4 and the device sometimes take
 123          * some time, especially when there is crypto involved.
 124          */
 125         IWMX_SDK_L4_TIMEOUT_US = 5 * 1000 * 1000,
 126
 127         /*
 128          * WARNING!!!!!
 129          *
 130          * ONLY ONE DEVICE SUPPORTED
 131          *
 132          * - on removal, there is no way to know which device was
 133          *   removed (the removed device is removed from the list and
 134          *   the callback doesn't have any more information than the
 135          *   index in the list that getlistdevice would return -- racy
 136          *   as hell).
 137          *
 138          * - on insertion, there is not enough information provided.
 139          */
 140         IWMX_SDK_DEV_MAX = 1,
 141 };
 142
 143 struct connman_network *__iwmx_cm_network_available(
 144                         struct wmxsdk *wmxsdk, const char *station_name,
 145                         const char *station_type,
 146                         const void *sdk_nspname, size_t sdk_nspname_size,
 147                                                                 int strength);
 148
 149 struct connman_network *iwmx_cm_network_available(
 150                         struct wmxsdk *wmxsdk, const char *station_name,
 151                         const char *station_type,
 152                         const void *sdk_nspname, size_t sdk_nspname_size,
 153                                                                 int strength);
 154
 155 WIMAX_API_DEVICE_STATUS iwmx_cm_status_get(struct wmxsdk *wmxsdk);
 156 void __iwmx_cm_state_change(struct wmxsdk *wmxsdk,
 157                                         WIMAX_API_DEVICE_STATUS __new_status);
 158 void iwmx_cm_state_change(struct wmxsdk *wmxsdk,
 159                                         WIMAX_API_DEVICE_STATUS __new_status);
 160
 161 int iwmx_sdk_connect(struct wmxsdk *wmxsdk, struct connman_network *nw);
 162 int iwmx_sdk_disconnect(struct wmxsdk *wmxsdk);
 163 struct connman_network *__iwmx_sdk_get_connected_network(struct wmxsdk *wmxsdk);
 164 const char *iwmx_sdk_dev_status_to_str(WIMAX_API_DEVICE_STATUS status);
 165 int iwmx_sdk_rf_state_set(struct wmxsdk *wmxsdk, WIMAX_API_RF_STATE rf_state);
 166 WIMAX_API_DEVICE_STATUS iwmx_sdk_get_device_status(struct wmxsdk *wmxsdk);
 167 int iwmx_sdk_setup(struct wmxsdk *wmxsdk);
 168 void iwmx_sdk_remove(struct wmxsdk *wmxsdk);
 169 int iwmx_sdk_scan(struct wmxsdk *wmxsdk);
 170 int iwmx_sdk_api_init(void);
 171 void iwmx_sdk_api_exit(void);