Network module API


Classes

struct  icd_nw_api

Defines

#define ICD_NW_MODULE_VERSION   "@PACKAGE_VERSION@"
#define ICD_NW_ATTR_IAPNAME   0x01000000
#define ICD_NW_ATTR_SILENT   0x02000000
#define ICD_NW_ATTR_AUTOCONNECT   0x04000000
#define ICD_NW_ATTR_SRV_PROVIDER   0x10000000
#define ICD_NW_ATTR_LOCALMASK   0x00FFFFFF
#define ICD_NW_SEARCH_SCOPE_ALL   0x0
#define ICD_NW_SEARCH_SCOPE_SAVED   0x1

Typedefs

typedef void(*) icd_nw_layer_renew_cb_fn (enum icd_nw_renew_status status, gpointer renew_cb_token)
typedef void(*) icd_nw_layer_renew_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, icd_nw_layer_renew_cb_fn renew_cb, gpointer renew_cb_token, gpointer *private)
typedef void(*) icd_nw_ip_down_cb_fn (const enum icd_nw_status status, const gpointer ip_down_cb_token)
typedef void(*) icd_nw_ip_down_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_ip_down_cb_fn ip_down_cb, gpointer ip_down_cb_token, gpointer *private)
typedef void(*) icd_nw_ip_up_cb_fn (const enum icd_nw_status status, const gchar *err_str, const gpointer ip_up_cb_token,...)
typedef void(*) icd_nw_ip_up_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_ip_up_cb_fn ip_up_cb, gpointer ip_up_cb_token, gpointer *private)
typedef void(*) icd_nw_ip_addr_info_cb_fn (const gpointer addr_info_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, gchar *ip_address, gchar *ip_netmask, gchar *ip_gateway, gchar *ip_dns1, gchar *ip_dns2, gchar *ip_dns3)
typedef void(*) icd_nw_ip_addr_info_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_ip_addr_info_cb_fn cb, const gpointer addr_info_cb_token)
typedef void(*) icd_nw_ip_stats_cb_fn (const gpointer ip_stats_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, guint time_active, guint rx_bytes, guint tx_bytes)
typedef void(*) icd_nw_ip_stats_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_ip_stats_cb_fn cb, const gpointer ip_stats_cb_token)
typedef void(*) icd_nw_link_pre_down_cb_fn (const enum icd_nw_status status, const gpointer link_pre_down_cb_token)
typedef void(*) icd_nw_link_pre_down_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_link_pre_down_cb_fn link_pre_down_cb, const gpointer link_pre_down_cb_token, gpointer *private)
typedef void(*) icd_nw_link_post_up_cb_fn (const enum icd_nw_status status, const gchar *err_str, const gpointer link_post_up_cb_token,...)
typedef void(*) icd_nw_link_post_up_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_link_post_up_cb_fn link_post_up, const gpointer link_post_up_cb_token, gpointer *private)
typedef void(*) icd_nw_link_post_stats_cb_fn (const gpointer link_post_stats_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, guint time_active, guint rx_bytes, guint tx_bytes)
typedef void(*) icd_nw_link_post_stats_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_link_post_stats_cb_fn cb, const gpointer link_post_stats_cb_token)
typedef void(*) icd_nw_link_down_cb_fn (const enum icd_nw_status status, const gpointer link_down_cb_token)
typedef void(*) icd_nw_link_down_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_link_down_cb_fn link_down_cb, const gpointer link_down_cb_token, gpointer *private)
typedef void(*) icd_nw_link_up_cb_fn (const enum icd_nw_status status, const gchar *err_str, const gchar *interface_name, const gpointer link_up_cb_token,...)
typedef void(*) icd_nw_link_up_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, icd_nw_link_up_cb_fn link_up_cb, const gpointer link_up_cb_token, gpointer *private)
typedef void(*) icd_nw_link_stats_cb_fn (const gpointer link_stats_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, guint time_active, gint signal, gchar *station_id, gint dB, guint rx_bytes, guint tx_bytes)
typedef void(*) icd_nw_link_stats_fn (const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_link_stats_cb_fn cb, const gpointer link_stats_cb_token)
typedef void(*) icd_nw_search_cb_fn (enum icd_network_search_status status, gchar *network_name, gchar *network_type, const guint network_attrs, gchar *network_id, enum icd_nw_levels signal, gchar *station_id, gint dB, const gpointer search_cb_token)
typedef void(*) icd_nw_start_search_fn (const gchar *network_type, guint search_scope, icd_nw_search_cb_fn search_cb, const gpointer search_cb_token, gpointer *private)
typedef void(*) icd_nw_stop_search_fn (gpointer *private)
typedef void(*) icd_nw_child_exit_fn (const pid_t pid, const gint exit_value, gpointer *private)
typedef void(*) icd_nw_network_destruct_fn (gpointer *private)
typedef void(*) icd_nw_watch_pid_fn (const pid_t pid, gpointer watch_cb_token)
typedef void(*) icd_nw_close_fn (enum icd_nw_status status, const gchar *err_str, const gchar *network_type, const guint network_attrs, const gchar *network_id)
typedef void(*) icd_nw_status_change_fn (gchar *network_type, guint network_attrs, gchar *network_id)
typedef void(*) icd_nw_renew_fn (enum icd_nw_layer renew_layer, const gchar *network_type, const guint network_attrs, const gchar *network_id)
typedef gboolean(*) icd_nw_init_fn (struct icd_nw_api *network_api, icd_nw_watch_pid_fn watch_fn, gpointer watch_fn_token, icd_nw_close_fn close_fn, icd_nw_status_change_fn status_change_fn, icd_nw_renew_fn renew_fn)

Enumerations

enum  icd_nw_status {
  ICD_NW_SUCCESS = 0, ICD_NW_SUCCESS_NEXT_LAYER = 1, ICD_NW_RESTART = 2, ICD_NW_ERROR = 3,
  ICD_NW_TOO_MANY_CONNECTIONS = 4, ICD_NW_ERROR_USER_ACTION_DONE = 5, ICD_NW_RESTART_IP = 6, ICD_NW_RESTART_LINK_POST = 7,
  ICD_NW_RESTART_LINK = 8
}
enum  icd_nw_renew_status { ICD_NW_RENEW_NO_CHANGES = 0, ICD_NW_RENEW_CHANGES_MADE = 1 }
enum  icd_nw_levels {
  ICD_NW_LEVEL_NONE = 0, ICD_NW_LEVEL_1, ICD_NW_LEVEL_2, ICD_NW_LEVEL_3,
  ICD_NW_LEVEL_4, ICD_NW_LEVEL_5, ICD_NW_LEVEL_6, ICD_NW_LEVEL_7,
  ICD_NW_LEVEL_8, ICD_NW_LEVEL_9, ICD_NW_LEVEL_10
}
enum  icd_network_search_status { ICD_NW_SEARCH_CONTINUE = 0, ICD_NW_SEARCH_COMPLETE = 1, ICD_NW_SEARCH_EXPIRE = 2 }
enum  icd_nw_layer {
  ICD_NW_LAYER_NONE = 0, ICD_NW_LAYER_LINK = 1, ICD_NW_LAYER_LINK_POST = 2, ICD_NW_LAYER_IP = 3,
  ICD_NW_LAYER_SERVICE = 4, ICD_NW_LAYER_ALL = 5
}

Detailed Description

The network module API is considered stable.

A network in ICd is abstracted by a shared library implementing the network module API. A network module consists of three functionally different parts, one for searching for networks of the supported types, another for connecting and disconnecting and the third one for providing information about the connected network.

Each module must implement the icd_nw_init_fn() function, and the network module library package must create special settings in GConf in order to be loaded by ICd2. The settings define a unique network type string that will be used to look up modules needed when connecting networks with a particular type.

A network type is defined by the following entries in the gconf path /system/osso/connectivity/network_type/<network type name>

The module initialization function is fed an icd_nw_api structure, which the module needs to fill in with the functions it intends to support. A network module consists of three layers:

Each of the layers consist of *_up_fn() and *_down_fn() functions. In order to support the specified layer, an *_up_fn() function needs to be provided while a *_down_fn() function is optional. A module may choose to implement one or more of the network module layers.

When a network is being established, the specified modules will be run in the order defined in GConf. Thus when connecting to a network, the link layer functions icd_nw_link_up_fn() will be run one by one in the specified order for each network module, and the next module will be run only after the previous one has called icd_nw_link_up_cb_fn(). When all link layer module icd_nw_link_up_fn() functions have been successfully run, the post-link layer icd_nw_link_post_up_fn() functions will be run in the same order for each network module. Again ICd waits for the icd_nw_link_post_up_cb_fn() to be called before continuing. When all modules with a icd_nw_link_post_up_fn() have been called, the procedure is repeated for the IP layer. If an error condition or other unfavorable network event happens while the module tries to connect, the module will indicate this with a suitable icd_nw_status code in the callback function. When a callback function returns an error, ICd2 will start disconnecting the network connection, calling the _down_fn() functions in reverse order.

When the network module has been successfully connected but notices that the network connection it implements has been closed, e.g. due to connection loss, it must use icd_nw_close_fn() to inform ICd about the event. A network module must use the close function if it has already called the given *_cb_fn() and not call the callback function more than once.

ICd can request disconnection of a network at any time, either due to a network module calling icd_nw_close_fn(), a network callback returning error or a disconnection forced by a timer or requested by the user. When a disconnection takes place, network module *_down() functions are called in reverse order than their *_up() counterparts. A network module needs to be prepared that a disconnect can happen before a network module has called the respective *_up_cb_fn() callback, i.e. ICd will not wait for the callback to be called before starting the network module disconnection. When the disconnect procedure is completed, the network module calls the given *_down_cb_fn() function, whereby ICd continues with the next *_down_fn() function.

Network scanning is started with the icd_nw_start_search_fn() function. The start function will be called again if the search scope changes from ICD_NW_SEARCH_SCOPE_SAVED to ICD_NW_SEARCH_SCOPE_ALL. Scan results are passed to ICd2 with the icd_nw_search_cb_fn() callback function. When the network search is completed the module must call the callback with the ICD_NW_SEARCH_COMPLETE status code. If a module desires, it can invalidate any scanned networks by setting the ICD_NW_SEARCH_EXPIRE status code and filling in the network type, attributes and id for the expired network. Expiring a network can happen at any time, also after the network scan has ended. Scanning should be stopped when icd_nw_stop_search_fn() is called. After scan has ended or stopped, no more scan results are accepted except for expiring entries. ICd2 will automatically expire entries after the time given in the search_lifetime element of the icd_nw_api structure.

A network module may implement optional statistics functions. When a statistics request is received, network status is queried from the link layer from every module implementing icd_nw_link_stats_fn(), then for the link post layer from every module implementing icd_nw_link_post_stats_fn() and finally from every icd_nw_ip_stats_fn() function. The values from upper layers take precedence over the values supplied by lower layers with the signal, station id and dB values being unique statistics for the link layer. The IP layer can optionally support IP status information by implmenting the icd_nw_ip_addr_info_fn() function.

Any network module can ask a renewal of an network layer with the icd_nw_renew_fn() function. Usually the renewal is due to some specialized network condition in some special network case; network modules have no need to normally call the renew function. If a renew is requested for a specific icd_nw_layer network module layer, the corresponding renew functions icd_nw_api::link_renew, icd_nw_api::link_post_renew, icd_nw_api::ip_renew are called for each module that have the corresponding *_up() function. If the network renewal is successful and no side effects will be noticable by any other network module, the renew callback function shall return ICD_NW_RENEW_NO_CHANGES. If there are network changes affecting other parts of the network stack, ICD_NW_RENEW_CHANGES_MADE must be reported. A module layer without renew functions receiving a renew request will cause the IAP to be restarted.


Define Documentation

#define ICD_NW_ATTR_AUTOCONNECT   0x04000000

Whether we have all required credentials to authenticate ourselves to the network automatically without any user interaction

#define ICD_NW_ATTR_IAPNAME   0x01000000

Type of network id; set for IAP name, unset for local id, e.g. WLAN SSID

#define ICD_NW_ATTR_LOCALMASK   0x00FFFFFF

Mask for network attribute local values, e.g. security settings, WLAN mode, etc. These values might be evaluated by relevant UI components

#define ICD_NW_ATTR_SILENT   0x02000000

UI and user interaction forbidden if set, allowed if unset

#define ICD_NW_ATTR_SRV_PROVIDER   0x10000000

Whether this network always needs service provider support in order to get connected

#define ICD_NW_MODULE_VERSION   "@PACKAGE_VERSION@"

ICd2 version this network module is compiled against

#define ICD_NW_SEARCH_SCOPE_ALL   0x0

Search for all available networks in range

#define ICD_NW_SEARCH_SCOPE_SAVED   0x1

Search for saved IAPs


Typedef Documentation

typedef void(*) icd_nw_child_exit_fn(const pid_t pid, const gint exit_value, 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_nw_close_fn(enum icd_nw_status status, const gchar *err_str, const gchar *network_type, const guint network_attrs, const gchar *network_id)

Prototype for the module to request closing of its connection due to internal or external events. icd_nw_api '_down' functions will be called in order starting from top.

Parameters:
status reason for closing; ICD_NW_RESTART if the IAP needs to be restarted, success or error will both close the network connection
err_str NULL success, error string from osso-ic-dbus.h on failure
network_type the type of the IAP returned
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID

typedef gboolean(*) icd_nw_init_fn(struct icd_nw_api *network_api, icd_nw_watch_pid_fn watch_fn, gpointer watch_fn_token, icd_nw_close_fn close_fn, icd_nw_status_change_fn status_change_fn, icd_nw_renew_fn renew_fn)

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

Parameters:
network_api icd_nw_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 watch pid function
close_cb function to inform ICd that the network connection is to be closed
status_change function to inform ICd2 that the status of the network has changed while the network has been connected
renew function to request a network layer renewal
Returns:
TRUE on success; FALSE on failure whereby the module is unloaded

typedef void(*) icd_nw_ip_addr_info_cb_fn(const gpointer addr_info_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, gchar *ip_address, gchar *ip_netmask, gchar *ip_gateway, gchar *ip_dns1, gchar *ip_dns2, gchar *ip_dns3)

Receive IP address configuration information based on network type, attributes and id.

Parameters:
addr_info_cb_token token passed to the request function
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
private a reference to the icd_nw_api private member
ip_address IP address string or NULL if no such value
ip_netmask IP netmask string which or NULL if no such value
ip_gateway IP gateway string which or NULL if no such value
ip_dns1 DNS server IP address string or NULL if no such value
ip_dns2 DNS server IP address string or NULL if no such value
ip_dns3 DNS server IP address string or NULL if no such value
Returns:
TRUE if some of the values are returned, FALSE if no values assigned

typedef void(*) icd_nw_ip_addr_info_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_ip_addr_info_cb_fn cb, const gpointer addr_info_cb_token)

Request IP address configuration information based on network type, attributes and id.

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
private a reference to the icd_nw_api private member
cb callback function when delivering the data
addr_info_cb_token token to pass to the callback function

typedef void(*) icd_nw_ip_down_cb_fn(const enum icd_nw_status status, const gpointer ip_down_cb_token)

Callback function called when the IP address has been deconfigured

Parameters:
status status of the operation
ip_up_cb_token the callback token

typedef void(*) icd_nw_ip_down_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_ip_down_cb_fn ip_down_cb, gpointer ip_down_cb_token, gpointer *private)

Function for deconfiguring the IP layer, e.g. relasing the IP address. Normally this function need not to be provided as the libicd_network_ipv4 network module provides IP address deconfiguration in a generic fashion.

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
interface_name interface name
ip_down_cb callback function for notifying ICd when the IP address is deconfigured
ip_down_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_ip_stats_cb_fn(const gpointer ip_stats_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, guint time_active, guint rx_bytes, guint tx_bytes)

Receive ip statistics based on network type, attributes and id. Values are set to zero or NULL if statistics are not available or applicable

Parameters:
ip_stats_cb_token token passed to the request function
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
time_active time active, if applicable
rx_bytes bytes received on the link, if applicable
tx_bytes bytes sent on the link, if applicable
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_ip_stats_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_ip_stats_cb_fn cb, const gpointer ip_stats_cb_token)

Request ip statistics based on network type, attributes and id.

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
private a reference to the icd_nw_api private member
cb callback function when delivering the data
ip_stats_cb_token token to pass to the callback function

typedef void(*) icd_nw_ip_up_cb_fn(const enum icd_nw_status status, const gchar *err_str, const gpointer ip_up_cb_token,...)

Callback function called when IP address configuration has completed

Parameters:
status status of the operation
err_str NULL success, error string from osso-ic-dbus.h on failure
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

typedef void(*) icd_nw_ip_up_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_ip_up_cb_fn ip_up_cb, gpointer ip_up_cb_token, gpointer *private)

Function for configuring an IP address. Normally this function need not be provided as the libicd_network_ipv4 network module takes care of configuring IP addresses in a generic fashion.

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
interface_name interface name
link_up_cb callback function for notifying ICd when the IP address is configured
link_up_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_layer_renew_cb_fn(enum icd_nw_renew_status status, gpointer renew_cb_token)

Callback function called when the network module layer has been renewed

Parameters:
status status of the operation
renew_cb_token the callback token

typedef void(*) icd_nw_layer_renew_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, icd_nw_layer_renew_cb_fn renew_cb, gpointer renew_cb_token, gpointer *private)

Function for renewing a network module layer

Parameters:
network_type network type
network_attrs network attributes
network_id netowork id
renew_cb callback function for notifying ICd when the renewal is done
renew_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_link_down_cb_fn(const enum icd_nw_status status, const gpointer link_down_cb_token)

Callback notifying the status of icd_nw_link_down_fn

Parameters:
status status of the operation; ignored for now
link_down_cb_token the callback token

typedef void(*) icd_nw_link_down_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_link_down_cb_fn link_down_cb, const gpointer link_down_cb_token, gpointer *private)

Function to disconnect the link layer

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
interface_name interface name
link_down_cb callback function for notifying ICd when the link is down
link_down_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_link_post_stats_cb_fn(const gpointer link_post_stats_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, guint time_active, guint rx_bytes, guint tx_bytes)

Receive link post up statistics based on network type, attributes and id. Values are set to zero or NULL if statistics are not available or applicable

Parameters:
link_post_stats_cb_token token passed to the request function
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
time_active time active, if applicable
rx_bytes bytes received on the link, if applicable
tx_bytes bytes sent on the link, if applicable
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_link_post_stats_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_link_post_stats_cb_fn cb, const gpointer link_post_stats_cb_token)

Request link post up statistics based on network type, attributes and id.

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
private a reference to the icd_nw_api private member
cb callback function when delivering the data
link_post_stats_cb_token token to pass to the callback function

typedef void(*) icd_nw_link_post_up_cb_fn(const enum icd_nw_status status, const gchar *err_str, const gpointer link_post_up_cb_token,...)

Callback notifying the status of icd_nw_link_post_up_fn

Parameters:
status status of the operation
err_str NULL success, error string from osso-ic-dbus.h on failure
link_post_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

typedef void(*) icd_nw_link_post_up_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_link_post_up_cb_fn link_post_up, const gpointer link_post_up_cb_token, gpointer *private)

Function for performing link layer authentication after the link has been enabled

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
interface_name interface name
link_post_up_cb callback function for notifying ICd when the link post up function has completed
link_post_up_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_link_pre_down_cb_fn(const enum icd_nw_status status, const gpointer link_pre_down_cb_token)

Callback notifying the status of icd_nw_link_pre_down_fn

Parameters:
status status of the operation; ignored for now
link_pre_down_cb_token the callback token

typedef void(*) icd_nw_link_pre_down_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, const gchar *interface_name, icd_nw_link_pre_down_cb_fn link_pre_down_cb, const gpointer link_pre_down_cb_token, gpointer *private)

Function to disconnect the link layer authentication

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
interface_name interface name
link_pre_down_cb callback function for notifying ICd when the link is deauthenticate
link_pre_down_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_link_stats_cb_fn(const gpointer link_stats_cb_token, const gchar *network_type, const guint network_attrs, const gchar *network_id, guint time_active, gint signal, gchar *station_id, gint dB, guint rx_bytes, guint tx_bytes)

Receive link statistics based on network type, attributes and id. Values are set to zero or NULL if statistics are not available or applicable

Parameters:
link_stats_cb_token token passed to the request function
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
time_active time active, if applicable
signal signal level
station_id base station id, e.g. WLAN access point MAC address
dB raw signal strength; depends on the type of network
rx_bytes bytes received on the link, if applicable
tx_bytes bytes sent on the link, if applicable
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_link_stats_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, gpointer *private, icd_nw_link_stats_cb_fn cb, const gpointer link_stats_cb_token)

Request link statistics based on network type, attributes and id.

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id network id
private a reference to the icd_nw_api private member
cb callback function when delivering the data
link_stats_cb_token token to pass to the callback function

typedef void(*) icd_nw_link_up_cb_fn(const enum icd_nw_status status, const gchar *err_str, const gchar *interface_name, const gpointer link_up_cb_token,...)

Callback notifying the status of icd_nw_link_up_fn

Parameters:
status status of the operation
err_str NULL success, error string from osso-ic-dbus.h on failure
interface_name the device interface name on ICD_NW_SUCCESS; used for statistics gathering and post link up authentication
link_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

typedef void(*) icd_nw_link_up_fn(const gchar *network_type, const guint network_attrs, const gchar *network_id, icd_nw_link_up_cb_fn link_up_cb, const gpointer link_up_cb_token, gpointer *private)

Function to bring up the link layer

Parameters:
network_type network type
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
link_up_cb the callback function to call when the link is up
link_up_cb_token token to pass to the callback function
private a reference to the icd_nw_api private member

typedef void(*) icd_nw_network_destruct_fn(gpointer *private)

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

Parameters:
private reference to the 'private' member in the icd_nw_api structure

typedef void(*) icd_nw_renew_fn(enum icd_nw_layer renew_layer, const gchar *network_type, const guint network_attrs, const gchar *network_id)

Request a renewal for a specific network module layer.

Parameters:
renew_layer the network module layer to renew
network_type network type
network_attrs network_attrs
network_id network_id

typedef void(*) icd_nw_search_cb_fn(enum icd_network_search_status status, gchar *network_name, gchar *network_type, const guint network_attrs, gchar *network_id, enum icd_nw_levels signal, gchar *station_id, gint dB, const gpointer search_cb_token)

Callback for the search function.

Parameters:
status the status of the operation
network_name the name of the IAP to display by the UI
network_type the type of the IAP returned
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID
signal signal level
station_id base station id, e.g. WLAN access point MAC address
dB raw signal strength; depends on the type of network
search_cb_token the token given in icd_nw_search_fn

typedef void(*) icd_nw_start_search_fn(const gchar *network_type, guint search_scope, icd_nw_search_cb_fn search_cb, const gpointer search_cb_token, gpointer *private)

Function for listing the available networks provided by the module

Parameters:
network_type network type to search for or NULL for all networks; currently this will always be NULL. If you happen to report all networks with this entry being non-NULL, don't worry. ICd2 will take care of that too.
search_scope search scope, see ICD_NW_SEARCH_SCOPE_ALL and ICD_NW_SEARCH_SCOPE_SAVED
search_cb the search callback
search_cb_token token from the ICd to pass to the callback a reference to the icd_nw_api private member

typedef void(*) icd_nw_status_change_fn(gchar *network_type, guint network_attrs, gchar *network_id)

Status of the network has changed while the network has been connected

Parameters:
network_type the type of the IAP returned
network_attrs attributes, such as type of network_id, security, etc.
network_id IAP name or local id, e.g. SSID

typedef void(*) icd_nw_stop_search_fn(gpointer *private)

Function for stopping an ongoing search. The module must call the callback given in icd_nw_start_search_fn with status ICD_NW_SEARCH_COMPLETE as soon as search is stopped.

Parameters:
private a reference to the icd_nw_api private member

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

enum icd_network_search_status

search function callback status

Enumerator:
ICD_NW_SEARCH_CONTINUE  Search continues, more values to be expected soon
ICD_NW_SEARCH_COMPLETE  Search is completed or the module cannot continue due to some error; the search callback values are ignored
ICD_NW_SEARCH_EXPIRE  Search result is expired due to external reasons and needs to be removed immediately from the cache

enum icd_nw_layer

Network module layer

Enumerator:
ICD_NW_LAYER_NONE  No layer
ICD_NW_LAYER_LINK  Link layer
ICD_NW_LAYER_LINK_POST  Post-link or link authentication layer
ICD_NW_LAYER_IP  IP network layer
ICD_NW_LAYER_SERVICE  Service layer provided by a service module, see Service Provider API
ICD_NW_LAYER_ALL  All layers

enum icd_nw_levels

signal level from lowest (_NONE) to highest (_10)

Enumerator:
ICD_NW_LEVEL_NONE  no signal
ICD_NW_LEVEL_1  signal level 1
ICD_NW_LEVEL_2  signal level 2
ICD_NW_LEVEL_3  signal level 3
ICD_NW_LEVEL_4  signal level 4
ICD_NW_LEVEL_5  signal level 5
ICD_NW_LEVEL_6  signal level 6
ICD_NW_LEVEL_7  signal level 7
ICD_NW_LEVEL_8  signal level 8
ICD_NW_LEVEL_9  signal level 9
ICD_NW_LEVEL_10  signal level 10

enum icd_nw_renew_status

Renew status codes

Enumerator:
ICD_NW_RENEW_NO_CHANGES  No visible changes in any network parameters changed, no further action required
ICD_NW_RENEW_CHANGES_MADE  Network parameters have changed, restart this and above network layers

enum icd_nw_status

status of the icd_nw_api function call returned in respective callbacks

Enumerator:
ICD_NW_SUCCESS  function call succeeded; ICd will now call the next non-NULL icd_nw_api '_up' function on the same layer from any other module that has the same type but greater priority number
ICD_NW_SUCCESS_NEXT_LAYER  function call succeeded; ICd will now call the next non-NULL icd_nw_api '_up' function from the layer above. This status code is ignored on disconnect.
ICD_NW_RESTART  restart this IAP; ICd will first call the all icd_nw_api '_down' functions starting with the one for this level and then restart from link_up. This status code is ignored on disconnect.
ICD_NW_ERROR  generic error condition; the network will be closed down and the corresponding 'err_str' should contain more information on the error. The 'err_str' is currently formatted as a D-Bus error, e.g. "com.nokia.icd.error.somedescriptivestring". This status code is ignored on disconnect.
ICD_NW_TOO_MANY_CONNECTIONS  network module is already in use by another connection. This status code is ignored on disconnect.
ICD_NW_ERROR_USER_ACTION_DONE  network module has done all the needed user interaction, no need to show retry dialogs or similar. This status code is ignored on disconnect.
ICD_NW_RESTART_IP  Restart the IP layer of this IAP; ICd will first call the icd_srv_disconnect_fn if needed and then call any required icd_nw_ip_down_fn functions. When done, any required icd_nw_ip_up and icd_srv_connect_fn functions will be called normally. This status code is ignored on disconnection.
ICD_NW_RESTART_LINK_POST  Restart up to link post layer of this IAP; works similarly to ICD_NW_RESTART_IP. This status code is ignored on disconnect.
ICD_NW_RESTART_LINK  Restart up to link layer of this IAP; works similarly to ICD_NW_RESTART_IP. This status code is ignored on disconnect.


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