Internet Connectivity (IC) API is used by applications to request for
Internet connections. The current API is described in the file
/usr/include/osso-ic.h from osso-ic-dev.
Now I have started to update the API based on the feedback I have
received. For example, it's now possible to follow connection status
using the API. In the attached header file there is a draft of the new
IC API. Being still just a draft, the comments are still quite vague,
but hopefully the API is still readable.
If you want to comment the IC API, in the list or privately, now is
the time to do it. Thanks.
--
Kalle Valo
/* osso-ic-6.h
*/
#include <glib/gtypes.h>
#include <glib/gslist.h>
/*
* registration
*/
/* OssoIcConnection gobject. */
typedef struct _OssoIcConnection OssoIcConnection;
/* Creates new OssoIcConnection. Creating the object does not yet open the
* connection. */
OssoIcConnection *osso_ic_connection_new();
/*
* OssoIcConnection has these gobject signals:
* - connection-event
* - statistics
*
* The different signals are listed below as function prototypes for
* informational purposes. They will be implemented as gobject signals in
* the final API.
*
* "connection-event" signal
*
* When there's a new connection event for the application (eg. a
* connection is opened as requested), it sent as connection-event signal.
* OssoIcConnectionEvent contains the status, for example
* OSSO_IC_STATUS_CONNECTED or OSSO_IC_STATUS_DISCONNECTED.
*
* void user_function(OssoIcConnection *connection,
* OssoIcConnectionEvent *event,
* gpointer user_data);
*
* "statistics" signal
*
* All statistics are sent using this signal as OssoIcStatistics event.
*
* void user_function(OssoIcConnection *connection,
* OssoIcStatisticsEvent *event,
* gpointer user_data);
*/
/* connect request flags */
typedef enum {
OSSO_IC_CONNECT_FLAG_NONE = 0,
OSSO_IC_CONNECT_FLAG_AUTOMATICALLY_TRIGGERED = 1 << 0,
OSSO_IC_CONNECT_FLAG_UNMANAGED = 1 << 1
} OssoIcConnectFlags;
/* Request for a connection. The Internet Connectivity subsystem will
* choose the best connection based on user settings and input provided by
* the user.
*
* Answer is sent using the connection-event signal. If connection
* establishment succeeded or there was already a connection established, a
* OSSO_IC_STATUS_CONNECTED in OssoIcConnectionEvent is sent. If there
* wasn't a connection and connection establishment failed, a
* OSSO_IC_STATUS_DISCONNECTED in OssoIcConnectionEvent is sent and error
* is set accordingly. */
gboolean osso_ic_connection_connect(OssoIcConnection *connection,
OssoIcConnectFlags flags);
/* Request for a specific connection using the IAP name. */
gboolean osso_ic_connection_connect_by_name(OssoIcConnection *connection,
const gchar *iap,
OssoIcConnectFlags flags);
/* Disconnects all IAPs associated with the application. Normally use this
* one. */
gboolean osso_ic_connection_disconnect(OssoIcConnection *connection);
/* Disconnects specific IAP associated with the application. Normally this
* isn't used. */
gboolean osso_ic_connection_disconnect_by_name(OssoIcConnection *connection,
const gchar *iap);
/*
* OssoIcConnection gobject property:
*
* "automatic-connection-events" gboolean : Read / Write
*
* If set to true, receive connection-events automatically as connections
* are established and tore down. Normally events are only sent when
* applications request for a connection, with this all events are received
* constantly. This makes it possible, for example, to create an
* application which executes something from the network every time a
* connection is established.
*
* Note: the automatic events are stopped by Internet Connectivity
* system when connect() is called and started again after DISCONNECT event
* is received
*/
/* Requests statistics, the answer is sent as OssoIcStatics in statistics
* signal. */
gboolean osso_ic_connectoin_statistics(OssoIcConnection *connection,
const gchar *iap);
typedef enum {
OSSO_IC_PROXY_MODE_NONE,
OSSO_IC_PROXY_MODE_MANUAL,
OSSO_IC_PROXY_MODE_AUTO
} OssoIcProxyMode;
/* Get proxy mode from the event. */
OssoIcProxyMode osso_ic_connection_get_proxy_mode(OssoIcConnection *connection);
/* If proxy mode is OSSO_IC_PROXY_MODE_NONE, do not use proxies at all. */
/* If proxy mode is OSSO_IC_PROXY_MODE_MANUAL, use only these functions: */
gchar *osso_ic_connection_get_proxy_http_host(OssoIcConnection *connection);
gint osso_ic_connection_get_proxy_http_port(OssoIcConnection *connection);
GSList *osso_ic_connection_get_proxy_ignore_hosts(OssoIcConnection *connection);
gchar *osso_ic_connection_get_proxy_ftp_host(OssoIcConnection *connection);
gint osso_ic_connection_get_proxy_ftp_port(OssoIcConnection *connection);
gchar *osso_ic_connection_get_proxy_https_host(OssoIcConnection *connection);
gint osso_ic_connection_get_proxy_https_port(OssoIcConnection *connection);
gchar *osso_ic_connection_get_proxy_socks_host(OssoIcConnection *connection);
gint osso_ic_connection_get_proxy_socks_port(OssoIcConnection *connection);
gchar *osso_ic_connection_get_proxy_rtsp_host(OssoIcConnection *connection);
gint osso_ic_connection_get_proxy_rtsp_port(OssoIcConnection *connection);
/* If proxy mode is OSSO_IC_PROXY_MODE_AUTO, use only this function: */
gchar *osso_ic_connection_get_autoconfig_url(OssoIcConnection *connection);
/* OssoIcEvent gobject, an abstract type from which all event types
* derive. */
typedef struct _OssoIcEvent OssoIcEvent;
/* Get the name of the IAP this event is associated with. */
gchar *osso_ic_event_get_iap_name(OssoIcEvent *event);
/* Get bearer type of the IAP this event is associated with. */
gchar *osso_ic_event_get_bearer_type(OssoIcEvent *event);
/* gobject, derived from OssoIcEvent. Contains the new status of the IAP. */
typedef struct _OssoIcConnectionEvent OssoIcConnectionEvent;
/* IAP connection statuses.
*
* Note: more status types might be added in the future */
typedef enum {
OSSO_IC_STATUS_CONNECTED,
OSSO_IC_STATUS_DISCONNECTED,
OSSO_IC_STATUS_DISCONNECTING
} OssoIcConnectionStatus;
/* Error codes for connection events. Only set in DISCONNECTED
* events, otherwise set to OSSO_IC_CONNECTION_ERROR_NONE.
*
* Note: more error types might be added in the future */
typedef enum {
OSSO_IC_CONNECTION_ERROR_NONE,
OSSO_IC_CONNECTION_ERROR_INVALID_IAP,
OSSO_IC_CONNECTION_ERROR_CONNECTION_FAILED,
OSSO_IC_CONNECTION_ERROR_USER_CANCELED
} OssoIcConnectionError;
OssoIcConnectionStatus
osso_ic_connection_event_get_status(OssoIcConnectionEvent *event);
OssoIcConnectionError osso_ic_connection_event_get_error(OssoIcConnectionEvent
*event);
/* gobject, derived from OssoIcEvent. Contains current statistics. Received
* with statistics signal.*/
typedef struct _OssoIcStatisticsEvent OssoIcStatisticsEvent;
guint osso_ic_statistics_event_get_time_active(OssoIcStatisticsEvent
*statistics);
guint osso_ic_statistics_event_get_signal_strength(OssoIcStatisticsEvent
*statistics);
guint64 osso_ic_statistics_event_get_rx_packets(OssoIcStatisticsEvent
*statistics);
guint64 osso_ic_statistics_event_get_tx_packets(OssoIcStatisticsEvent
*statistics);
guint64 osso_ic_statistics_event_get_rx_bytes(OssoIcStatisticsEvent
*statistics);
guint64 osso_ic_statistics_event_get_tx_bytes(OssoIcStatisticsEvent
*statistics);
/* OssoIcIap gobject. */
typedef struct _OssoIcIap OssoIcIap;
/* Returns the name of the IAP as string. Caller must free the string with
g_free(). */
gchar *osso_ic_iap_get_name(OssoIcIap *iap);
/* Return the bearer type of the IAP. Caller must free the string with
* g_free(). See OSSO_IC_BEARER macros for current types. */
gchar *osso_ic_iap_get_bearer_type(OssoIcIap *iap);
/* The bearer types returned by osso_ic_iap_get_bearer_type() and
* osso_ic_event_get bearer_type().
*
* Note: more bearer types might be added in the future */
#define OSSO_IC_BEARER_WLAN_INFRA "WLAN_INFRA"
#define OSSO_IC_BEARER_WLAN_ADHOC "WLAN_ADHOC"
#define OSSO_IC_BEARER_DUN_GSM_CS "DUN_GSM_CS"
#define OSSO_IC_BEARER_DUN_GSM_PS "DUN_GSM_PS"
/* Get a list of IAPs. Returns a singly linked list of OssoIcIaps or
* NULL for error. Caller should free all OssoIcIaps with g_object_unref()
* and the list itself with g_slist_free(). */
GSList *osso_ic_connection_get_all_iaps(OssoIcConnection *connection);
/* Retrieve an IAP by name. Returns OssoIcIap gobject which caller must
free with g_object_unref(). */
OssoIcIap *osso_ic_connection_get_iap(OssoIcConnection *connection,
gchar *name);
/* example: basic application requesting for connection (similar as in
* sputnik) and the connection establishment succeeds
int main(int argc, char **argv) {
OssoIcConnection *connection;
struct FooCtxt my_ctxt;
connection = osso_ic_connection_new();
g_signal_connect(G_OBJECT(connection), "connection-event",
G_CALLBACK(connection_cb), &my_ctxt);
osso_ic_connect(connection, OSSO_IC_CONNECT_FLAG_NONE);
}
IC library calls connectivity_cb with (connection, &OssoIcConnectionEvent,
my_ctxt) as parameters after the connection established (status will be
OSSO_IC_STATUS_CONNECTED) or it failed (status will be
OSSO_IC_STATUS_DISCONNECTED).
void connection_cb(OssoIc *connection, OssoIcConnectionEvent *event,
gpointer user_data) {
status = osso_ic_connection_event_get_status(event);
if (status == OSSO_IC_STATUS_CONNECTED) {
connection is now up, application saves IAP name and starts
using the network
iap_name = osso_ic_event_get_name(event);
fd = socket(...)
}
} else if (type == OSSO_IC_STATUS_DISCONNECTED) {
shutdown(fd, SHUT_RDWR);
}
}
*/
/* example: application listening to the connection events all the time
int main(int argc, char **argv) {
OssoIcConnection *connection;
struct FooCtxt my_ctxt;
connection = osso_ic_connection_new();
g_signal_connect(G_OBJECT(connection), "connection-event",
G_CALLBACK(connection_cb), &my_ctxt);
g_object_set(connection, "automatic-connection-events", TRUE);
}
IC library calls connectivity_cb with (&connection, &OssoIcConnectionEvent,
&my_ctxt) as parameters always when connected or disconnected
void connection_cb(OssoIcConnetion *connection, OssoIcConnectionEvent *event,
gpointer user_data) {
status = osso_ic_connection_event_get_status(event);
if (status == OSSO_IC_STATUS_CONNECTED) {
connection is now up, application saves IAP name and starts
using the network
iap_name = osso_ic_event_get_name(OSSO_IC_EVENT(event));
update_data();
}
} else if (status == OSSO_IC_STATUS_DISCONNECTED) {
stop_update();
}
}
*/
_______________________________________________
maemo-developers mailing list
[email protected]
https://maemo.org/mailman/listinfo/maemo-developers
