ICd policy API

Classes
struct	icd_policy_request
struct	icd_policy_api
Defines
#define	ICD_POLICY_ATTRIBUTE_CONN_UI   0x01
#define	ICD_POLICY_ATTRIBUTE_BACKGROUND   0x02
#define	ICD_POLICY_ATTRIBUTE_CONNECTIONS_FAILED   0x04
#define	ICD_POLICY_ATTRIBUTE_HAS_CONNECTIONS   0x08
#define	ICD_POLICY_ATTRIBUTE_NO_INTERACTION   0x10
#define	ICD_POLICY_ATTRIBUTE_ALWAYS_ONLINE_CHANGE   0x20
Typedefs
typedef void(*)	icd_policy_request_new_cb_fn (enum icd_policy_status status, struct icd_policy_request *new_request, gpointer policy_token)
typedef void(*)	icd_policy_request_new_fn (struct icd_policy_request *new_request, const GSList *existing_requests, icd_policy_request_new_cb_fn policy_done_cb, gpointer policy_token, gpointer *private)
typedef void(*)	icd_policy_request_cancel_fn (struct icd_policy_request *request, gpointer *private)
typedef void(*)	icd_policy_nw_connected_fn (struct icd_policy_request *network, GSList *existing_connections, gpointer *private)
typedef void(*)	icd_policy_nw_disconnected_fn (struct icd_policy_request *network, const gchar *err_str, GSList *existing_connections, gpointer *private)
typedef void(*)	icd_policy_nw_scan_stop_fn (const gchar *network_type, gpointer *private)
typedef void(*)	icd_policy_nw_scan_start_fn (const gchar *network_type, gpointer *private)
typedef void(*)	icd_policy_destruct_fn (gpointer *private)
typedef gboolean(*)	icd_policy_network_priority_fn (const gchar *srv_type, const gchar *srv_id, const gchar *network_type, const guint network_attrs, gint *network_priority)
typedef void(*)	icd_policy_nw_add_fn (struct icd_policy_request *request, gchar *service_type, guint service_attrs, gchar *service_id, gchar *network_type, guint network_attrs, gchar *network_id, gint network_priority)
typedef void(*)	icd_policy_request_merge_fn (struct icd_policy_request *request_to_merge, struct icd_policy_request *existing_request)
typedef void(*)	icd_policy_request_make_new_fn (guint policy_attrs, gchar *service_type, guint service_attrs, gchar *service_id, gchar *network_type, guint network_attrs, gchar *network_id)
typedef void(*)	icd_policy_scan_cb_fn (const guint status, const gchar *service_name, const gchar *service_type, const guint service_attrs, const gchar *service_id, gint service_priority, const gchar *network_name, const gchar *network_type, const guint network_attrs, const gchar *network_id, gint network_priority, const enum icd_nw_levels signal, gpointer user_data)
typedef void(*)	icd_policy_scan_start_fn (const gchar *type, const guint scope, icd_policy_scan_cb_fn cb, gpointer user_data)
typedef void(*)	icd_policy_scan_stop_fn (icd_policy_scan_cb_fn cb, gpointer user_data)
typedef void(*)	icd_policy_nw_close_fn (struct icd_policy_request *network)
typedef void(*)	icd_policy_init_fn (struct icd_policy_api *policy_api, icd_policy_nw_add_fn add_network, icd_policy_request_merge_fn merge_requests, icd_policy_request_make_new_fn make_request, icd_policy_scan_start_fn scan_start, icd_policy_scan_stop_fn scan_stop, icd_policy_nw_close_fn nw_close, icd_policy_network_priority_fn priority)
Enumerations
enum	icd_policy_status { ICD_POLICY_ACCEPTED = 0, ICD_POLICY_MERGED, ICD_POLICY_WAITING, ICD_POLICY_REJECTED }
enum	icd_policy_scan_status { ICD_POLICY_SCAN_NEW_NETWORK = 0, ICD_POLICY_SCAN_UPDATE_NETWORK, ICD_POLICY_SCAN_EXPIRED_NETWORK, ICD_POLICY_SCAN_DONE }
Variables
enum icd_policy_status(*)	icd_policy_nw_connect_fn (struct icd_policy_request *network, GSList *existing_connections, gpointer *private)
enum icd_policy_status(*)	icd_policy_nw_connection_restart_fn (struct icd_policy_request *network, guint restart_count, gpointer *private)
enum icd_policy_status(*)	icd_policy_nw_disconnect_fn (struct icd_policy_request *network, gint reference_count, GSList *existing_connections, gpointer *private)

---

Define Documentation

#define ICD_POLICY_ATTRIBUTE_ALWAYS_ONLINE_CHANGE   0x20

set if always online policy has made the request

#define ICD_POLICY_ATTRIBUTE_BACKGROUND   0x02

set if an application generated the request by itself

#define ICD_POLICY_ATTRIBUTE_CONN_UI   0x01

set if request is a response from UI

#define ICD_POLICY_ATTRIBUTE_CONNECTIONS_FAILED   0x04

set if a previous attempt for a request to connect networks failed; used by policy_iap_ask_request()

#define ICD_POLICY_ATTRIBUTE_HAS_CONNECTIONS   0x08

set whenever any IAPs are added to the request

#define ICD_POLICY_ATTRIBUTE_NO_INTERACTION   0x10

set if no user interaction may take place

---

Typedef Documentation

typedef void(*) icd_policy_destruct_fn(gpointer *private)

Policy module destruction function. Will be called before unloading the module.

Parameters:

private

a reference to the private data

typedef void(*) icd_policy_init_fn(struct icd_policy_api *policy_api, icd_policy_nw_add_fn add_network, icd_policy_request_merge_fn merge_requests, icd_policy_request_make_new_fn make_request, icd_policy_scan_start_fn scan_start, icd_policy_scan_stop_fn scan_stop, icd_policy_nw_close_fn nw_close, icd_policy_network_priority_fn priority)

Policy module initialization function. ICd will look for this type of function called 'icd_policy_init' for each policy module.

Parameters:

	policy_api	policy API structure to be filled in by the module
	add_network	function to add a network in response to a policy
	merge_requests	function to merge requests
	make_request	function for creating a new request
	scan_networks	function for scanning networks
	nw_close	function to disconnect a network
	priority	function to get a network priority for a network type

typedef gboolean(*) icd_policy_network_priority_fn(const gchar *srv_type, const gchar *srv_id, const gchar *network_type, const guint network_attrs, gint *network_priority)

Policy module network priority function.

Parameters:

	srv_type	service type or NULL if none
	srv_id	service id or NULL if none
	network_type	network type
	network_attrs	network attrs
	the	network priority (returned to caller)

Returns:

is there network type that has higher priority (TRUE = yes there is, FALSE = no there is not)

typedef void(*) icd_policy_nw_add_fn(struct icd_policy_request *request, gchar *service_type, guint service_attrs, gchar *service_id, gchar *network_type, guint network_attrs, gchar *network_id, gint network_priority)

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 avoid excessive string allocation, copying and deletion, ICd - not the module - will free all strings with g_free().

Parameters:

	request	the request this network refers to
	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
	network_priority	network priority, default value to use is -1

typedef void(*) icd_policy_nw_close_fn(struct icd_policy_request *network)

Close a connected network in icd_policy_nw_(dis)?connect* functions

Parameters:

network

the network to disconnect

typedef void(*) icd_policy_nw_connected_fn(struct icd_policy_request *network, GSList *existing_connections, gpointer *private)

Informational policy called when a network has been successfully connected

Parameters:

	network	the network to connect
	existing_connections	existing network connections
	private	private data for the module

typedef void(*) icd_policy_nw_disconnected_fn(struct icd_policy_request *network, const gchar *err_str, GSList *existing_connections, gpointer *private)

Informational policy called when a network has been disconnected

Parameters:

	request	the network to connect
	err_str	NULL if the network was disconnected normally, any ICD_DBUS_ERROR_* from osso-ic-dbus.h on error
	existing_connections	existing network connections
	private	private data for the module

typedef void(*) icd_policy_nw_scan_start_fn(const gchar *network_type, gpointer *private)

Informationa policy called when a scan is started for a network type

Parameters:

	network_type	network type
	private	private data for the module

typedef void(*) icd_policy_nw_scan_stop_fn(const gchar *network_type, gpointer *private)

Informationa policy called when a scan is stopped for a network type

Parameters:

	network_type	network type
	private	private data for the module

typedef void(*) icd_policy_request_cancel_fn(struct icd_policy_request *request, gpointer *private)

Clean up internal policy module data structures for a request that has previously reported ICD_POLICY_WAITING. After returning from this function, the request will be freed.

Parameters:

	request	the request that is to be removed
	private	private data for the module

typedef void(*) icd_policy_request_make_new_fn(guint policy_attrs, gchar *service_type, guint service_attrs, gchar *service_id, gchar *network_type, guint network_attrs, gchar *network_id)

Make a request for a new network connection. The new request will translate into icd_policy_request_new_fn function calls.

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

typedef void(*) icd_policy_request_merge_fn(struct icd_policy_request *request_to_merge, struct icd_policy_request *existing_request)

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. DO NOT USE after calling this function as it is freed and can point to anything afterwards.
	existing_request	the request that continues to exists after a merge

typedef void(*) icd_policy_request_new_cb_fn(enum icd_policy_status status, struct icd_policy_request *new_request, gpointer policy_token)

Result of the policy decision

Parameters:

	status	status of the operation, i.e. wheter to accept or deny the request
	new_request	the new connection request or NULL if the request has been merged with an existing one
	policy_token	the received policy_token

typedef void(*) icd_policy_request_new_fn(struct icd_policy_request *new_request, const GSList *existing_requests, icd_policy_request_new_cb_fn policy_done_cb, gpointer policy_token, gpointer *private)

New connection request policy function. Note that this function call is asynchronous; the callback needs to be called in order to report status.

Parameters:

	new_request	the new connection request
	existing_requests	currently existing requests; valid only when this function is executing - DO NOT EVER USE later on in any callbacks
	cb	callback to call when policy has been decided
	private	the private memeber of the icd_request_api structure

Note:

Policy modules implementing this function should also check wheter they need to implement icd_policy_request_cancel_fn.

typedef void(*) icd_policy_scan_cb_fn(const guint status, const gchar *service_name, const gchar *service_type, const guint service_attrs, const gchar *service_id, gint service_priority, const gchar *network_name, const gchar *network_type, const guint network_attrs, const gchar *network_id, gint network_priority, const enum icd_nw_levels signal, gpointer user_data)

Callback function for network scan.

Parameters:

	status	network scan status with ICD_POLICY_SCAN_* values
	service_name	service provider name, see srv_provider_api.h
	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
	service_priority	service priority within a service_type
	network_name	network name, see network_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
	network_priority	network priority between different network_type
	signal	signal leve, see network_api.h
	user_data	user data passed to icd_policy_scan_start_fn

typedef void(*) icd_policy_scan_start_fn(const gchar *type, const guint scope, icd_policy_scan_cb_fn cb, gpointer user_data)

Request network scan. Only usable in icd_policy_request_new_fn, as it's the only asynchronous policy function that a policy module can implement. Note also that scanning will continue until icd_policy_scan_stop_fn is called.

Parameters:

	type	network type
	scope	scan scope
	cb	callback function to call with scan results, cannot be NULL
	user_data	user data to pass to the callback function

typedef void(*) icd_policy_scan_stop_fn(icd_policy_scan_cb_fn cb, gpointer user_data)

Stop all network scans

Parameters:

	cb	callback function passed to icd_policy_scan_start_fn
	user_data	user data passed to icd_policy_scan_start_fn

---

Enumeration Type Documentation

enum icd_policy_scan_status

Network scan status

Enumerator:

ICD_POLICY_SCAN_NEW_NETWORK	A new network was found
ICD_POLICY_SCAN_UPDATE_NETWORK	The signal strenght of the network was updated
ICD_POLICY_SCAN_EXPIRED_NETWORK	The network is no longer found
ICD_POLICY_SCAN_DONE	Scanning done for this scan request

enum icd_policy_status

Status of the policy check

Enumerator:

ICD_POLICY_ACCEPTED	Accepted, next module to verify policy
ICD_POLICY_MERGED	Request is merged with an existing one, stops policy processing
ICD_POLICY_WAITING	Request is waiting for external action, stops policy processing
ICD_POLICY_REJECTED	Rejected by policy module

---

Variable Documentation

enum icd_policy_status(*) icd_policy_nw_connect_fn(struct icd_policy_request *network, GSList *existing_connections, gpointer *private)

Network connection policy function that will be once for each network that is tried.

Parameters:

	network	the network to connect
	existing_connections	existing network connections
	private	private data for the module

enum icd_policy_status(*) icd_policy_nw_connection_restart_fn(struct icd_policy_request *network, guint restart_count, gpointer *private)

Network connection restart policy function; decides how many times the network can be restarted

Parameters:

	network	the network to connect
	restart_count	how many times the network module has requested ICD_NW_RESTART
	private	private data for the module

enum icd_policy_status(*) icd_policy_nw_disconnect_fn(struct icd_policy_request *network, gint reference_count, GSList *existing_connections, gpointer *private)

Network disconnection policy function called when ICd attempts to disconnect a network.

Parameters:

	network	the network to disconnect
	reference_count	the number of applications using this connection or -1 on forced disconnect from the Connectivity UI
	existing_connections	existing network connections
	private	private data for the module

---