conicconnection.h File Reference

Detailed Description

ConIcConnection class.

ConIcConnection class can be used to request for Internet connections. Also it can be used retrieve current statistics, proxies and settings for Internet Access Points (IAPs).

Gobject signals

ConIcConnection has these gobject signals:

connection-event
statistics

The different signals are listed below as function prototypes for informational purposes. They are implemented as gobject signals.

"connection-event" signal

 void user_function(ConIcConnection *connection, 
                     ConIcConnectionEvent *event,
                     gpointer user_data);

When there's a new connection event for the application (eg. a connection is opened as requested), it sent as connection-event signal. ConIcConnectionEvent contains the status, for example CON_IC_STATUS_CONNECTED or CON_IC_STATUS_DISCONNECTED.

"statistics" signal

 void user_function(ConIcConnection *connection, 
                    ConIcStatisticsEvent *event,
                    gpointer user_data);

All statistics are sent using this signal as ConIcStatistics event.

Gobject properties

ConIcConnection has one gobject property:

 "automatic-connection-events"        gboolean              : Read / Write

If set to true, application will 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:: Automatic events are not stopped by Internet Connectivity system when con_ic_connection_connect() is called. The documentation was wrong and has now been updated.

#include <glib.h>
#include <glib-object.h>
#include <coniciap.h>

Typedefs

typedef struct _ConIcConnection ConIcConnection

ConIcConnection object.

Enumerations

enum ConIcConnectFlags { CON_IC_CONNECT_FLAG_NONE = 0, CON_IC_CONNECT_FLAG_AUTOMATICALLY_TRIGGERED = 1 << 0, CON_IC_CONNECT_FLAG_UNMANAGED = 1 << 1 }

Connection request flags. More...

enum ConIcProxyMode { CON_IC_PROXY_MODE_NONE, CON_IC_PROXY_MODE_MANUAL, CON_IC_PROXY_MODE_AUTO }

Proxy modes. More...

enum ConIcProxyProtocol {
CON_IC_PROXY_PROTOCOL_HTTP, CON_IC_PROXY_PROTOCOL_HTTPS, CON_IC_PROXY_PROTOCOL_FTP, CON_IC_PROXY_PROTOCOL_SOCKS,
CON_IC_PROXY_PROTOCOL_RTSP
}

Proxy protocol. More...

Functions

ConIcConnection * con_ic_connection_new (void)

Creates new ConIcConnection.

gboolean con_ic_connection_connect (ConIcConnection *connection, ConIcConnectFlags flags)

Request for a connection.

gboolean con_ic_connection_connect_by_id (ConIcConnection *connection, const gchar *id, ConIcConnectFlags flags)

Request for a connection using the IAP id.

gboolean con_ic_connection_disconnect (ConIcConnection *connection)

Disconnects all IAPs associated with the connection.

gboolean con_ic_connection_disconnect_by_id (ConIcConnection *connection, const gchar *id)

Disconnects specific IAP associated with the application.

gboolean con_ic_connection_statistics (ConIcConnection *connection, const gchar *id)

Requests statistics for a IAP.

ConIcProxyMode con_ic_connection_get_proxy_mode (ConIcConnection *connection)

Get current proxy mode.

GSList * con_ic_connection_get_proxy_ignore_hosts (ConIcConnection *connection)

Get a list of hosts to be ignored.

const gchar * con_ic_connection_get_proxy_autoconfig_url (ConIcConnection *connection)

Get the URL of Auto-Config Proxy.

const gchar * con_ic_connection_get_proxy_host (ConIcConnection *connection, ConIcProxyProtocol protocol)

Get proxy host.

gint con_ic_connection_get_proxy_port (ConIcConnection *connection, ConIcProxyProtocol protocol)

Get proxy port.

GSList * con_ic_connection_get_all_iaps (ConIcConnection *connection)

Get a list of all configured IAPs.

ConIcIap * con_ic_connection_get_iap (ConIcConnection *connection, const gchar *id)

Retrieve an IAP by id.

Typedef Documentation

typedef struct _ConIcConnection ConIcConnection

ConIcConnection object.

The contents of the object is private, use only the functions provided by conicconnection.h.

Enumeration Type Documentation

enum ConIcConnectFlags

Connection request flags.

With these flags special connection requests can be made. The flags can be ORred.

Normally just use CON_IC_CONNECT_FLAG_NONE.

Enumerator:

CON_IC_CONNECT_FLAG_NONE	No flags set.
CON_IC_CONNECT_FLAG_AUTOMATICALLY_TRIGGERED	Connection establishment wasn't started by a user action. Instead it was triggered by a timer, or something similar, event from the application. Using this flags means that if a connection isn't already established, the connection request will fail.
CON_IC_CONNECT_FLAG_UNMANAGED	Process requesting the connection won't be monitored for killing. Normally if the process died, it will be automatically detached from the connection. If this flag is set and process dies, the connection won't closed automatically.

enum ConIcProxyMode

Proxy modes.

Enumerator:

CON_IC_PROXY_MODE_NONE	No proxies set.
CON_IC_PROXY_MODE_MANUAL	Manual proxies set.
CON_IC_PROXY_MODE_AUTO	Automatic proxy URL set.

enum ConIcProxyProtocol

Proxy protocol.

Enumerator:

CON_IC_PROXY_PROTOCOL_HTTP	HTTP proxy protocol.
CON_IC_PROXY_PROTOCOL_HTTPS	HTTPS proxy protocol.
CON_IC_PROXY_PROTOCOL_FTP	FTP proxy protocol.
CON_IC_PROXY_PROTOCOL_SOCKS	SOCKS proxy protocol.
CON_IC_PROXY_PROTOCOL_RTSP	RTSP proxy protocol.

Function Documentation

gboolean con_ic_connection_connect	(	ConIcConnection *	connection,
		ConIcConnectFlags	flags
	)

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 from a ConIcConnection object. If the connection establishment succeeded, or there was already a connection established, a CON_IC_STATUS_CONNECTED inside ConIcConnectionEvent is sent. If connection establishment failed, a CON_IC_STATUS_DISCONNECTED inside ConIcConnectionEvent is sent and error is set accordingly.

Normally this one should be used.

Parameters:

	connection	ConIcConnection object.
	flags	Flags for the request.

Return values:

	TRUE	If no DBUS errors.
	FALSE	If a DBUS message couldn't be sent.

gboolean con_ic_connection_connect_by_id	(	ConIcConnection *	connection,
		const gchar *	id,
		ConIcConnectFlags	flags
	)

Request for a connection using the IAP id.

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 from a ConIcConnection object. If the connection establishment succeeded, or there was already a connection established, a CON_IC_STATUS_CONNECTED inside ConIcConnectionEvent is sent. If connection establishment failed, a CON_IC_STATUS_DISCONNECTED inside ConIcConnectionEvent is sent and error is set accordingly.

Normally con_ic_connection_connect() should be used. Use this one if you want to use a specific connection.

Parameters:

	connection	ConIcConnection object.
	flags	Flags for the request.
	id	Id of the requested IAP.

Return values:

	TRUE	If no DBUS errors.
	FALSE	If a DBUS message couldn't be sent.

gboolean con_ic_connection_disconnect ( ConIcConnection * connection )

Disconnects all IAPs associated with the connection.

Normally use this one.

Parameters:

connection

ConIcConnection object.

Return values:

	TRUE	If no DBUS errors.
	FALSE	If a DBUS message couldn't be sent.

gboolean con_ic_connection_disconnect_by_id	(	ConIcConnection *	connection,
		const gchar *	id
	)

Disconnects specific IAP associated with the application.

Normally use con_ic_connection_disconnect().

Parameters:

	connection	ConIcConnection object.
	id	Id of the IAP to disconnected.

Return values:

	TRUE	If no DBUS errors.
	FALSE	If a DBUS message couldn't be sent.

GSList* con_ic_connection_get_all_iaps ( ConIcConnection * connection )

Get a list of all configured IAPs.

Parameters:

connection

ConIcConnection object

Returns:: A singly linked list of ConIcIaps or NULL for error. Caller should free all ConIcIaps with g_object_unref() and the list itself with g_slist_free().

ConIcIap* con_ic_connection_get_iap	(	ConIcConnection *	connection,
		const gchar *	id
	)

Retrieve an IAP by id.

Returns:: ConIcIap gobject which caller must free with g_object_unref().

const gchar* con_ic_connection_get_proxy_autoconfig_url ( ConIcConnection * connection )

Get the URL of Auto-Config Proxy.

It is guaranteed that this function always returns the current and up-to-date settings.

Parameters:

connection

ConIcConnection object

Returns:: URL as a string. NULL, if no URL specified.

const gchar* con_ic_connection_get_proxy_host	(	ConIcConnection *	connection,
		ConIcProxyProtocol	protocol
	)

Get proxy host.

Parameters:

	connection	ConIcConnection object
	protocol	Protocol, for which the proxy host should be returned

Returns:: hostname of the proxy for the protocol

GSList* con_ic_connection_get_proxy_ignore_hosts ( ConIcConnection * connection )

Get a list of hosts to be ignored.

Connections to these hosts shouldn't use proxies.

It is guaranteed that this function always returns the current and up-to-date settings.

Parameters:

connection

ConIcConnection object

Returns:: A GSList of strings, which contain the hosts. Free all strings individually, and the list with g_slist_free(). NULL, if no hosts specified.

ConIcProxyMode con_ic_connection_get_proxy_mode ( ConIcConnection * connection )

Get current proxy mode.

If proxy mode is CON_IC_PROXY_MODE_NONE, do not use proxies at all.

If proxy mode is CON_IC_PROXY_MODE_MANUAL, use proxies and only use these functions to get the proxy settings:

If proxy mode is CON_IC_PROXY_MODE_AUTO, then only use Proxy Auto-config file specified in <http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/proxy-live.html>. To get the URL for the file, use this function:

con_ic_connection_get_proxy_autoconfig_url()

gint con_ic_connection_get_proxy_port	(	ConIcConnection *	connection,
		ConIcProxyProtocol	protocol
	)

Get proxy port.

Parameters:

	connection	ConIcConnection object
	protocol	Protocol, for which the proxy port should be returned

Returns:: port number of the proxy host for the protocol

ConIcConnection* con_ic_connection_new ( void )

Creates new ConIcConnection.

When not needed anymore, release with g_object_unref().

Creating the object does not yet open the connection. Use, for example, con_ic_connection_connect() to do that.

Returns:: New ConIcConnection object. NULL, if the object creation failed.

gboolean con_ic_connection_statistics	(	ConIcConnection *	connection,
		const gchar *	id
	)

Requests statistics for a IAP.

The answer is sent as ConIcStatistics in statistics signal.

Parameters:

	connection	ConIcConnection object.
	id	Id of the IAP

Return values:

	TRUE	If no DBUS errors.
	FALSE	If a DBUS message couldn't be sent. No statistics events will be emitted.


Typedefs
typedef struct _ConIcConnection	ConIcConnection
	ConIcConnection object.
Enumerations
enum	ConIcConnectFlags { CON_IC_CONNECT_FLAG_NONE = 0, CON_IC_CONNECT_FLAG_AUTOMATICALLY_TRIGGERED = 1 << 0, CON_IC_CONNECT_FLAG_UNMANAGED = 1 << 1 }
	Connection request flags. More...
enum	ConIcProxyMode { CON_IC_PROXY_MODE_NONE, CON_IC_PROXY_MODE_MANUAL, CON_IC_PROXY_MODE_AUTO }
	Proxy modes. More...
enum	ConIcProxyProtocol { CON_IC_PROXY_PROTOCOL_HTTP, CON_IC_PROXY_PROTOCOL_HTTPS, CON_IC_PROXY_PROTOCOL_FTP, CON_IC_PROXY_PROTOCOL_SOCKS, CON_IC_PROXY_PROTOCOL_RTSP }
	Proxy protocol. More...
Functions
ConIcConnection *	con_ic_connection_new (void)
	Creates new ConIcConnection.
gboolean	con_ic_connection_connect (ConIcConnection *connection, ConIcConnectFlags flags)
	Request for a connection.
gboolean	con_ic_connection_connect_by_id (ConIcConnection connection, const gchar id, ConIcConnectFlags flags)
	Request for a connection using the IAP id.
gboolean	con_ic_connection_disconnect (ConIcConnection *connection)
	Disconnects all IAPs associated with the connection.
gboolean	con_ic_connection_disconnect_by_id (ConIcConnection connection, const gchar id)
	Disconnects specific IAP associated with the application.
gboolean	con_ic_connection_statistics (ConIcConnection connection, const gchar id)
	Requests statistics for a IAP.
ConIcProxyMode	con_ic_connection_get_proxy_mode (ConIcConnection *connection)
	Get current proxy mode.
GSList *	con_ic_connection_get_proxy_ignore_hosts (ConIcConnection *connection)
	Get a list of hosts to be ignored.
const gchar *	con_ic_connection_get_proxy_autoconfig_url (ConIcConnection *connection)
	Get the URL of Auto-Config Proxy.
const gchar *	con_ic_connection_get_proxy_host (ConIcConnection *connection, ConIcProxyProtocol protocol)
	Get proxy host.
gint	con_ic_connection_get_proxy_port (ConIcConnection *connection, ConIcProxyProtocol protocol)
	Get proxy port.
GSList *	con_ic_connection_get_all_iaps (ConIcConnection *connection)
	Get a list of all configured IAPs.
ConIcIap *	con_ic_connection_get_iap (ConIcConnection connection, const gchar id)
	Retrieve an IAP by id.