IAP connection abstraction
[ICd internal functions]

Classes
struct	icd_iap_disconnect_data
struct	icd_iap_env
struct	icd_iap
Typedefs
typedef void(*)	icd_iap_request_cb_fn (enum icd_iap_status status, struct icd_iap *iap, gpointer user_data)
typedef gboolean(*)	icd_iap_foreach_fn (struct icd_iap *iap, gpointer user_data)
Enumerations
enum	icd_iap_state {   ICD_IAP_STATE_DISCONNECTED = 0, ICD_IAP_STATE_SCRIPT_PRE_UP, ICD_IAP_STATE_LINK_UP, ICD_IAP_STATE_LINK_POST_UP,   ICD_IAP_STATE_IP_UP, ICD_IAP_STATE_SRV_UP, ICD_IAP_STATE_SCRIPT_POST_UP, ICD_IAP_STATE_SAVING,   ICD_IAP_STATE_CONNECTED, ICD_IAP_STATE_CONNECTED_DOWN, ICD_IAP_STATE_SRV_DOWN, ICD_IAP_STATE_IP_DOWN,   ICD_IAP_STATE_IP_RESTART_SCRIPTS, ICD_IAP_STATE_LINK_PRE_DOWN, ICD_IAP_STATE_LINK_PRE_RESTART_SCRIPTS, ICD_IAP_STATE_LINK_DOWN,   ICD_IAP_STATE_LINK_RESTART_SCRIPTS, ICD_IAP_STATE_SCRIPT_POST_DOWN, ICD_IAP_MAX_STATES }
enum	icd_iap_status { ICD_IAP_CREATED = 0, ICD_IAP_DISCONNECTED, ICD_IAP_BUSY, ICD_IAP_FAILED }
Functions
static void	icd_iap_srv_disconnect_cb (enum icd_srv_status status, gpointer disconnect_cb_token)
static void	icd_iap_module_next (struct icd_iap *iap)
static void	icd_iap_disconnect_module (struct icd_iap *iap)
static void	icd_iap_run_pre_up_scripts (struct icd_iap *iap)
static void	icd_iap_run_post_down_scripts (struct icd_iap *iap)
static gboolean	icd_iap_run_renew (struct icd_iap *iap)
static gboolean	string_equal (const gchar *a, const gchar *b)
void	icd_iap_free (struct icd_iap *iap)
icd_iap *	icd_iap_new (void)
gboolean	icd_iap_id_create (struct icd_iap *iap, const gchar *new_id)
static struct icd_network_module *	icd_iap_next_ip_up_module (struct icd_iap *iap)
static struct icd_network_module *	icd_iap_next_link_post_up_module (struct icd_iap *iap)
static struct icd_network_module *	icd_iap_next_link_up_module (struct icd_iap *iap)
static void	icd_iap_modules_reset (struct icd_iap *iap)
static void	icd_iap_do_callback (enum icd_iap_status status, struct icd_iap *iap)
static void	icd_iap_disconnect_cb (const enum icd_nw_status status, const gpointer cb_token)
static gboolean	icd_iap_run_restart (struct icd_iap *iap)
static void	icd_iap_post_down_script_done (const pid_t pid, const gint exit_value, gpointer user_data)
static void	icd_iap_up_callback (const enum icd_nw_status status, const gchar *err_str, const gpointer cb_token)
static void	icd_iap_link_up_cb (const enum icd_nw_status status, const gchar *err_str, const gchar *interface_name, const gpointer link_up_cb_token,...)
static void	icd_iap_link_post_up_cb (const enum icd_nw_status status, const gchar *err_str, const gpointer link_post_up_cb_token,...)
static void	icd_iap_ip_up_cb (const enum icd_nw_status status, const gchar *err_str, const gpointer ip_up_cb_token,...)
static void	icd_iap_srv_connect_cb (enum icd_srv_status status, const gchar *err_str, gpointer user_data)
static void	icd_iap_has_connected (struct icd_iap *iap)
static void	icd_iap_save_cb (gboolean success, gpointer user_data)
static void	icd_iap_post_up_script_done (const pid_t pid, const gint exit_value, gpointer user_data)
static void	icd_iap_pre_up_script_done (const pid_t pid, const gint exit_value, gpointer user_data)
void	icd_iap_connect (struct icd_iap *iap, icd_iap_request_cb_fn request_cb, gpointer user_data)
static void	icd_iap_pre_down_script_done (const pid_t pid, const gint exit_value, gpointer user_data)
static gboolean	icd_iap_check_connected (struct icd_iap *iap, gpointer user_data)
static void	icd_iap_script_pre_down (const enum icd_nw_status status, const gpointer cb_token)
void	icd_iap_disconnect (struct icd_iap *iap, const gchar *err_str)
static void	icd_iap_run_renew_cb (enum icd_nw_renew_status status, gpointer renew_token)
void	icd_iap_renew (struct icd_iap *iap, enum icd_nw_layer renew_layer)
void	icd_iap_restart (struct icd_iap *iap, enum icd_nw_layer restart_layer)
guint	icd_iap_get_ipinfo (struct icd_iap *iap, icd_nw_ip_addr_info_cb_fn cb, gpointer user_data)
gboolean	icd_iap_get_ip_stats (struct icd_iap *iap, icd_nw_ip_stats_cb_fn cb, gpointer user_data)
gboolean	icd_iap_get_link_post_stats (struct icd_iap *iap, icd_nw_link_post_stats_cb_fn cb, gpointer user_data)
gboolean	icd_iap_get_link_stats (struct icd_iap *iap, icd_nw_link_stats_cb_fn cb, gpointer user_data)
icd_iap *	icd_iap_find (const gchar *network_type, const guint network_attrs, const gchar *network_id)
icd_iap *	icd_iap_find_by_id (const gchar *iap_id, const gboolean is_local)
icd_iap *	icd_iap_foreach (icd_iap_foreach_fn fn, gpointer user_data)
gboolean	icd_iap_rename (struct icd_iap *iap, const gchar *name)
Variables
const gchar *	icd_iap_state_names [ICD_IAP_MAX_STATES]
static const gchar *	icd_iap_status_names []
static const gchar *	icd_iap_layer_names []

---

Typedef Documentation

typedef gboolean(*) icd_iap_foreach_fn(struct icd_iap *iap, gpointer user_data)

Iterator function called for each active IAP structure starting from the structure associated with the newest request. Only active IAPs are iterated through, not the ones in a request that will be tried if the current one fails.

Parameters:

	iap	the IAP struct
	user_data	user data

Returns:

TRUE to continue, FALSE to stop iterating

typedef void(*) icd_iap_request_cb_fn(enum icd_iap_status status, struct icd_iap *iap, gpointer user_data)

The IAP status callback function

Parameters:

	status	the status from the IAP creation process
	iap	the IAP
	user_data	user data

---

Enumeration Type Documentation

enum icd_iap_state

State of an IAP

Enumerator:

ICD_IAP_STATE_DISCONNECTED	iap is not connected
ICD_IAP_STATE_SCRIPT_PRE_UP	iap pre-up script is being run
ICD_IAP_STATE_LINK_UP	iap is connecting its link layer
ICD_IAP_STATE_LINK_POST_UP	iap is connecting its post link layer, i.e. link authentication
ICD_IAP_STATE_IP_UP	iap is connecting its ip layer
ICD_IAP_STATE_SRV_UP	srv module is being run
ICD_IAP_STATE_SCRIPT_POST_UP	iap (post-)up script is being run
ICD_IAP_STATE_SAVING	connection is being saved
ICD_IAP_STATE_CONNECTED	iap is connected
ICD_IAP_STATE_CONNECTED_DOWN	iap is being disconnected
ICD_IAP_STATE_SRV_DOWN	srv module is disconnecting
ICD_IAP_STATE_IP_DOWN	iap is disconnecting its ip layer
ICD_IAP_STATE_IP_RESTART_SCRIPTS	iap is restarting at ip layer and running post-down and pre-up scripts
ICD_IAP_STATE_LINK_PRE_DOWN	iap is disconnecting its pre link layer, i.e. link deauthenticating
ICD_IAP_STATE_LINK_PRE_RESTART_SCRIPTS	iap is restarting at pre link layer and running post-down and pre-up scripts
ICD_IAP_STATE_LINK_DOWN	iap is disconnecting its link layer
ICD_IAP_STATE_LINK_RESTART_SCRIPTS	iap is restarting at link layer and running post-down and pre-up scripts
ICD_IAP_STATE_SCRIPT_POST_DOWN	iap post-down script is being run
ICD_IAP_MAX_STATES	number of states

enum icd_iap_status

status of the request

Enumerator:

ICD_IAP_CREATED	a new IAP was created and connected succesfully
ICD_IAP_DISCONNECTED	the iap was successfully disconnected
ICD_IAP_BUSY	iap failed because some other module was in use by another iap
ICD_IAP_FAILED	the iap failed with some critical error while connecting

---

Function Documentation

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

Helper function for pre down script to check wheter there is another connected IAP

Parameters:

	iap	IAP to examine
	user_data	IAP that is going down

Returns:

TRUE to continue iterating, FALSE to stop and return the IAP

void icd_iap_connect	(	struct icd_iap *	iap,
		icd_iap_request_cb_fn	request_cb,
		gpointer	user_data
	)

Request a network connection. The caller needs to free the given icd_iap data structure when the IAP is no longer in use.

Parameters:

	iap	IAP to connect
	request_cb	the callback to call when the outcome of the request is known
	user_data	user data to pass to the callback

void icd_iap_disconnect	(	struct icd_iap *	iap,
		const gchar *	err_str
	)

Start disconnecting the current connecting module if it has not yet called it's callback. Set the state to _down so that the IAP cannot be disconnected again.

Parameters:

	iap	IAP
	err_str	NULL if the network was disconnected normally or any ICD_DBUS_ERROR_* from osso-ic-dbus.h on error

static void icd_iap_disconnect_cb	(	const enum icd_nw_status	status,
		const gpointer	cb_token
	)			[static]

Disconnect callback function for all IAP network _down functions

Parameters:

	status	the status of the _down function, ignored mostly for now
	cb_token	the IAP

static void icd_iap_disconnect_module

(

struct icd_iap *

iap

)

[static]

Call all network module _down functions added to the IAP. This function does not handle cancelled IAPs which have not yet called their respective _up functions and can't thus be merged with icd_iap_disconnect().

Parameters:

iap

IAP to disconnect

static void icd_iap_do_callback	(	enum icd_iap_status	status,
		struct icd_iap *	iap
	)			[static]

Report the final status of the connection attempt to the caller. Do notice that the IAP is freed by the caller, do not use it after calling this function

Parameters:

	status	the status to report
	iap	the IAP

struct icd_iap * icd_iap_find	(	const gchar *	network_type,
		const guint	network_attrs,
		const gchar *	network_id
	)

Find an IAP according type, attributes and id

Parameters:

	network_type	the type of the IAP
	network_attrs	attributes
	network_id	IAP id

Returns:

a pointer to the IAP on success, NULL on failure

struct icd_iap * icd_iap_find_by_id	(	const gchar *	iap_id,
		const gboolean	is_local
	)

Find an IAP according to id and locally generated flag

Parameters:

	iap_id	IAP id
	is_local	TRUE if a locally generated icd2 id is requested, FALSE otherwise

Returns:

a pointer to the IAP on success, NULL on failure

struct icd_iap * icd_iap_foreach	(	icd_iap_foreach_fn	fn,
		gpointer	user_data
	)

Iterate over all active IAPs

Parameters:

	fn	function to call for each IAP
	user_data	user data to pass to the iterator function

Returns:

the IAP struct where fn returns FALSE, NULL otherwise or on error

void icd_iap_free

(

struct icd_iap *

iap

)

Free up an iap structure

Parameters:

iap

the IAP to free

gboolean icd_iap_get_ip_stats	(	struct icd_iap *	iap,
		icd_nw_ip_stats_cb_fn	cb,
		gpointer	user_data
	)

Get ip level statistics from an IAP.

Parameters:

	iap	the IAP
	cb	callback function
	user_data	user data

Returns:

TRUE if callback will be called, FALSE otherwise

guint icd_iap_get_ipinfo	(	struct icd_iap *	iap,
		icd_nw_ip_addr_info_cb_fn	cb,
		gpointer	user_data
	)

Get IP address info from an IAP

Parameters:

	iap	IAP
	cb	callback function
	user_data	user data

Returns:

the number of times the callback is going to be called

gboolean icd_iap_get_link_post_stats	(	struct icd_iap *	iap,
		icd_nw_link_post_stats_cb_fn	cb,
		gpointer	user_data
	)

Get link post level statistics from an IAP.

Parameters:

	iap	the IAP
	cb	callback function
	user_data	user data

Returns:

TRUE if callback will be called, FALSE otherwise

gboolean icd_iap_get_link_stats	(	struct icd_iap *	iap,
		icd_nw_link_stats_cb_fn	cb,
		gpointer	user_data
	)

Get link level statistics from an IAP.

Parameters:

	iap	the IAP
	cb	callback function
	user_data	user data

Returns:

TRUE if callback will be called, FALSE otherwise

static void icd_iap_has_connected

(

struct icd_iap *

iap

)

[static]

Notify the caller (request) that the IAP has connected

Parameters:

iap

the IAP

gboolean icd_iap_id_create	(	struct icd_iap *	iap,
		const gchar *	new_id
	)

Create a new unique id for the iap, settings are accessed using this id

Parameters:

	iap	the IAP
	new_id	preferably NULL but can also be the new id

Returns:

TRUE on success, FALSE on failure

Todo:

the settings library will create the id, for now let icd2 create a local id

static void icd_iap_ip_up_cb	(	const enum icd_nw_status	status,
		const gchar *	err_str,
		const gpointer	ip_up_cb_token,
			...
	)			[static]

Callback function called when IP address configuration has completed

Parameters:

	status	status of the operation
	err_str	NULL if the network was disconnected normally or an error string
	ip_up_cb_token	the callback token
	...	zero or more arrays of strings where each string in the array is an environment variable of the form name=value; end with NULL

static void icd_iap_link_post_up_cb	(	const enum icd_nw_status	status,
		const gchar *	err_str,
		const gpointer	link_post_up_cb_token,
			...
	)			[static]

Callback for link_post_up; common _up callback handling in icd_iap_up_callback()

Parameters:

	status	status of the operation
	err_str	NULL if the network was disconnected normally or any ICD_DBUS_ERROR_* from osso-ic-dbus.h on error
	link_up_cb_token	the IAP in question
	...	zero or more arrays of strings where each string in the array is an environment variable of the form name=value; end with NULL

static void icd_iap_link_up_cb	(	const enum icd_nw_status	status,
		const gchar *	err_str,
		const gchar *	interface_name,
		const gpointer	link_up_cb_token,
			...
	)			[static]

Callback for link_up; saves the interface name on success, common _up callback handling in icd_iap_up_callback()

Parameters:

	status	status of the operation
	err_str	NULL if the network was disconnected normally or any ICD_DBUS_ERROR_* from osso-ic-dbus.h on error
	interface_name	the device interface name on ICD_NW_SUCCESS*
	link_up_cb_token	the IAP in question
	...	zero or more arrays of strings where each string in the array is an environment variable of the form name=value; end with NULL

static void icd_iap_module_next

(

struct icd_iap *

iap

)

[static]

Continue (or start) connecting an IAP by finding a suitable _up function from the available modules. Calls icd_iap_connect_module() to call the relevant _up function

Parameters:

iap

the IAP to connect

static void icd_iap_modules_reset

(

struct icd_iap *

iap

)

[static]

Reset the list of modules to try

Parameters:

iap

the IAP

struct icd_iap * icd_iap_new

(

void

)

Allocate memory for a new IAP structure. Caller is responsible of freeing the IAP structure with icd_iap_free() after use

Returns:

the newly created IAP structure

static struct icd_network_module* icd_iap_next_ip_up_module

(

struct icd_iap *

iap

)

[static]

Find the next module that has implemented ip_up()

Parameters:

iap

the IAP

Returns:

the next module or NULL if none

static struct icd_network_module* icd_iap_next_link_post_up_module

(

struct icd_iap *

iap

)

[static]

Find the next module that has implemented link_post_up()

Parameters:

iap

the IAP

Returns:

the next module or NULL if none

static struct icd_network_module* icd_iap_next_link_up_module

(

struct icd_iap *

iap

)

[static]

Find the next module that has implemented link_up()

Parameters:

iap

the IAP

Returns:

the next module or NULL if none

static void icd_iap_post_down_script_done	(	const pid_t	pid,
		const gint	exit_value,
		gpointer	user_data
	)			[static]

Post-down script has run, restart IAP or report final status.

Parameters:

	pid	the process id of the script that exited
	exit_value	exit value of the script or -1 on timeout
	user_data	current IAP

static void icd_iap_post_up_script_done	(	const pid_t	pid,
		const gint	exit_value,
		gpointer	user_data
	)			[static]

A post-up script has exited

Parameters:

	pid	the process id of the script that exited
	exit_value	exit value of the script or -1 on timeout
	user_data	the current IAP

Todo:

what to do with this iap if UI goes down?

static void icd_iap_pre_down_script_done	(	const pid_t	pid,
		const gint	exit_value,
		gpointer	user_data
	)			[static]

Pre-down script callback to remove script pid from list.

Parameters:

	pid	the process id of the script that exited
	exit_value	exit value of the script or -1 on timeout
	user_data	user data

static void icd_iap_pre_up_script_done	(	const pid_t	pid,
		const gint	exit_value,
		gpointer	user_data
	)			[static]

Callback function called when pre-up scripts have been run

Parameters:

	pid	the process id of the script that exited
	exit_value	exit value of the script or -1 on timeout
	user_data	user data

gboolean icd_iap_rename	(	struct icd_iap *	iap,
		const gchar *	name
	)

Rename an IAP and continue connecting it if it's in ICD_IAP_STATE_SAVING

Parameters:

	iap	the IAP
	name	the new name of the IAP

Todo:

continuing with connecting should be done somewhere else

void icd_iap_renew	(	struct icd_iap *	iap,
		enum icd_nw_layer	renew_layer
	)

Request a renew for the specified IAP and network layer

Parameters:

	iap	the IAP
	renew_layer	the network module layer to renew

void icd_iap_restart	(	struct icd_iap *	iap,
		enum icd_nw_layer	restart_layer
	)

Restart a network module by disconnecting network modules including the requested layer. When the requested layer has been disconnected, reconnect starting from the requested layer.

Parameters:

	iap	the IAP
	renew_layer	the layer which is to be disconnectd

static void icd_iap_run_pre_up_scripts

(

struct icd_iap *

iap

)

[static]

Run pre up scripts

Parameters:

iap

the IAP

static gboolean icd_iap_run_renew

(

struct icd_iap *

iap

)

[static]

Run the renew function for the specified IAP

Parameters:

iap

the IAP

Returns:

TRUE if a renew network module function is called; FALSE if no further renew functions can be found

static void icd_iap_run_renew_cb	(	enum icd_nw_renew_status	status,
		gpointer	renew_token
	)			[static]

Renew function callback

Parameters:

	status	renewal status
	renew_token	the IAP that is being renewed

static gboolean icd_iap_run_restart

(

struct icd_iap *

iap

)

[static]

Check wheter the iap needs to be initiated. Called when the network module layer disconnect functions have been exhausted and when post down scripts have been run.

Parameters:

iap

the IAP

Returns:

TRUE if a restart was initiated, FALSE if not

static void icd_iap_save_cb	(	gboolean	success,
		gpointer	user_data
	)			[static]

Callback for save connection dialog request

Parameters:

	success	TRUE on success, FALSE on failure
	user_data	the IAP

static void icd_iap_script_pre_down	(	const enum icd_nw_status	status,
		const gpointer	cb_token
	)			[static]

Call pre-down network scripts.

Parameters:

	status	the status of the _down function, ignored for now
	cb_token	the IAP

static void icd_iap_srv_connect_cb	(	enum icd_srv_status	status,
		const gchar *	err_str,
		gpointer	user_data
	)			[static]

Service provider connect callback function

Parameters:

	status	status of the connect
	user_data	user data

static void icd_iap_srv_disconnect_cb	(	enum icd_srv_status	status,
		gpointer	disconnect_cb_token
	)			[static]

Disconnect callback for the service provider module

Parameters:

	status	status of the disconnect, ignored for now
	disconnect_cb_token	token passed to the disconnect function

static void icd_iap_up_callback	(	const enum icd_nw_status	status,
		const gchar *	err_str,
		const gpointer	cb_token
	)			[static]

Callback for _up functions; adds _down functions and calls the next module on success, starts disconnecting on failure

Parameters:

	status	status
	err_str	error string or NULL if no error
	cb_token	the IAP

static gboolean string_equal	(	const gchar *	a,
		const gchar *	b
	)			[static]

Helper function for comparing two strings where a NULL string is equal to another NULL string

Parameters:

	a	string A
	b	string B

Returns:

TRUE if equal, FALSE if unequal

---

Variable Documentation

const gchar* icd_iap_layer_names[] [static]

Initial value:

 {
  "ICD_NW_LAYER_NONE",
  "ICD_NW_LAYER_LINK",
  "ICD_NW_LAYER_LINK_POST",
  "ICD_NW_LAYER_IP",
  "ICD_NW_LAYER_SERVICE",
  "ICD_NW_LAYER_ALL"
}

names for network module layers

const gchar* icd_iap_state_names[ICD_IAP_MAX_STATES]

Initial value:

 {
  "ICD_IAP_STATE_DISCONNECTED",
  "ICD_IAP_STATE_SCRIPT_PRE_UP",
  "ICD_IAP_STATE_LINK_UP",
  "ICD_IAP_STATE_LINK_POST_UP",
  "ICD_IAP_STATE_IP_UP",
  "ICD_IAP_STATE_SRV_UP",
  "ICD_IAP_STATE_SCRIPT_POST_UP",
  "ICD_IAP_STATE_SAVING",
  "ICD_IAP_STATE_CONNECTED",
  "ICD_IAP_STATE_CONNECTED_DOWN",
  "ICD_IAP_STATE_SRV_DOWN",
  "ICD_IAP_STATE_IP_DOWN",
  "ICD_IAP_STATE_IP_RESTART_SCRIPTS",
  "ICD_IAP_STATE_LINK_PRE_DOWN",
  "ICD_IAP_STATE_LINK_PRE_RESTART_SCRIPTS",
  "ICD_IAP_STATE_LINK_DOWN",
  "ICD_IAP_STATE_LINK_RESTART_SCRIPTS",
  "ICD_IAP_STATE_SCRIPT_POST_DOWN"
}

names for the different states

const gchar* icd_iap_status_names[] [static]

Initial value:

 {
  "ICD_IAP_CREATED",
  "ICD_IAP_DISCONNECTED",
  "ICD_IAP_BUSY",
  "ICD_IAP_FAILED"
}

names for status codes

---