From af90caed6d360825587a3677f2a3a9213f271ba5 Mon Sep 17 00:00:00 2001 From: Wu Zheng Date: Mon, 16 May 2016 16:48:27 +0800 Subject: [PATCH] comms: Add so-connman API so-connman is for implementing connection manager features. The APIs should be implemented in Zephyr, connman and so on. To connman, the connman D-Bus APIs are wrapped in the so-connman APIs. The user can use the so-connman APIs to control connman. To invoke the D-Bus method of connman, the async call is used, the callback function is set to get the results of async call. The basic so-connman APIs are in the patch. It provides the APis of getting the name, ip address... of services. The service connect/disconnect APIs and set/get offline are implemented too. The further sol-connman APIs are being planned. Signed-off-by: Wu Zheng --- src/lib/comms/include/sol-netctl.h | 476 +++++++++++++++++++++++++++++ 1 file changed, 476 insertions(+) create mode 100644 src/lib/comms/include/sol-netctl.h diff --git a/src/lib/comms/include/sol-netctl.h b/src/lib/comms/include/sol-netctl.h new file mode 100644 index 000000000..78ce0c62d --- /dev/null +++ b/src/lib/comms/include/sol-netctl.h @@ -0,0 +1,476 @@ +/* + * This file is part of the Soletta Project + * + * Copyright (C) 2015 Intel Corporation. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +#include +#include +#include +#include +#include + + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @struct sol_netctl_service + * + * @brief service struct + */ +struct sol_netctl_service; + +/** + * @struct sol_netctl_network_params + * + * @brief network params + * + * This struct contains the information of a network. + * it has the addr of network link addr, the network of + * netmask and its gateway of network. + */ +struct sol_netctl_network_params { + /** + * @brief The network devices address + */ + struct sol_network_link_addr addr; + /** + * @brief The network devices netmask + */ + struct sol_network_link_addr netmask; + /** + * @brief The network gateway + */ + struct sol_network_link_addr gateway; +}; + +/** + * @enum sol_netctl_service_state + * + * @brief service state + * + * One of these must be chosen to set the state of service, + * with sol_netctl_service_get_state() + * + * @note SOL_NETCTL_SERVICE_STATE_REMOVE is used to show + * the service has been removed. When it is notified, + * the service has been removed in the system. + */ +enum sol_netctl_service_state { + /* + * @brief the service is unknow + * + * a service is unknow when the service is init + * and the service state can't be given. + */ + SOL_NETCTL_SERVICE_STATE_UNKNOWN = 0, + /* + * @brief the service is idle + * + * a service is idle when the service is not in use + * at all at the moment and it is not attempting to + * connect or do anything. + */ + SOL_NETCTL_SERVICE_STATE_IDLE, + /* + * @brief the service is association + * + * a service is association when the service tries to + * establish a low-level connection to the network. + */ + SOL_NETCTL_SERVICE_STATE_ASSOCIATION, + /* + * @brief the service is configuration + * + * a service is configuration when the service is trying to + * retrieve/configure IP settings. + */ + SOL_NETCTL_SERVICE_STATE_CONFIGURATION, + /* + * @brief the service is ready + * + * a service is ready when a successfully connected device. + */ + SOL_NETCTL_SERVICE_STATE_READY, + /* + * @brief the service is online + * + * a service is online when an internet connection is available + * and has been verified. + */ + SOL_NETCTL_SERVICE_STATE_ONLINE, + /* + * @brief the service is disconnect + * + * a service is disconnect when the service is going to terminate + * the current connection and will return to "idle". + */ + SOL_NETCTL_SERVICE_STATE_DISCONNECT, + /* + * @brief the service is failure + * + * a service is failure when the service indicates a wrong behavior. + */ + SOL_NETCTL_SERVICE_STATE_FAILURE, + /* + * @brief the service is remove + * + * a service is remove when the service is not available and removed + * from the network system. At the same time, the service handle(pointer) + * will become invalid. + */ + SOL_NETCTL_SERVICE_STATE_REMOVE, +}; + +#define SOL_NETCTL_SERVICE_TYPE_ETHERNET "ethernet" /**< @brief ethernet service type string */ +#define SOL_NETCTL_SERVICE_TYPE_WIFI "wifi" /**< @brief wifi service type string */ +#define SOL_NETCTL_SERVICE_TYPE_BLUETOOTH "bluetooth" /**< @brief bluetooth service type string */ +#define SOL_NETCTL_SERVICE_TYPE_CELLULAR "cellular" /**< @brief bluetooth service type string */ +#define SOL_NETCTL_SERVICE_TYPE_GPS "gps" /**< @brief gps service type string */ +#define SOL_NETCTL_SERVICE_TYPE_VPN "vpn" /**< @brief vpn service type string */ +#define SOL_NETCTL_SERVICE_TYPE_GADGET "gadget" /**< @brief gadget service type string */ +#define SOL_NETCTL_SERVICE_TYPE_P2P "p2p" /**< @brief p2p service type string */ + +/** + * @enum sol_netctl_state + * + * @brief the global connection state of system + * + * One of these must be chosen for the global connection state, + * with sol_netctl_get_state() + * + */ +enum sol_netctl_state { + /* + * @brief the state is unknow + * + * a state is unknow when the state is init + * and the state can't be given. + */ + SOL_NETCTL_STATE_UNKNOWN = 0, + /* + * @brief the state is idle + * + * a state is idle when no serives is in either "ready" or "online" state. + */ + SOL_NETCTL_STATE_IDLE, + /* + * @brief the state is ready + * + * a state is ready when at least one service is in "ready" + * state and no service is in "online" state. + */ + SOL_NETCTL_STATE_READY, + /* + * @brief the state is online + * + * a state is online when at least one service is in "online". + */ + SOL_NETCTL_STATE_ONLINE, + /* + * @brief the state is offline + * + * a state is offline when the device is in offline mode and + * the user doesn't re-enable individual technologies like + * WiFi and Bluetooth while in offline mode. + */ + SOL_NETCTL_STATE_OFFLINE, +}; + +/** + * @brief Service monitor callback used to inform a service changed + * + * @param data the user data + * @param service the monitor service + */ +typedef void (*sol_netctl_service_monitor_cb) + (void *data, + const struct sol_netctl_service *service); + +/** + * @brief Manager monitor callback used to inform a manager updated + * + * @param data the user data + */ +typedef void (*sol_netctl_manager_monitor_cb)(void *data); + +/** + * @brief error monitor callback used to inform a call result + * + * @param data the user data + * @param service the activity service + * @param error the call result + */ +typedef void (*sol_netctl_error_monitor_cb) + (void *data, const struct sol_netctl_service *service, + unsigned int error); + +/** + * @brief Gets the service name + * + * This function gets the name for the connman service, + * after the service is to give by service monitor. + * + * @param service The service structure which the name is desired + * + * @return The name of the services on success, NULL on failure. + */ +const char *sol_netctl_service_get_name( + const struct sol_netctl_service *service); + +/** + * @brief Gets the service state + * + * This function gets the state for the connman service, + * after the service is to give by service monitor. + * + * @note SOL_NETCTL_SERVICE_STATE_REMOVE is used to show + * the service has been removed. When it is notified, + * the service has been removed in the system. + * + * @param service The service structure which the state is desired + * + * @return The state of the services on success, + * SOL_NETCTL_SERVICE_STATE_UNKNOWN on failure. + */ +enum sol_netctl_service_state sol_netctl_service_get_state( + const struct sol_netctl_service *service); + +/** + * @brief Gets the service type + * + * This function gets the type for the connman service, + * after the service is to give by service monitor. + * + * @param service The service structure which the type is desired + * + * @return The type of the services on success, NULL on failure. + */ +const char *sol_netctl_service_get_type( + const struct sol_netctl_service *service); + +/** + * @brief Gets the service network address + * + * This function gets the network address for the connman service, + * after the service is to give by service monitor. + * + * @param service The service structure which the network address is desired + * @param link The retrieved content + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_service_get_network_address( + const struct sol_netctl_service *service, struct sol_network_link **link); + +/** + * @brief Gets the service strength + * + * This function gets the service strength for the connman service, + * after the service is to give by service monitor. + * + * @param service The service structure which the service strength is + * desired + * + * @return 0-100 on success, -errno on failure. + */ +int32_t sol_netctl_service_get_strength( + const struct sol_netctl_service *service); + +/** + * @brief Gets the global connection state of system + * + * This function gets the global connection state for system, + * after the state is to give by manager monitor. + * This callback of sol_netctl_add_manager_monitor must be + * added BEFORE sol_netctl_get_state() is called + * to ensure no messages are lost. + * + * @return The state of the global connection state on success, + * SOL_NETCTL_STATE_UNKNOWN on failure + */ +enum sol_netctl_state sol_netctl_get_state(void); + +/** + * @brief Sets the global connection state to offline + * + * This function sets the global connection state to offline, + * enter offline Mode too. + * + * @param enabled The value is set for offline on/off + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_set_radios_offline(bool enabled); + +/** + * @brief Gets the global connection state of offline + * + * This function gets the global connection state of offline, + * after the state is to give by manager monitor. + * This callback of sol_netctl_add_manager_monitor must be + * added BEFORE sol_netctl_get_radios_offline() is called + * to ensure no messages are lost. + * + * @return True if the offline is enabled, false otherwise. + */ +bool sol_netctl_get_radios_offline(void); + +/** + * @brief Connect the service + * + * This function connects the service, after the service is to give by service monitor. + * Since the connman function is asynchronous, the return is not connection error, + * but just some dispatching/immediate error. The actual state change will be notified + * via sol_netctl_add_service_monitor() callbacks. The service connect error info will be + * notified by error monitor. This callbacks of sol_netctl_add_service_monitor and + * sol_netctl_add_error_monitor must be added BEFORE the sol_netctl_service_connect() + * is called to ensure no messages are lost. + * + * @param service The service structure which the connection is desired + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_service_connect(struct sol_netctl_service *service); + +/** + * @brief Disconnect the service + * + * This function disconnects the service. + * Since the connman function is asynchronous, the return is not disconnection error, + * but just some dispatching/immediate error. The actual state change will be notified + * via sol_netctl_add_service_monitor() callbacks.The service disconnect error info + * will be notified by error monitor. This callbacks of sol_netctl_add_service_monitor and + * sol_netctl_add_error_monitor must be added BEFORE the sol_netctl_service_disconnect() + * is called to ensure no messages are lost. + * + * @param service The service structure which the disconnection is desired + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_service_disconnect(struct sol_netctl_service *service); + +/** + * @brief Adds a monitor for the updated connman services + * + * To monitor the property of services, it gives information + * about the services. The callback is used to provide the information. + * sol_netctl_add_service_monitor will trigger all required activations. + * This callback must be added BEFORE the all functions are called to + * ensure connection manager has been initialized. + * + * @param cb monitor Callback to be called when the services are updated + * @param data Add a user data per callback + * + * @return 1 on the first time success, 0 on success, -errno on failure. + */ +int sol_netctl_add_service_monitor(sol_netctl_service_monitor_cb cb, + const void *data); + +/** + * @brief Dels a monitor for the updated connman services + * + * Removes the monitor for updated connman services. + * sol_netctl_del_service_monitor will trigger all required activations. + * This callback must be added AFTER the all functions are called to + * ensure connection manager has been shutdown. + * + * @param cb monitor Callback to be called when the services are updated + * @param data Add a user data per callback + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_del_service_monitor(sol_netctl_service_monitor_cb cb, + const void *data); + +/** + * @brief Adds a monitor for the updated connman manager properties + * + * To monitor (State, Offline...), a single monitor can be done for + * "something changed", and then the new value can be get. + * sol_netctl_add_manager_monitor will trigger all required activations. + * This callback must be added BEFORE sol_connman_get_state and + * sol_netctl_get_radios_offline. + * + * @param cb monitor Callback to be called when the manager are updated + * @param data Add a user data per callback + * + * @return 1 on the first time success, 0 on success, -errno on failure. + */ +int sol_netctl_add_manager_monitor(sol_netctl_manager_monitor_cb cb, + const void *data); + +/** + * @brief Dels a monitor for the updated connman manager properties + * + * Removes the monitor for updated connman manager properties. + * sol_netctl_del_manager_monitor will trigger all required activations. + * + * @param cb monitor Callback to be called when the manager are updated + * @param data Add a user data per callback + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_del_manager_monitor(sol_netctl_manager_monitor_cb cb, + const void *data); + +/** + * @brief Adds a monitor for the call error happens + * + * To monitor the call error happens, a single monitor can be done for + * error happens, and then the call result can be get. + * sol_netctl_add_error_monitor will call trigger all required activations. + * This callback must be added BEFORE sol_netctl_service_connect and + * sol_netctl_service_disconnect. + * + * @param cb monitor Callback to be called when the call result are updated + * @param data Add a user data per callback + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_add_error_monitor(sol_netctl_error_monitor_cb cb, + const void *data); + +/** + * @brief Dels a monitor for the call error happens + * + * Removes the monitor for updated the call error happens. + * sol_netctl_del_error_monitor will trigger all required activations. + * + * @param cb monitor Callback to be called when the call result are updated + * @param data Add a user data per callback + * + * @return 0 on success, -errno on failure. + */ +int sol_netctl_del_error_monitor(sol_netctl_error_monitor_cb cb, + const void *data); +/** + * @brief Gets the connman services + * + * The connman services vector can be given via sol_netctl_get_services. + * The vector is the last-known and more may be added/removed dynamically, + * then the pattern is to add a service monitor BEFORE calling the function. + * + * @return The retrieved content on success, NULL on failure. + */ +const struct sol_ptr_vector *sol_netctl_get_services(void); + +#ifdef __cplusplus +} +#endif