resource/csdk/connectivity/src/bt_le_adapter/linux/utils.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_UTILS_H
  20 #define CA_BLE_LINUX_UTILS_H
  21
  22 #include "context.h"
  23
  24
  25 /**
  26  * Proxy retrieval filter function type.
  27  *
  28  * A function that implements this interface may be passed to
  29  * @c CAGetBlueZManagedObjectProxies() to filter proxies to be added
  30  * to the returned list.
  31  *
  32  * @return @c true if the proxy should be added to the proxy list,
  33  *         @c false otherwise.
  34  */
  35 typedef bool(*CALEProxyFilter)(GDBusProxy * proxy);
  36
  37 /**
  38  * Get information for all BlueZ managed objects with a given
  39  * interface.
  40  *
  41  * @param[out] proxies   List containing @a proxies (@c GDBusProxy)
  42  *                       for all found BlueZ objects that match the
  43  *                       given D-Bus @a interface.
  44  * @param[in]  interface D-Bus interface of BlueZ object for which a
  45  *                       proxy will be created.
  46  * @param[in]  context   BLE Linux adapter context.
  47  * @param[in]  filter    Filter function used to determine whether or
  48  *                       not a proxy retrieved from the BlueZ
  49  *                       @c ObjectManager should be added to the
  50  *                       returned @a proxies list.
  51  *
  52  * @return @c true if objects were found.
  53  */
  54 bool CAGetBlueZManagedObjectProxies(GList ** proxies,
  55                                     char const * interface,
  56                                     CALEContext * context,
  57                                     CALEProxyFilter filter);
  58
  59
  60 /**
  61  * Get the proxy to a object that implements the given D-Bus
  62  * @a interface.
  63  *
  64  * @param[in] tuple      A D-Bus tuple that contains the D-Bus object
  65  *                       path and corresponding dictionary of
  66  *                       properties, i.e. with the format specifier
  67  *                       @c "(oa{sv})".
  68  * @param[in] interface  The D-Bus interface in which we're
  69  *                       interested.  A @c GDBusProxy object will be
  70  *                       create using the properties found in the
  71  *                       dictionary item whose key matches this
  72  *                       interface name.
  73  * @param[in] manager    The D-Bus object manager that contains the
  74  *                       information about the object in question.
  75  */
  76 GDBusProxy * CAGetBlueZInterfaceProxy(GVariant * tuple,
  77                                       char const * interface,
  78                                       GDBusObjectManager * object_manager);
  79
  80 /**
  81  * Set @a property on BlueZ object to given @a value.
  82  *
  83  * Using the @c org.freedesktop.DBus.Properties.Set() method
  84  * implemented by BlueZ objects, set the desired @a property on the
  85  * object pointed to by @a proxy to the given @a value.
  86  *
  87  * @param[in] proxy     D-Bus proxy to the BlueZ object.
  88  * @param[in] interface Interface name of the object on which the
  89  *                      property is being set.
  90  * @param[in] property  Property name.
  91  * @param[in] value     Property value.  Ownership is transferred from
  92  *                      the caller.
  93  */
  94 bool CASetBlueZObjectProperty(GDBusProxy * proxy,
  95                               char const * interface,
  96                               char const * property,
  97                               GVariant * value);
  98
  99 /**
 100  * D-Bus skeleton propery name/value pair.
 101  *
 102  * This name value pair will be used when constructing the property
 103  * dictionary embedded in
 104  * @c org.freedesktop.DBus.ObjectManager.GetManagedObjects() results.
 105  */
 106 typedef struct _CADBusSkeletonProperty
 107 {
 108     /// Property name.
 109     char const * const name;
 110
 111     /**
 112      * Property value.
 113      *
 114      * @c Ownership is transferred to the function this variant passed
 115      * to.
 116      */
 117     GVariant * const value;
 118 } CADBusSkeletonProperty;
 119
 120 /**
 121  * Construct property dictionary suitable for place in ObjectManager
 122  * results.
 123  *
 124  * @param[in] interface_name The name of the interface to which the
 125  *                           properties correspond.
 126  * @param[in] properties     Array of property name/value pairs.
 127  *                           Ownership of the value variant will be
 128  *                           transferred to this function.
 129  * @param[in] count          Number of elements in the @a properties
 130  *                           array.
 131  *
 132  * @return A variant of the form a{sa{sv}}, suitable for use in the
 133  *         results of
 134  *         @c org.freedesktop.DBus.ObjectManager.GetManagedObjects()
 135  *         or @c org.freedesktop.DBus.Properties.GetAll() method
 136  *         implementations.
 137  *
 138  * @note Ownership of the returned @c GVariant is transferred to the
 139  *       caller.
 140  */
 141 GVariant * CAMakePropertyDictionary(
 142     char const * interface_name,
 143     CADBusSkeletonProperty const * properties,
 144     size_t count);
 145
 146
 147 #endif  // CA_BLE_LINUX_UTILS_H