ICd policy API implementation
[ICd internal functions]


Classes

struct  icd_policy_api_async_data
struct  icd_policy_api_request_data
struct  icd_policy_scan_data
struct  icd_policy_module

Defines

#define ICD_POLICY_API_PREFIX   "libicd_policy_"
#define ICD_POLICY_INIT   "icd_policy_init"

Typedefs

typedef gboolean(*) icd_policy_api_async_call_fn (struct icd_policy_module *module, struct icd_policy_request *request, struct icd_policy_api_async_data *async_data)
typedef void(*) icd_policy_api_request_cb_fn (enum icd_policy_status status, struct icd_policy_request *req)

Functions

static void icd_policy_api_add_iap (struct icd_policy_request *req, gchar *service_type, guint service_attrs, gchar *service_id, gchar *network_type, guint network_attrs, gchar *network_id, gint network_priority)
static GSList * icd_policy_api_existing_requests_get (struct icd_request *new_request)
static void icd_policy_api_merge_requests (struct icd_policy_request *request_to_merge, struct icd_policy_request *existing_request)
static void icd_policy_api_make_request (guint policy_attrs, gchar *service_type, guint service_attrs, gchar *service_id, gchar *network_type, guint network_attrs, gchar *network_id)
static void icd_policy_api_async_data_free (struct icd_policy_api_async_data *data)
static gboolean icd_policy_api_run_async_next (struct icd_policy_request *req, struct icd_policy_api_async_data *async_data)
static gboolean icd_policy_api_run_async (struct icd_policy_request *req, icd_policy_api_async_call_fn call_policy, gpointer user_data)
static void icd_policy_api_request_cb (enum icd_policy_status status, struct icd_policy_request *req, gpointer policy_token)
static gboolean icd_policy_api_request_call (struct icd_policy_module *module, struct icd_policy_request *request, struct icd_policy_api_async_data *async_data)
void icd_policy_api_new_request (struct icd_policy_request *req, icd_policy_api_request_cb_fn cb, gpointer user_data)
static enum icd_policy_status icd_policy_api_run (icd_policy_api_run_module_fn policy_fn, struct icd_policy_request *request, gpointer user_data)
static enum icd_policy_status icd_policy_api_request_cancel_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
void icd_policy_api_request_cancel (struct icd_policy_request *req)
static gboolean icd_policy_api_existing_conn_foreach (struct icd_iap *iap, gpointer user_data)
static GSList * icd_policy_api_existing_conn_get (void)
static enum icd_policy_status icd_policy_api_iap_connect_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
enum icd_policy_status icd_policy_api_iap_connect (struct icd_policy_request *connection)
static enum icd_policy_status icd_policy_api_iap_restart_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
enum icd_policy_status icd_policy_api_iap_restart (struct icd_policy_request *connection, guint restart_count)
static enum icd_policy_status icd_policy_api_iap_succeeded_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
void icd_policy_api_iap_succeeded (struct icd_policy_request *connection)
static enum icd_policy_status icd_policy_api_iap_disconnect_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
enum icd_policy_status icd_policy_api_iap_disconnect (struct icd_policy_request *connection, gint refcount)
static enum icd_policy_status icd_policy_api_iap_disconnected_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
void icd_policy_api_iap_disconnected (struct icd_policy_request *connection, const gchar *err_str)
static enum icd_policy_status icd_policy_api_scan_stop_status_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
void icd_policy_api_scan_stop_status (const gchar *network_type)
static enum icd_policy_status icd_policy_api_scan_start_status_iter (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)
void icd_policy_api_scan_start_status (const gchar *network_type)
static GSList ** icd_policy_api_scan_list_get (void)
static struct icd_policy_scan_data * icd_policy_api_scan_find (icd_policy_scan_cb_fn cb, gpointer user_data)
static void icd_policy_api_scan_result (enum icd_scan_status status, const struct icd_scan_srv_provider *srv_provider, const struct icd_scan_cache *cache_entry, gpointer user_data)
static void icd_policy_api_scan_start (const gchar *type, const guint scope, icd_policy_scan_cb_fn cb, gpointer user_data)
static void icd_policy_api_scan_stop (icd_policy_scan_cb_fn cb, gpointer user_data)
static void icd_policy_api_disconnect_iap (struct icd_policy_request *network)
static gboolean icd_policy_api_init_cb (const gchar *module_name, void *handle, gpointer init_function, gpointer data)
gboolean icd_policy_api_load_modules (struct icd_context *icd_ctx)
void icd_policy_api_unload_modules (struct icd_context *icd_ctx)

Variables

const gchar const * icd_policy_api_state []
enum icd_policy_status(*) icd_policy_api_run_module_fn (struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)

Detailed Description

The data structure of the list of requests in icd_context and the existing request list passed to icd_policy_request_new_fn usable with e.g. icd_policy_merge_requests_fn looks like the following: 
 +-icd_context-+    +-GSList-------+
 |             |--->| request_list |
 +-------------+    +--------------+
                         |                    +-icd_policy_request-+
                         +---->icd_request--->| req                |<---+
                         |                    +--------------------+    |
                         |                                              |
                         |                    +-icd_policy_request-+    |
                         +---->icd_request--->| req                |<---+
                         |                    +--------------------+    |

                        ...                                            ...

                         |                    +-icd_policy_request-+    |
                         +---->icd_request--->| req                |<---+
                                              +--------------------+    |
                                                                        |
                                                        +-GSList------------+
                                                        | existing_requests |
                                                        +-------------------+
A policy module can make a request to wait for an external event such as UI dialog appearing by returning ICD_POLICY_WAITING. Policy processing will stop, whereby a new request is needed to clean up the waiting request. On cancelling a request, the request_cancel will be called for all policy modules to clean up an pending calls or timers left behind.

Define Documentation

#define ICD_POLICY_API_PREFIX   "libicd_policy_"

prefix for the ICd policy API modules

#define ICD_POLICY_INIT   "icd_policy_init"

name of the policy API init function

Typedef Documentation

typedef gboolean(*) icd_policy_api_async_call_fn(struct icd_policy_module *module, struct icd_policy_request *request, struct icd_policy_api_async_data *async_data)

Function prototype for calling the actual asynchronous policy function

Parameters:
module the policy module
request the requested connection
async_data data for the asynchronous function call
Returns:
TRUE if the module has a policy function that will cause the callback to be called; FALSE if no policy function is called

typedef void(*) icd_policy_api_request_cb_fn(enum icd_policy_status status, struct icd_policy_request *req)

Callback for the new_connection policy request

Parameters:
status status of the policy request
policy_request the policy request structure

Function Documentation

static void icd_policy_api_add_iap ( struct icd_policy_request *  req,
gchar *  service_type,
guint  service_attrs,
gchar *  service_id,
gchar *  network_type,
guint  network_attrs,
gchar *  network_id,
gint  network_priority 
) [static]

Add a network connection to try in response to the policy decision. Any policy module using this function must be compatible with the corresponding network module in order to set correct *_type and *_id.

Parameters:
req the request to which the new network is added
service_type service provider type, see srv_provider_api.h
service_attrs service provider attributes, see srv_provider_api.h
service_id service_provider id, see srv_provider_api.h
network_type network type, see network_api.h
network_attrs network attributes, see network_api.h
network_id network id, see network_api.h

static void icd_policy_api_async_data_free ( struct icd_policy_api_async_data *  data  )  [static]

Free async policy api data

Parameters:
data the data to free

static void icd_policy_api_disconnect_iap ( struct icd_policy_request *  network  )  [static]

Disconnect an active IAP

Parameters:
network the network to disconnect

static gboolean icd_policy_api_existing_conn_foreach ( struct icd_iap *  iap,
gpointer  user_data 
) [static]

Go through all connections and add them to the list in reverse order

Parameters:
iap current iap
user_data connection list
Returns:
TRUE to iterate over all connections

static GSList* icd_policy_api_existing_conn_get ( void   )  [static]

Get the list of existing connections

Returns:
list of connections; the caller needs to free only the GSList.

static GSList* icd_policy_api_existing_requests_get ( struct icd_request *  new_request  )  [static]

Create the list of existing requests the current request not to add to the list

Returns:
list of requests; the caller needs to free only the GSList.

enum icd_policy_status icd_policy_api_iap_connect ( struct icd_policy_request *  connection  ) 

Connect policy called when ICd attempts to connect to a network

Parameters:
connection the connection that is to be tried

static enum icd_policy_status icd_policy_api_iap_connect_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Iterator for the connect policy

Parameters:
module the policy module
request the request to apply policy to
user_data not used

enum icd_policy_status icd_policy_api_iap_disconnect ( struct icd_policy_request *  connection,
gint  refcount 
)

Disconnect policy called when ICd attempts to disconnect from a network

Parameters:
connection the connection that is to be tried
refcount a reference count on the number of applications using this connection or -1 if disconnect forced by Connectivity UI

static enum icd_policy_status icd_policy_api_iap_disconnect_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Iterator for the disconnect policy

Parameters:
module the policy module
request the request to apply policy to
user_data reference count

void icd_policy_api_iap_disconnected ( struct icd_policy_request *  connection,
const gchar *  err_str 
)

Informational policy to call when a network connection has been disconnected

Parameters:
connection the connection that was disconnected
err_str reason for disconnect; NULL on success

static enum icd_policy_status icd_policy_api_iap_disconnected_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Iterator for the disconnected informational policy

Parameters:
module the policy module
request the request to apply policy to
user_data reason for disconnect; NULL on success
Returns:
ICD_POLICY_ACCEPTED

enum icd_policy_status icd_policy_api_iap_restart ( struct icd_policy_request *  connection,
guint  restart_count 
)

Restart policy

Parameters:
connection the IAP network connection that is restarting
restart_count restart count
Returns:
ICD_POLICY_REJECTED if the limit has been exceded, ICD_POLICY_ACCEPTED otherwise

static enum icd_policy_status icd_policy_api_iap_restart_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Iterator for the restart policy

Parameters:
module the policy module
request the request to apply policy to
user_data user data to pass to the module

void icd_policy_api_iap_succeeded ( struct icd_policy_request *  connection  ) 

Informational policy to call when a network connection has been established

Parameters:
connection the connection that was connected

static enum icd_policy_status icd_policy_api_iap_succeeded_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Iterator for the connection succeeded informational policy

Parameters:
module the policy module
request the request to apply policy to
user_data not used
Returns:
ICD_POLICY_ACCEPTED

static gboolean icd_policy_api_init_cb ( const gchar *  module_name,
void *  handle,
gpointer  init_function,
gpointer  data 
) [static]

Initialize the loaded module

Parameters:
module_name module filename without path
handle module handle; used for unloading
init_function module init function
data icd context
Returns:
TRUE on success, FALSE on failure

Todo:
make init return TRUE on success and FALSE on failure whereby the module is unloaded

gboolean icd_policy_api_load_modules ( struct icd_context *  icd_ctx  ) 

Load all policy API modules

Parameters:
icd_ctx icd context
Returns:
the status from icd_plugin_load_all

static void icd_policy_api_make_request ( guint  policy_attrs,
gchar *  service_type,
guint  service_attrs,
gchar *  service_id,
gchar *  network_type,
guint  network_attrs,
gchar *  network_id 
) [static]

Function to create a new request

Parameters:
policy_attrs ICD_POLICY_ATTRIBUTE_* attributes
service_type service provider type, see srv_provider_api.h
service_attrs service provider attributes, see srv_provider_api.h
service_id service_provider id, see srv_provider_api.h
network_type network type, see network_api.h
network_attrs network attributes, see network_api.h
network_id network id, see network_api.h

static void icd_policy_api_merge_requests ( struct icd_policy_request *  request_to_merge,
struct icd_policy_request *  existing_request 
) [static]

Merge two request together and free the request_to_merge structure.

Parameters:
request_to_merge the request that will be joined with the existing one. The structure will also be freed and may point to anything after that.
existing_request the request that continues to exists after a merge

void icd_policy_api_new_request ( struct icd_policy_request *  req,
icd_policy_api_request_cb_fn  cb,
gpointer  user_data 
)

New request policy

Parameters:
req the new request
cb the callback to call with the policy decision
user_data user data to pass to the callback

static gboolean icd_policy_api_request_call ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
struct icd_policy_api_async_data *  async_data 
) [static]

Function that calls the new_request policy module function

Parameters:
module the policy module
request the requested network
async_data policy structure to pass as the policy_token to the policy module funcion
Returns:
TRUE if the module has a policy function that will cause the callback to be called; FALSE if no policy function is called

void icd_policy_api_request_cancel ( struct icd_policy_request *  req  ) 

Cancel a request that is in ICD_POLICY_WAITING state by informing each policy module.

Parameters:
req the policy request structure

static enum icd_policy_status icd_policy_api_request_cancel_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Module iterator for the 'cancel_request' function.

Parameters:
module the policy module
request the request to cancel
user_data user data; not used
Returns:
ICD_POLICY_ACCEPTED to iterate through all policy modules

static void icd_policy_api_request_cb ( enum icd_policy_status  status,
struct icd_policy_request *  req,
gpointer  policy_token 
) [static]

Status callback for the new request policy function

Parameters:
status status of the new request function
req the policy request
policy_token data for the async policy function call

static enum icd_policy_status icd_policy_api_run ( icd_policy_api_run_module_fn  policy_fn,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Iterate over all the modules and call the policy callback function for each of them.

Parameters:
policy_fn the policy callback function call for each module
request the request to apply policy to
user_data user data to pass to the function
Returns:
enum icd_policy_status

static gboolean icd_policy_api_run_async ( struct icd_policy_request *  req,
icd_policy_api_async_call_fn  call_policy,
gpointer  user_data 
) [static]

Initialize the asynchronous policy module function data and start running the policy modules one by one

Parameters:
req the request
call_policy the function that calls the policy module function with correct parameters
user_data user data for the function
Returns:
TRUE if an asynchronous policy module function got called, FALSE if no policy module contained any suitable functions

static gboolean icd_policy_api_run_async_next ( struct icd_policy_request *  req,
struct icd_policy_api_async_data *  async_data 
) [static]

Call an asynchronous policy module function

Parameters:
req the request
async_data policy data
Returns:
TRUE if a module was called; FALSE if there were no more modules to call

static struct icd_policy_scan_data* icd_policy_api_scan_find ( icd_policy_scan_cb_fn  cb,
gpointer  user_data 
) [static]

Find callback and user data

Parameters:
cb callback
user_data user_data

static GSList** icd_policy_api_scan_list_get ( void   )  [static]

Get the callback and user data list

Returns:
the list

static void icd_policy_api_scan_result ( enum icd_scan_status  status,
const struct icd_scan_srv_provider *  srv_provider,
const struct icd_scan_cache *  cache_entry,
gpointer  user_data 
) [static]

Scan results

Parameters:
status status of this network
srv_provider service provider entry; guaranteed to exist only for the lifetime of this callback function
cache_entry scan results; guaranteed to exist only for the lifetime of this callback function
user_data used data given to the scan callback

static void icd_policy_api_scan_start ( const gchar *  type,
const guint  scope,
icd_policy_scan_cb_fn  cb,
gpointer  user_data 
) [static]

Function for a module to request a network scan. icd_policy_api_scan_stop() has to be called as many times as this function is called even if the same callback and user_data pair are added.

Parameters:
type network type
scope scan scope
cb callback function to call with scan results
user_data user data to pass to the callback function

void icd_policy_api_scan_start_status ( const gchar *  network_type  ) 

Start scan informational policy

Parameters:
network_type network type to start scan for

static enum icd_policy_status icd_policy_api_scan_start_status_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Start scan iterator function

Parameters:
module the policy module
request NULL
user_data network type
Returns:
ICD_POLICY_ACCEPTED

static void icd_policy_api_scan_stop ( icd_policy_scan_cb_fn  cb,
gpointer  user_data 
) [static]

Stop returning scan results for the given callback and user data

Parameters:
cb scan callback
user_data user_data given in icd_policy_api_scan_start()

void icd_policy_api_scan_stop_status ( const gchar *  network_type  ) 

Stop scan informational policy

Parameters:
network_type network type to start scan for

static enum icd_policy_status icd_policy_api_scan_stop_status_iter ( struct icd_policy_module *  module,
struct icd_policy_request *  request,
gpointer  user_data 
) [static]

Stop scan iterator function

Parameters:
module the policy module
request NULL
user_data network type
Returns:
ICD_POLICY_ACCEPTED

void icd_policy_api_unload_modules ( struct icd_context *  icd_ctx  ) 

Unload all policy modules

Parameters:
icd_ctx icd context

Variable Documentation

enum icd_policy_status(*) icd_policy_api_run_module_fn(struct icd_policy_module *module, struct icd_policy_request *request, gpointer user_data)

Policy module function that will be called once for each policy module until ICD_POLICY_REJECTED is returned

Parameters:
module the policy module
request the request to apply policy to
user_data user data to pass to the module
Returns:
ICD_POLICY_REJECTED if the policy got rejected, ICD_POLICY_ACCEPTED otherwise

const gchar const* icd_policy_api_state[]

Initial value:

 {
  "ICD_POLICY_ACCEPTED",
  "ICD_POLICY_MERGED",
  "ICD_POLICY_WAITING",
  "ICD_POLICY_REJECTED"
}

Generated on Tue Feb 24 16:21:36 2009 for ICd2 by  doxygen 1.5.1