Network scan and scan result handling
[ICd internal functions]


Classes

struct  icd_scan_listener
struct  icd_scan_expire_network_data
struct  icd_scan_cache_list
struct  icd_scan_srv_provider
struct  icd_scan_cache
struct  icd_scan_cache_timeout

Typedefs

typedef void(*) icd_scan_cb_fn (enum icd_scan_status status, const struct icd_scan_srv_provider *srv_provider, const struct icd_scan_cache *cache_entry, gpointer user_data)

Functions

static gboolean string_equal (const gchar *a, const gchar *b)
void icd_scan_cache_entry_free (struct icd_scan_cache *cache_entry)
void icd_scan_cache_entry_add (struct icd_network_module *module, struct icd_scan_cache_list *scan_cache, struct icd_scan_cache *cache_entry)
icd_scan_cache_list * icd_scan_cache_list_lookup (struct icd_network_module *module, const gchar *network_id)
icd_scan_cache * icd_scan_cache_entry_find (struct icd_scan_cache_list *scan_cache_list, const gchar *network_type, const guint network_attrs)
gboolean icd_scan_cache_entry_remove (struct icd_scan_cache_list *scan_cache_list, const gchar *network_id, const gchar *network_type, const guint network_attrs)
static gboolean icd_scan_cache_rescan (gpointer data)
static void icd_scan_status_stop (struct icd_network_module *module)
static void icd_scan_status_start (struct icd_network_module *module)
static gboolean icd_scan_listener_exist (struct icd_network_module *module)
static gboolean icd_scan_listener_send_entry (struct icd_scan_srv_provider *srv_provider, struct icd_scan_cache *cache_entry, struct icd_scan_listener *listener, enum icd_scan_status status)
static void icd_scan_listener_send_list (gpointer key, gpointer value, gpointer user_data)
static gboolean icd_scan_cache_element_check (gpointer key, gpointer value, gpointer user_data)
static gboolean icd_scan_cache_has_elements (struct icd_network_module *module)
static void icd_scan_listener_send_cache (struct icd_network_module *module, struct icd_scan_listener *listener)
static gboolean icd_scan_listener_add (struct icd_network_module *module, const gchar *type, icd_scan_cb_fn cb, gpointer user_data)
static void icd_scan_listener_remove (struct icd_network_module *module, icd_scan_cb_fn cb, gpointer user_data)
void icd_scan_listener_notify (struct icd_network_module *module, struct icd_scan_srv_provider *srv_provider, struct icd_scan_cache *cache_entry, enum icd_scan_status status)
static gboolean icd_scan_expire_network (gpointer key, gpointer value, gpointer user_data)
static gboolean icd_scan_expire_network_for_hash (gpointer key, gpointer value, gpointer user_data)
static guint icd_scan_timeout_rescan_add (struct icd_network_module *module, guint seconds)
static guint icd_scan_timeout_add (struct icd_network_module *module, GSourceFunc expire_function, guint seconds)
static void icd_scan_timeout_free (struct icd_scan_cache_timeout *timeout_data)
static gboolean icd_scan_cache_expire (gpointer data)
static void icd_scan_cb (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)
static gboolean icd_scan_network (struct icd_network_module *module, const gchar *network_type)
static gboolean icd_scan_cache_remove_iap_for_module (struct icd_network_module *module, gpointer user_data)
void icd_scan_cache_remove_iap (gchar *iap_name)
gboolean icd_scan_results_request (const gchar *type, guint scope, icd_scan_cb_fn cb, gpointer user_data)
gboolean icd_scan_results_unregister (icd_scan_cb_fn cb, gpointer user_data)
gboolean icd_scan_cache_init (struct icd_network_module *module)
void icd_scan_cache_remove (struct icd_network_module *module)

Variables

const gchar const * icd_scan_status_names []

Detailed Description

Internally each module has a hash table of cached scan results. The hash table is accessed using the module internal network_id. Each hash table entry contains an icd_scan_cache_list structure with a singly linked list of networks. The icd_scan_cache_list structure is used because the pointer to the singly linked list must be updated whenever a network is removed. 
 +---+
 | n |   +GHashTable(network_idX)-+
 | w |-->|scan_cache_table        |
 |   |   +------------------------+
 | m |                     |  |  +->icd_scan_cache_list
 | o |                     |  |       +->GSlist for network_idN
 | d |                     |  |
 | u |                     |  +->icd_scan_cache_list
 | l |                     |       +->GSList for network_id2
 | e |                     |
 +---+                     |   ...
                           |
                           +->icd_scan_cache_list
                                +->GSList for network_idN

Typedef Documentation

typedef void(*) icd_scan_cb_fn(enum icd_scan_status status, const struct icd_scan_srv_provider *srv_provider, const struct icd_scan_cache *cache_entry, gpointer user_data)

Scan callback function for receiving scan results

Parameters:
status status of this network
srv_provider service provider entry; guaranteed to exist only for the lifetime of this callback function
cache_entry scan results; guaranteed to exist only for the lifetime of this callback function
user_data used data given to the scan callback

Function Documentation

static gboolean icd_scan_cache_element_check ( gpointer  key,
gpointer  value,
gpointer  user_data 
) [static]

Check for elements, return immediately on first element found

Parameters:
key the network_id, not used
value the icd_scan_cache_list
user_data not used
Returns:
TRUE on first non-NULL element found

void icd_scan_cache_entry_add ( struct icd_network_module *  module,
struct icd_scan_cache_list *  scan_cache,
struct icd_scan_cache *  cache_entry 
)

Add an cache entry to the network module

Parameters:
module network module
scan_cache scan cache list or NULL
cache_entry the entry to add

struct icd_scan_cache * icd_scan_cache_entry_find ( struct icd_scan_cache_list *  scan_cache_list,
const gchar *  network_type,
const guint  network_attrs 
)

Find a network entry in the scan cache list

Parameters:
scan_cache_list scan cache list
network_type network type
network_attrs network attrs
Returns:
the scan cache entry or NULL if not found

void icd_scan_cache_entry_free ( struct icd_scan_cache *  cache_entry  ) 

Free an icd_scan_cache structure

Parameters:
cache_entry cache entry to free

gboolean icd_scan_cache_entry_remove ( struct icd_scan_cache_list *  scan_cache_list,
const gchar *  network_id,
const gchar *  network_type,
const guint  network_attrs 
)

Remove scan cache from scan list, the removed entry does not call listener.

Parameters:
cache_list the icd_scan_cache_list struct
network_id network identifier
network_type the network type
network_attrs network attributes
Returns:
TRUE if scan entry was removed; FALSE otherwise

static gboolean icd_scan_cache_expire ( gpointer  data  )  [static]

Cache expiry function

Parameters:
data scan cache timeout data
Returns:
FALSE to remove the timeout

static gboolean icd_scan_cache_has_elements ( struct icd_network_module *  module  )  [static]

Check wheter a scan cache has any elements

Parameters:
module network module
Returns:
TRUE if there are elements, FALSE otherwise

gboolean icd_scan_cache_init ( struct icd_network_module *  module  ) 

Set up the scan cache for a network module

Parameters:
module network module

struct icd_scan_cache_list * icd_scan_cache_list_lookup ( struct icd_network_module *  module,
const gchar *  network_id 
)

Get the scan cache list associated with the network id

Parameters:
module network module
network_id network id
Returns:
the scan cache list or NULL if not found

void icd_scan_cache_remove ( struct icd_network_module *  module  ) 

Tear down the scan cache and its hash table

Parameters:
module the netowork module

void icd_scan_cache_remove_iap ( gchar *  iap_name  ) 

Function that removes all the IAPs from cache that match name.

Parameters:
iap_name IAP name

static gboolean icd_scan_cache_remove_iap_for_module ( struct icd_network_module *  module,
gpointer  user_data 
) [static]

Function that removes all the IAPs for a given module from cache that match name.

Parameters:
module the network module
IAP name
Returns:
TRUE so that foreach func will continue

static gboolean icd_scan_cache_rescan ( gpointer  data  )  [static]

Rescan timeout function

Parameters:
data scan cache timeout data
Returns:
FALSE so that the timeout won't repeat

static void icd_scan_cb ( 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 
) [static]

Callback function for scan results

Parameters:
status status of the operation
network_name name of the network displayable to user
network_type type of network
network_attrs network attributes
network_id network id
signal signal level
station_id base station id
dB raw signal strength
search_cb_token the network module structure

static gboolean icd_scan_expire_network ( gpointer  key,
gpointer  value,
gpointer  user_data 
) [static]

Hash table callback for removing an entry. Note that this function is also called outside of hash, so care should be taken when dealing with the hash (that is why list_entry is not deleted inside this function).

Parameters:
key the network_id
value the icd_scan_cache_list struct
user_data expiration time
Returns:
TRUE when all networks for the network_id have been expired and the hash table element can be removed; FALSE otherwise

static gboolean icd_scan_expire_network_for_hash ( gpointer  key,
gpointer  value,
gpointer  user_data 
) [static]

Hash table callback for removing an entry, this version is only called from hash remove func.

Parameters:
key the network_id
value the icd_scan_cache_list struct
user_data expiration time
Returns:
TRUE when all networks for the network_id have been expired and the hash table element can be removed; FALSE otherwise

static gboolean icd_scan_listener_add ( struct icd_network_module *  module,
const gchar *  type,
icd_scan_cb_fn  cb,
gpointer  user_data 
) [static]

Add a scan result listener to a module

Parameters:
module the module whose scan results to report
type the network type to receive scan results for
cb listener callback
user_data user data to pass to the callback
Returns:
TRUE when the callback is added to the list, FALSE on error

static gboolean icd_scan_listener_exist ( struct icd_network_module *  module  )  [static]

Check if there are any listeners that want scan results

Parameters:
module the network module
Returns:
TRUE if there are listeners, FALSE otherwise

void icd_scan_listener_notify ( struct icd_network_module *  module,
struct icd_scan_srv_provider *  srv_provider,
struct icd_scan_cache *  cache_entry,
enum icd_scan_status  status 
)

Notify each matching listener about the change in the cache entry

Parameters:
module the network module
srv_provider NULL or the specific service provider entry that got updated; if non-NULL only this service provider associated with the cache_entry will be sent to the listeners
cache_entry corresponding cache entry that got updated
status status of the notification

static void icd_scan_listener_remove ( struct icd_network_module *  module,
icd_scan_cb_fn  cb,
gpointer  user_data 
) [static]

Remove all matching listener callback - user data tuples from a module

Parameters:
module the network module
cb the callback to remove or NULL to remove all callbacks
user_data user data to remove

static void icd_scan_listener_send_cache ( struct icd_network_module *  module,
struct icd_scan_listener *  listener 
) [static]

Notify a (new) listener of the current cache

Parameters:
module the network module
listener the listener to update with the current cache

static gboolean icd_scan_listener_send_entry ( struct icd_scan_srv_provider *  srv_provider,
struct icd_scan_cache *  cache_entry,
struct icd_scan_listener *  listener,
enum icd_scan_status  status 
) [static]

Send the cache entry to the listener if the network type matches

Parameters:
srv_provider send only this service provider to the listener if set; send all network and service provider entries if NULL
cache_entry the cache entry
listener the listener
status the status of the supplied cache entry
Returns:
TRUE if the type matched and listener was updated; FALSE otherwise

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

Send all cache entries to the listener

Parameters:
key the network_id
value the icd_scan_cache_list
user_data the icd_scan_listener

static gboolean icd_scan_network ( struct icd_network_module *  module,
const gchar *  network_type 
) [static]

Request one network module to initiate scan with given scope

Parameters:
module the network module
network_type network type to scan for
Returns:
TRUE if scan was started or already ongoing, FALSE otherwise

gboolean icd_scan_results_request ( const gchar *  type,
guint  scope,
icd_scan_cb_fn  cb,
gpointer  user_data 
)

Function requesting scan results; can be called many times to add more than one network type per callback

Parameters:
type network type to scan or NULL for all networks
scope scope of the scan, see network_api.h
cb callback function for the results
user_data user data to pass to the callback
Returns:
TRUE if the callback is going to be called; FALSE on error

gboolean icd_scan_results_unregister ( icd_scan_cb_fn  cb,
gpointer  user_data 
)

Unregister all matching callback - user data tuples from receiving scan results

Parameters:
cb the same callback as given in icd_scan_results_request
user_data the same user_data as given in icd_scan_results_request
Returns:
TRUE if the callback - user_data tuple existed and was remvoed; FALSE otherwise

static void icd_scan_status_start ( struct icd_network_module *  module  )  [static]

Send scan start status

Parameters:
module network module

static void icd_scan_status_stop ( struct icd_network_module *  module  )  [static]

Send scan stop status

Parameters:
module network module

static guint icd_scan_timeout_add ( struct icd_network_module *  module,
GSourceFunc  expire_function,
guint  seconds 
) [static]

Add a pending timeout function. The timeout function must remove the timeout data structure if the same callback is not called repeatedly.

Parameters:
module the network module
expire_function function to call
seconds seconds until timeout
Returns:
id the timeout id

static void icd_scan_timeout_free ( struct icd_scan_cache_timeout *  timeout_data  )  [static]

Remove and g_free() the timeout data

Parameters:
timeout_data the timeout data to free

static guint icd_scan_timeout_rescan_add ( struct icd_network_module *  module,
guint  seconds 
) [static]

Add a rescan timeout.

Parameters:
module the network module
seconds seconds until timeout
Returns:
id the new timeout id

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 const* icd_scan_status_names[]

Initial value:

 {
  "ICD_SCAN_NEW",
  "ICD_SCAN_UPDATE",
  "ICD_SCAN_NOTIFY",
  "ICD_SCAN_EXPIRE",
  "ICD_SCAN_COMPLETE"
}
scan status name strings

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