Service provider API implementation
[ICd internal functions]

Classes
struct	icd_srv_provider_cb_data
struct	icd_srv_identify
struct	pid_notify
struct	icd_srv_module
Defines
#define	ICD_SRV_PROVIDER_MODULE_NAME   "/module"
#define	ICD_SRV_PROVIDER_NETWORK_TYPES   "/network_type"
Typedefs
typedef gboolean(*)	icd_srv_provider_foreach_module_fn (struct icd_srv_module *module, gpointer user_data)
typedef void(*)	icd_srv_provider_connect_cb_fn (enum icd_srv_status status, const gchar *err_str, gpointer user_data)
typedef void(*)	icd_srv_provider_disconnect_cb_fn (enum icd_srv_status status, gpointer user_data)
Functions
static gboolean	string_equal (const gchar *a, const gchar *b)
icd_srv_module *	icd_srv_provider_foreach_module (struct icd_context *icd_ctx, icd_srv_provider_foreach_module_fn foreach_fn, gpointer user_data)
static void	icd_srv_provider_disconnect_cb (enum icd_srv_status status, gpointer disconnect_cb_token)
gboolean	icd_srv_provider_disconnect (struct icd_iap *iap, icd_srv_provider_disconnect_cb_fn cb, gpointer user_data)
gboolean	icd_srv_provider_has_next (struct icd_iap *iap)
static void	icd_srv_provider_connect_cb (enum icd_srv_status status, const gchar *err_str, gpointer connect_cb_token)
gboolean	icd_srv_provider_connect (struct icd_iap *iap, icd_srv_provider_connect_cb_fn cb, gpointer user_data)
static void	icd_srv_provider_identify_cb (const enum icd_srv_identify_status status, const gchar *service_type, const gchar *service_name, const guint service_attrs, const gchar *service_id, const gint service_priority, const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer identify_cb_token)
gboolean	icd_srv_provider_identify (struct icd_network_module *nw_module, struct icd_scan_cache *cache_entry, enum icd_scan_status status)
static gboolean	icd_srv_provider_foreach_module_pid (struct icd_srv_module *srv_module, gpointer user_data)
gboolean	icd_srv_provider_notify_pid (struct icd_context *icd_ctx, const pid_t pid, const gint exit_value)
static void	icd_srv_provider_watch_pid (const pid_t pid, gpointer watch_cb_token)
static void	icd_srv_provider_close (enum icd_srv_status status, const gchar *err_str, const gchar *service_type, const guint service_attrs, const gchar *service_id, const gchar *network_type, const guint network_attrs, const gchar *network_id)
static void	icd_srv_provider_limited_conn (const enum icd_srv_limited_conn_status conn_status, const gchar *service_type, const guint service_attrs, const gchar *service_id, const gchar *network_type, const guint network_attrs, const gchar *network_id)
static gboolean	icd_srv_provider_init (const gchar *module_name, void *handle, gpointer init_function, gpointer cb_data)
static void	icd_srv_provider_free_list (gpointer key, gpointer value, gpointer user_data)
gboolean	icd_srv_provider_load_modules (struct icd_context *icd_ctx)
void	icd_srv_provider_unload_modules (struct icd_context *icd_ctx)

---

Detailed Description

A service provider module is set up in gconf as follows: ICD_GCONF_SRV_PROVIDERS/<srv_type>/module name of the module to load ICD_GCONF_SRV_PROVIDERS/<srv_type>/network_type list of strings containing the network types supported

---

Define Documentation

#define ICD_SRV_PROVIDER_MODULE_NAME   "/module"

service provider entry for the module name

#define ICD_SRV_PROVIDER_NETWORK_TYPES   "/network_type"

service provider entry for supported network types

---

Typedef Documentation

typedef void(*) icd_srv_provider_connect_cb_fn(enum icd_srv_status status, const gchar *err_str, gpointer user_data)

Service provider connect callback function

Parameters:

	status	status of the connect
	err_str	error string or NULL on success
	user_data	user data

typedef void(*) icd_srv_provider_disconnect_cb_fn(enum icd_srv_status status, gpointer user_data)

Service provider disconnect callback function

Parameters:

	status	status of the connect
	user_data	user data

typedef gboolean(*) icd_srv_provider_foreach_module_fn(struct icd_srv_module *module, gpointer user_data)

Service provider api callback for going through every service provider module

Parameters:

	module	the service provider module
	user_data	user data passed to icd_srv_provider_foreach_module

Returns:

if TRUE the callback will be called again with the next module; if FALSE iteration is stopped

---

Function Documentation

static void icd_srv_provider_close	(	enum icd_srv_status	status,
		const gchar *	err_str,
		const gchar *	service_type,
		const guint	service_attrs,
		const gchar *	service_id,
		const gchar *	network_type,
		const guint	network_attrs,
		const gchar *	network_id
	)			[static]

Function to request closing down a connection due to internal or external events.

Parameters:

	status	reason for closing; ICD_SRV_RESTART if the connection needs to be restarted, success or error will both close the network connection
	err_str	NULL if the service provisioning was disconnected normally or any ICD_DBUS_ERROR_* from osso-ic-dbus.h on error
	service_type	the service type; currently ignored
	service_attrs	attributes; currently ignored
	service_id	internal service id; currently ignored
	network_type	the network type
	network_attrs	network attributes
	network_id	network id

gboolean icd_srv_provider_connect	(	struct icd_iap *	iap,
		icd_srv_provider_connect_cb_fn	cb,
		gpointer	user_data
	)

Run the service module, if any

Parameters:

	iap	the IAP
	cb	callback function
	user_data	user data for the callback function

Returns:

TRUE if the service module got called, FALSE if not

static void icd_srv_provider_connect_cb	(	enum icd_srv_status	status,
		const gchar *	err_str,
		gpointer	connect_cb_token
	)			[static]

Connect callback for the service provider module

Parameters:

	status	status of the connect attempt; with ICD_SRV_RESTART the IAP will be disconnected and reconnected again
	connect_cb_token	token passed to the connect function

gboolean icd_srv_provider_disconnect	(	struct icd_iap *	iap,
		icd_srv_provider_disconnect_cb_fn	cb,
		gpointer	user_data
	)

Disconnect the service module

Parameters:

	iap	the IAP
	cb	callback function
	user_data	user data for the callback function

Returns:

TRUE if the service module got called, FALSE if not

static void icd_srv_provider_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

struct icd_srv_module * icd_srv_provider_foreach_module	(	struct icd_context *	icd_ctx,
		icd_srv_provider_foreach_module_fn	foreach_fn,
		gpointer	user_data
	)

Iterate over all service provider modules

Parameters:

	icd_ctx	icd context
	foreach_fn	the function to call for each module
	user_data	user data to pass to the function

Returns:

a pointer to the module if the iteration function returns FALSE; NULL otherwise

static gboolean icd_srv_provider_foreach_module_pid	(	struct icd_srv_module *	srv_module,
		gpointer	user_data
	)			[static]

Find the srv provider module that is watching a child process exit

Parameters:

	module	the srv provider module to examine
	user_data	the pid notify structure

Returns:

TRUE to continue searching, FALSE to exit iteration and return a pointer to the module

static void icd_srv_provider_free_list	(	gpointer	key,
		gpointer	value,
		gpointer	user_data
	)			[static]

Wrapper function for removing a list that is a hash table value when stepping through a hash table

Parameters:

	key	key; ignored
	value	the list
	user_data	user data; ignored

gboolean icd_srv_provider_has_next

(

struct icd_iap *

iap

)

Check wheter there is a service module to run

Parameters:

iap

the IAP

Returns:

TRUE if there is a service module to run, FALSE otherwise

gboolean icd_srv_provider_identify	(	struct icd_network_module *	nw_module,
		struct icd_scan_cache *	cache_entry,
		enum icd_scan_status	status
	)

Send a network to be identified by possible service providers

Parameters:

	cache_entry	scan cache entry containing the data so far
	status	scan status

Returns:

TRUE if at least one service module was called, FALSE if not

static void icd_srv_provider_identify_cb	(	const enum icd_srv_identify_status	status,
		const gchar *	service_type,
		const gchar *	service_name,
		const guint	service_attrs,
		const gchar *	service_id,
		const gint	service_priority,
		const gchar *	network_type,
		const guint	network_attrs,
		const gchar *	network_id,
		gpointer	identify_cb_token
	)			[static]

Service identification callback.

Parameters:

	status	status of the identification procedure
	service_type	service type
	service_name	name of the service provider displayable to the user/UI
	service_attrs	service attributes
	service_id	internal service id
	service_priority	priority within a service type
	network_type	network type
	network_attrs	network attributes
	network_id	network_id
	identify_cb_token	the token passed to the identification function

Todo:

this sets the network priority for ALL entries, not just the service entry; for now it works as the preferred is only WIMAX, which does not have any networks without a service provider; the network part is created right here

static gboolean icd_srv_provider_init	(	const gchar *	module_name,
		void *	handle,
		gpointer	init_function,
		gpointer	cb_data
	)			[static]

Service provider plugin initialization callback function

Parameters:

	module_name	the moduel filename
	handle	module handle to pass unloading function
	init_function	a pointer to the plugin init function
	cb_data	user data passed to icd_plugin_load_all

Returns:

TRUE on success, FALSE on failure whereby the module is unloaded

static void icd_srv_provider_limited_conn	(	const enum icd_srv_limited_conn_status	conn_status,
		const gchar *	service_type,
		const guint	service_attrs,
		const gchar *	service_id,
		const gchar *	network_type,
		const guint	network_attrs,
		const gchar *	network_id
	)			[static]

Limited connectivity enabling and disabling.

Parameters:

	service_type	the service type
	service_attrs	attributes
	service_id	internal service id
	network_type	the network type
	network_attrs	network attributes
	network_id	network id

gboolean icd_srv_provider_load_modules

(

struct icd_context *

icd_ctx

)

Load service provider modueles

Parameters:

icd_ctx

icd context

Returns:

TRUE if at least one module got loaded, FALSE otherwise

gboolean icd_srv_provider_notify_pid	(	struct icd_context *	icd_ctx,
		const pid_t	pid,
		const gint	exit_value
	)

Notify a srv provider module that its child process has exited

Parameters:

	icd_ctx	the context
	pid	the process id
	exit_value	exit value

Returns:

TRUE if the process id was in use by the srv provider api; FALSE if not

void icd_srv_provider_unload_modules

(

struct icd_context *

icd_ctx

)

Unload all network modules

Parameters:

icd_ctx

icd context

static void icd_srv_provider_watch_pid	(	const pid_t	pid,
		gpointer	watch_cb_token
	)			[static]

Function for notifying ICd that a child process has been started. The srv provider destruction function will not be called before all child processes have exited.

Parameters:

	pid	process id
	watch_cb_token	the watch callback token given on initialization

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

---