Service Provider API


Classes

struct  icd_srv_api

Defines

#define ICD_SRV_MODULE_VERSION   ICD_NW_MODULE_VERSION

Typedefs

typedef void(* icd_srv_identify_cb_fn )(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)
typedef void(* icd_srv_identify_fn )(enum icd_scan_status status, const gchar *network_type, const gchar *network_name, const guint network_attrs, const gchar *network_id, const guint network_priority, enum icd_nw_levels signal, const gchar *station_id, const gint dB, icd_srv_identify_cb_fn identify_cb, gpointer identify_cb_token, gpointer *private)
typedef void(* icd_srv_disconnect_cb_fn )(enum icd_srv_status status, gpointer disconnect_cb_token)
typedef void(* icd_srv_disconnect_fn )(const gchar *service_type, const guint service_attrs, const gchar *service_id, const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_srv_disconnect_cb_fn disconnect_cb, gpointer disconnect_cb_token, gpointer *private)
typedef void(* icd_srv_connect_cb_fn )(enum icd_srv_status status, const gchar *err_str, gpointer connect_cb_token)
typedef void(* icd_srv_connect_fn )(const gchar *service_type, const guint service_attrs, const gchar *service_id, const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_srv_connect_cb_fn connect_cb, gpointer connect_cb_token, gpointer *private)
typedef void(* icd_srv_child_exit_fn )(const pid_t pid, const gint exit_status, gpointer *private)
typedef void(* icd_srv_destruct_fn )(gpointer *private)
typedef void(* icd_srv_watch_pid_fn )(const pid_t pid, gpointer watch_cb_token)
typedef void(* icd_srv_close_fn )(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)
typedef void(* icd_srv_limited_conn_fn )(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)
typedef gboolean(* icd_srv_init_fn )(struct icd_srv_api *srv_api, icd_srv_watch_pid_fn watch_cb, gpointer watch_cb_token, icd_srv_close_fn close, icd_srv_limited_conn_fn limited_conn)

Enumerations

enum  icd_srv_status { ICD_SRV_SUCCESS = 0, ICD_SRV_RESTART = 1, ICD_SRV_ERROR = 2 }
enum  icd_srv_identify_status { ICD_SRV_UNKNOWN = 0, ICD_SRV_IDENTIFIED = 1, ICD_SRV_CONTINUE = 8 }
enum  icd_srv_limited_conn_status { ICD_SRV_LIMITED_CONN_DISABLED = 0, ICD_SRV_LIMITED_CONN_ENABLED = 1 }

Detailed Description

The service provider API is considered beta quality, it may still be modified at some point.

The service provider API makes it possible to run tasks after an IP address has been acquired in the network module ip layer but before the network is announced to applications as being connected. The settings for a service module include the network types the service module is interested in, whereby the icd_srv_identify_fn() is called whenever there is a scan result available with a matching network type. In this way e.g. hotspot WLAN networks can be supported, since they need IP layer connectivity in order to reach an authentication service that usually means posting credentials on a web page.

In order for the network connection with an associated service module to succeed, icd_srv_connect_cb_fn() needs to be called with an ICD_SRV_SUCCESS status code. On error conditions or when closing the network connection the optional icd_srv_disconnect_fn() function is called, whereafter the network is disconnected as described in Network module API definitions.

The following service module settings are located at the gconf path /system/osso/connectivity/srv_provider/<service type name>:


Define Documentation

#define ICD_SRV_MODULE_VERSION   ICD_NW_MODULE_VERSION

Service provider module version equal to the network module version


Typedef Documentation

typedef void(* icd_srv_child_exit_fn)(const pid_t pid, const gint exit_status, gpointer *private)

Notification function for child process termination

Parameters:
pid the process id that exited
exit_value process exit value
private a reference to the icd_nw_api private member

typedef void(* icd_srv_close_fn)(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)

Prototype for the module to request closing down its 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
service_attrs attributes
service_id internal service id
network_type the network type
network_attrs network attributes
network_id network id

typedef void(* icd_srv_connect_cb_fn)(enum icd_srv_status status, const gchar *err_str, gpointer connect_cb_token)

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
err_str error string or NULL on success
connect_cb_token token passed to the connect function

typedef void(* icd_srv_connect_fn)(const gchar *service_type, const guint service_attrs, const gchar *service_id, const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_srv_connect_cb_fn connect_cb, gpointer connect_cb_token, gpointer *private)

Connect (or authenticate) with a service provider.

Parameters:
service_type service type
service_attrs service attributes
service_id internal id identifying the service
network_type type of network connected to
network_attrs network attributes
network_id network identification
interface_name network interface used
connect_cb callback to call when connection attempt is completed
connect_cb_token token to pass to the callback
private reference to the private icd_srv_api member

typedef void(* icd_srv_destruct_fn)(gpointer *private)

Destruction function that cleans up after the module. The list of network and service types in the icd_srv_api structure is deleted by ICd. The destruction function will not be called before all child processes have exited.

Parameters:
private a reference to the icd_nw_api private member

typedef void(* icd_srv_disconnect_cb_fn)(enum icd_srv_status status, gpointer disconnect_cb_token)

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

typedef void(* icd_srv_disconnect_fn)(const gchar *service_type, const guint service_attrs, const gchar *service_id, const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_srv_disconnect_cb_fn disconnect_cb, gpointer disconnect_cb_token, gpointer *private)

Disconnect function for the service provider module

Parameters:
service_type service type
service_attrs service attributes
service_id internal id identifying the service
network_type type of network connected to
network_attrs network attributes
network_id network identification
interface_name network interface used
disconnect_cb callback to call when disconnection is completed
disconnect_cb_token token to pass to the callback
private reference to the private icd_srv_api member

typedef void(* icd_srv_identify_cb_fn)(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)

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 that was identified
network_attrs network attributes that were identified
network_id network id that was identified
identify_cb_token the token passed to the identification function

typedef void(* icd_srv_identify_fn)(enum icd_scan_status status, const gchar *network_type, const gchar *network_name, const guint network_attrs, const gchar *network_id, const guint network_priority, enum icd_nw_levels signal, const gchar *station_id, const gint dB, icd_srv_identify_cb_fn identify_cb, gpointer identify_cb_token, gpointer *private)

Identify whether a given network is usable with this service provider. Even though this function has a callback, it is important that the decision is made as fast as possible in order not to slow down network scan processing. The service provider and network modules have to have a common understanding of both network_attrs and network_id parameters.

Parameters:
status status, see icd_scan_status
network_type network type
network_name name of the network displayable to the user
network_attrs network attributes
network_id network identification
signal signal strength
station_id station id, e.g. MAC address or similar id
dB absolute signal strength value in dB
identify_cb callback to call when the identification has been done
identify_cb_token token to pass to the identification callback

typedef gboolean(* icd_srv_init_fn)(struct icd_srv_api *srv_api, icd_srv_watch_pid_fn watch_cb, gpointer watch_cb_token, icd_srv_close_fn close, icd_srv_limited_conn_fn limited_conn)

Prototype for the service api initialization function. ICd searches each library for an instance of this function prototype called 'icd_srv_init'.

Parameters:
srv_api icd_srv_api structure to be filled in by the module
watch_cb function to inform ICd that a child process is to be monitored for exit status
watch_cb_token token to pass to the pid watch function
close_cb function to inform ICd that the network connection is to be closed
Returns:
TRUE on success, FALSE on failure whereby the module will be immediately unloaded

typedef void(* icd_srv_limited_conn_fn)(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)

Inform about enabled or disabled limited connectivity for service providing purposes. An example of limited connectivity is a network that allows IP connections only to certain authenticaion/log in server until the service module has finished its task. It is fully optional to use this function and full connectivity will be signalled when the network is connected.

Parameters:
conn_status whether limited connectivity is enabled or disabled
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

typedef void(* icd_srv_watch_pid_fn)(const pid_t pid, gpointer watch_cb_token)

Prototype function for notifying ICd that a child process has been started. The network 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


Enumeration Type Documentation

status of the network identification, use OR to add parts together

Enumerator:
ICD_SRV_UNKNOWN  the network is not identified by this service provider
ICD_SRV_IDENTIFIED  the network is identified to be used by this service provider
ICD_SRV_CONTINUE  whether there will be more identify results to come

Enabled/disabled limited connectivity status values

Enumerator:
ICD_SRV_LIMITED_CONN_DISABLED  Limited connectivity is disabled
ICD_SRV_LIMITED_CONN_ENABLED  Limited connectivity is enabled

status of the icd_srv_api function call returned in the callback

Enumerator:
ICD_SRV_SUCCESS  service provider (authentication) functionality succeeded; network connection is functioning
ICD_SRV_RESTART  restart this IAP; ICd will call all icd_nw_api '_down' functions for the associated network module and then restart from link_up all the way to the service API
ICD_SRV_ERROR  error; the IAP will be disconnected


Generated on Wed Sep 30 22:16:01 2009 for ICd2 by  doxygen 1.5.6