include/data_usage.h

   1 /*
   2  * resourced
   3  *
   4  * Copyright (c) 2000 - 2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 /*
  21  *  @file: data_udage.h
  22  *
  23  *  @desc Data usage API
  24  *  @version 1.0
  25  *
  26  *  Created on: 28 June, 2012
  27  */
  28
  29 #ifndef _RESOURCED_DATA_USAGE_H_
  30 #define _RESOURCED_DATA_USAGE_H_
  31
  32 #include <resourced.h>
  33 #include <time.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif /* __cplusplus */
  38
  39 /**
  40  * @brief Hardware network protocol types
  41  */
  42 typedef enum {
  43         RESOURCED_PROTOCOL_NONE,                        /**< Network unknown */
  44         RESOURCED_PROTOCOL_DATACALL_NOSVC,              /**< Network no service */
  45         RESOURCED_PROTOCOL_DATACALL_EMERGENCY,          /**< Network emergency */
  46         RESOURCED_PROTOCOL_DATACALL_SEARCH,             /**< Network search 1900 */
  47         RESOURCED_PROTOCOL_DATACALL_2G,                 /**< Network 2G */
  48         RESOURCED_PROTOCOL_DATACALL_2_5G,               /**< Network 2.5G */
  49         RESOURCED_PROTOCOL_DATACALL_2_5G_EDGE,          /**< Network EDGE */
  50         RESOURCED_PROTOCOL_DATACALL_3G,                 /**< Network UMTS */
  51         RESOURCED_PROTOCOL_DATACALL_HSDPA,              /**< Network HSDPA */
  52         RESOURCED_PROTOCOL_DATACALL_LTE,                /**< Network LTE */
  53         RESOURCED_PROTOCOL_MAX_ELEM
  54 } resourced_hw_net_protocol_type;
  55
  56 /**
  57  * @brief State of the monitored process
  58  */
  59 typedef enum {
  60         RESOURCED_STATE_UNKNOWN = 0,
  61         RESOURCED_STATE_FOREGROUND = 1 << 1,            /** < foreground state */
  62         RESOURCED_STATE_BACKGROUND = 1 << 2,            /** < background state */
  63         RESOURCED_STATE_LAST_ELEM = 1 << 3
  64 } resourced_state_t;
  65
  66 /**
  67  * @brief Network restriction states
  68  */
  69 typedef enum {
  70         RESOURCED_RESTRICTION_UNKNOWN,
  71         RESOURCED_RESTRICTION_ACTIVATED, /** < restriction has been activated */
  72         RESOURCED_RESTRICTION_REMOVED,   /** < restriction has been removed */
  73         RESOURCED_RESTRICTION_EXCLUDED,  /** < restriction has been excluded */
  74         RESOURCED_RESTRICTION_LAST_ELEM
  75 } resourced_restriction_state;
  76
  77 /**
  78  * @brief Network interface types
  79  */
  80 typedef enum {
  81         RESOURCED_IFACE_UNKNOWN,        /**< undefined iface */
  82         RESOURCED_IFACE_DATACALL,       /**< mobile data */
  83         RESOURCED_IFACE_WIFI,           /**< wifi data */
  84         RESOURCED_IFACE_WIRED,  /**< wired interface */
  85         RESOURCED_IFACE_BLUETOOTH,      /**< bluetooth interface */
  86         RESOURCED_IFACE_ALL,    /**< enumerate all network interface types */
  87         RESOURCED_IFACE_LAST_ELEM
  88 } resourced_iface_type;
  89
  90 /**
  91  * @brief Network roaming type
  92  */
  93 typedef enum {
  94         RESOURCED_ROAMING_UNKNOWN,              /**< can't define roaming - roaming unknown */
  95         RESOURCED_ROAMING_ENABLE,               /**< in roaming */
  96         RESOURCED_ROAMING_DISABLE,              /**< not in roaming */
  97         RESOURCED_ROAMING_LAST_ELEM,
  98 } resourced_roaming_type;
  99
 100 /*
 101  * rs_type: foreground or background process
 102  * iftype - interface type to apply restriction
 103  * send_limit - amount number of engress bytes allowed for restriction
 104  * rcv_limit - amount number of ingress bytes allowed for restriction
 105  *              old behaviour for send_limit & rcv_limit was 0
 106  * snd_warning_limit - threshold for warning notification on engress bytes
 107  * rcv_warning_limit - threshold for warning notification on ingress bytes
 108  *              value - WARNING_THRESHOLD_UNDEF means no threshold
 109  *              this limit is different from quota warning threshold,
 110  *              threshold means remaining, limit means occupaied
 111  * roaming - roaming support now only for exclusions for restriction it doesn't
 112  * make sense (roaming will be saved as UNKNOWN and restriction will be applied
 113  * in any case).
 114  *
 115  */
 116 typedef struct {
 117         resourced_state_t rs_type;
 118         resourced_iface_type iftype;
 119         int send_limit;
 120         int rcv_limit;
 121         int snd_warning_limit;
 122         int rcv_warning_limit;
 123         resourced_roaming_type roaming;
 124 } resourced_net_restrictions;
 125
 126 /**
 127  * @brief the same as for restriction
 128  */
 129 typedef struct {
 130         long incoming_bytes;
 131         long outgoing_bytes;
 132 } resourced_counters;
 133
 134
 135 /**
 136  * @brief Commulative structure for holding data usage information
 137  */
 138 typedef struct {
 139         resourced_counters cnt;
 140         resourced_net_restrictions rst;
 141 } resourced_common_info;
 142
 143 typedef struct {
 144         time_t from;
 145         time_t to;
 146 } resourced_tm_interval;
 147
 148 typedef enum {
 149         RESOURCED_CON_PERIOD_UNKNOWN,                   /**< Undefined period */
 150         RESOURCED_CON_PERIOD_LAST_RECEIVED_DATA,        /**< Last received data */
 151         RESOURCED_CON_PERIOD_LAST_SENT_DATA,            /**< Last sent data */
 152         RESOURCED_CON_PERIOD_TOTAL_RECEIVED_DATA,       /**< Total received data */
 153         RESOURCED_CON_PERIOD_TOTAL_SENT_DATA,           /**< Total sent data */
 154         RESOURCED_CON_PERIOD_LAST_ELEM
 155 } resourced_connection_period_type;
 156
 157 /**
 158  * @brief Period used in quota
 159  */
 160 typedef enum {
 161         RESOURCED_PERIOD_UNDEF = 0,
 162         RESOURCED_PERIOD_HOUR = 3600,
 163         RESOURCED_PERIOD_DAY = 86400,
 164         RESOURCED_PERIOD_WEEK = 604800,
 165         RESOURCED_PERIOD_MONTH = 2419200
 166 } data_usage_quota_period_t;
 167
 168 /**
 169  * @brief Restriction notification warning threshold value
 170  * definitions
 171  */
 172 enum {
 173         WARNING_THRESHOLD_DEFAULT,              /**< for quota it means
 174                 system-resource will evaluate proper value, for restriction it
 175                 means no warning */
 176         WARNING_THRESHOLD_NONE,                 /**< means no threshold at all */
 177 };
 178
 179 /**
 180  * @brief Datausage quota
 181  * time_period - time interval for quota, use predefined quota
 182  *  @see data_usage_quota_period_t
 183  * snd_quota - quota for outcoming data
 184  * rcv_quota - quota for incoming data
 185  * warning_send_threshold - threshold for warning notification on engress bytes
 186  * warning_rcv_threshold - threshold for warning notification on ingress bytes
 187  *              value - WARNING_THRESHOLD_UNDEF means no threshold
 188  *                    - WARNING_THRESHOLD_DEFAULT means system-resource will be
 189  *              responsible for evaluation threshold value
 190  *              The threshold value is amount of bytes remaining till blocking
 191  *
 192  * quota_type - at present it can be foreground quota or background
 193  * iftype - network interface type
 194  * start_time - quota processing activation time, if NULL current time is used
 195  */
 196 typedef struct {
 197         int time_period;
 198         int64_t snd_quota;
 199         int64_t rcv_quota;
 200         int snd_warning_threshold;
 201         int rcv_warning_threshold;
 202         resourced_state_t quota_type;
 203         resourced_iface_type iftype;
 204         time_t *start_time;
 205         resourced_roaming_type roaming_type;
 206 } data_usage_quota;
 207
 208 /**
 209  * @brief Reset filter for quota
 210  * app_id is mandatory field
 211  * iftype interface type, RESOURCED_IFACE_UNKNOWN
 212  *     interface is not valid parameter, use
 213  *     RESOURCED_IFACE_ALL instead
 214  * roaming_type roaming type
 215  * If user will not specify last 2 fields (UNKNOWN by default),
 216  *   neither quota with defined interface nor
 217  *   quota with defined roaming state will be removed.
 218  */
 219 struct datausage_quota_reset_rule {
 220         const char *app_id;
 221         resourced_iface_type iftype;
 222         resourced_roaming_type roaming;
 223 };
 224
 225 /**
 226  * @brief Selection rule applied for data usage enumeration
 227  */
 228 typedef struct {
 229         unsigned char version;
 230         time_t from;
 231         time_t to;
 232         resourced_iface_type iftype;
 233         int granularity;
 234 } data_usage_selection_rule;
 235
 236 /**
 237  * @brief Bundle structure for bringing all together application identification
 238  *     and properties.
 239  * app_id - application identification - copy it if you in
 240  *   callback function, don't store raw pointer on it
 241  * iface - interface name, NULL means all interfaces,
 242  *   don't store raw pointer on it in the callback function, copy it by value
 243  * interval - time interval for given result, NULL means entire interval
 244  * foreground - foreground restrictions and counters
 245  * background - background restrictions and counters
 246  */
 247 typedef struct {
 248         const char *app_id;
 249         const char *ifname;
 250         resourced_iface_type iftype;
 251         resourced_tm_interval *interval;
 252         resourced_common_info foreground;
 253         resourced_common_info background;
 254         resourced_roaming_type roaming;
 255         resourced_hw_net_protocol_type hw_net_protocol_type;
 256 } data_usage_info;
 257
 258 /**
 259  * @brief callback for enumerate counters and restrictions
 260  */
 261 typedef resourced_cb_ret(*data_usage_info_cb) (const data_usage_info *info,
 262                                                void *user_data);
 263
 264
 265 /**
 266  * @desc Description of the boolean option for enabling/disabling
 267  *      network interfaces and enabling/disabling some behaviar
 268  */
 269 typedef enum {
 270         RESOURCED_OPTION_UNDEF,
 271         RESOURCED_OPTION_ENABLE,
 272         RESOURCED_OPTION_DISABLE
 273 } resourced_option_state;
 274
 275 /**
 276  * @desc Set of the options.
 277  * version - contains structure version
 278  * wifi - enable/disable wifi, RESOURCED_OPTION_UNDEF to leave option as is
 279  * datacall - enable/disable datacall, RESOURCED_OPTION_UNDEF to leave option as is
 280  * datausage_timer - set period of the updating data from the kernel,
 281  *      0 to leave option as is
 282  * datacall_logging - enable/disable datacall_logging,
 283  *      RESOURCED_OPTION_UNDEF to leave option as is
 284  */
 285 typedef struct {
 286         unsigned char version;
 287         resourced_option_state wifi;
 288         resourced_option_state datacall;
 289         time_t datausage_timer;
 290         resourced_option_state datacall_logging;
 291 } resourced_options;
 292
 293 /**
 294  * @brief Structure for information on restrictions.
 295  * app_id - application identification - copy it if you in
 296  *   callback function, don't store raw pointer on it
 297  * iftype - type of network interface
 298  */
 299 typedef struct {
 300         const char *app_id;
 301         resourced_iface_type iftype;
 302         resourced_restriction_state rst_state;
 303         int rcv_limit;
 304         int send_limit;
 305         int quota_id;
 306         resourced_roaming_type roaming;
 307 } resourced_restriction_info;
 308
 309 /**
 310  * @brief callback for processing information of restrictions
 311  */
 312 typedef resourced_cb_ret(*resourced_restriction_cb)(
 313         const resourced_restriction_info *info, void *user_data);
 314
 315 /**
 316  * @desc Reset rule. It's statistics erasing description.
 317  * app_id - Erase statistics per appropriate app_id.
 318  *      app_id can be NULL in this case erasing all datas
 319  * iftype - Erase statistics per appropriate network interface type
 320  *      @see resourced_iface_type, if iftype is RESOURCED_IFACE_LAST_ELEM - erase all
 321  *      RESOURCED_IFACE_UNKNOW - means undetermined interface
 322  *      on moment of storing data.
 323  * interval - It's time interval, @see resourced_tm_interval. It should be set.
 324  *      Zero interval since 0 till 0 means entire interval.
 325  * connection_state - It's mask on time interval.
 326  *      Possible variation LAST and TOTAL for send and received data.
 327  */
 328 typedef struct {
 329         unsigned char version;
 330         char *app_id;
 331         resourced_iface_type iftype;
 332         resourced_tm_interval *interval;
 333         resourced_connection_period_type connection_state;
 334 } data_usage_reset_rule;
 335
 336 resourced_ret_c reset_data_usage(const data_usage_reset_rule *rule);
 337
 338 struct net_activity_info {
 339         int type;               /*<< ingress/egress */
 340         char *appid;
 341         int iftype;
 342         int bytes;
 343 };
 344
 345 typedef resourced_cb_ret(*net_activity_cb)(struct net_activity_info *info);
 346
 347
 348
 349 /**
 350  * @desc Set and apply restriction for application.
 351  *      It will create new restriction or modify existing.
 352  * @param app_id[in] - application identifier, it's package name now
 353  * @param restriction[in] - restriction to apply for application
 354  *      in foreground mode
 355  * At least one of the restriction should be setted.
 356  * @return 0 on success, otherwise error code
 357  */
 358 resourced_ret_c set_net_restriction(const char *app_id,
 359                             const resourced_net_restrictions *restriction);
 360
 361 /**
 362  * @desc Remove existing restriction for application
 363  *   It will delete restriction rule in kernel
 364  * @param app_id[in] - application identifier, it's package name
 365  */
 366 resourced_ret_c remove_restriction(const char *app_id);
 367
 368 resourced_ret_c remove_restriction_by_iftype(const char *app_id,
 369                                              const resourced_iface_type iftype);
 370
 371 /**
 372  * @desc Exclude restriction for application
 373  *   It will exclude restriction rule in kernel
 374  * @param app_id[in] - application identifier, it's package name
 375  * This function is deprecated, use set_net_exclusion
 376  */
 377 resourced_ret_c exclude_restriction(const char *app_id);
 378
 379 /**
 380  * This function is deprecated, use set_net_exclusion
 381  */
 382 resourced_ret_c exclude_restriction_by_iftype(
 383         const char *app_id, const resourced_iface_type iftype);
 384
 385
 386 /**
 387  * @brief Exclude application from network restriction.
 388  * Excluded application will be granted to
 389  * internet access, in case of whole network restriction.
 390  * iftype and roaming in resourced_net_restriction is supported right now
 391  */
 392 resourced_ret_c set_net_exclusion(const char *app_id,
 393                         const resourced_net_restrictions *rst);
 394
 395 /**
 396  * @desc Remove datausage quota by quota rule
 397  */
 398 resourced_ret_c remove_datausage_quota(
 399         const struct datausage_quota_reset_rule *rule);
 400
 401 /**
 402  * @deprecated
 403  */
 404 resourced_ret_c remove_datausage_quota_by_iftype(
 405         const char *app_id, const resourced_iface_type iftype);
 406
 407 /**
 408  * @desc Set options, daemon will handle option setting.
 409  */
 410 resourced_ret_c set_resourced_options(const resourced_options *options);
 411
 412 /**
 413  * @desc Obtain performance control options.
 414  */
 415 resourced_ret_c get_resourced_options(resourced_options *options);
 416
 417 /**
 418  * @desc This function will set time interval based quota for data usage
 419  *    Restriction will be applied in case of exceeding of the quota
 420  *    during time interval
 421  * @param app_id[in] - application identifier, it's package name
 422  * @param quotas[in] - time interval based restriction for data usage
 423  */
 424 resourced_ret_c set_datausage_quota(const char *app_id,
 425                               const data_usage_quota *quota);
 426
 427 /**
 428  * The callback is called for each application that used network
 429  * in between timestamps specified.
 430  *
 431  * If interface name is not specified, each application will only appear
 432  * once with the total traffic used over all interfaces.
 433  *
 434  * @brief Data usage enumerate function
 435  */
 436 resourced_ret_c data_usage_foreach(const data_usage_selection_rule *rule,
 437                              data_usage_info_cb info_cb, void *user_data);
 438
 439 /**
 440  * The callback is called for each application that restricted now
 441  *
 442  * @brief Restrictions enumerate function
 443  */
 444 resourced_ret_c restrictions_foreach(resourced_restriction_cb restriction_cb,
 445                                 void *user_data);
 446
 447 /**
 448  * If interface name is specified in rule, the callback will be called
 449  * exactly 1 time with the total traffic counts for that interface
 450  * by specified application in the specified time interval.
 451  *
 452  * If interface name is not specified, the callback will be called once
 453  * for each interface used by application during the specified interval.
 454  * It could be 0 if the application did not use any network interfaces
 455  * during that period.
 456  *
 457  * @brief Data usage details enumerate function
 458  */
 459 resourced_ret_c data_usage_details_foreach(const char *app_id,
 460                                            data_usage_selection_rule *rule,
 461                                            data_usage_info_cb info_cb,
 462                                            void *user_data);
 463
 464 /**
 465  * @desc This function registering callback which invokes per every packet.
 466  *      Function creates new reading thread and returns.
 467  */
 468 resourced_ret_c register_net_activity_cb(net_activity_cb activity_cb);
 469
 470 /**
 471  * @desc This function updates the resourced counters and stores in the database
 472  */
 473 resourced_ret_c resourced_update_statistics(void);
 474
 475 resourced_ret_c get_restriction_state(const char *pkg_id,
 476         resourced_iface_type iftype, resourced_restriction_state *state);
 477
 478 #ifdef __cplusplus
 479 }
 480 #endif /* __cplusplus */
 481
 482 #endif /* _RESOURCED_DATA_USAGE_H_ */