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:

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

ConIcConnectioncon_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.
ConIcIapcon_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

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.

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.

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:

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.


Generated on Tue Oct 13 14:46:14 2009 for Internet Connectivity API by  doxygen 1.5.6