The Connection Profile API provides functions for managing the connection profile.

Required Header

#include <net_connection.h>

Overview

The Connection Profile provides functions for mapping connection profile. It allows you to use a handle for dealing with a connection profile. You can get details about connection using ‘connection_profile_h’ handle.

Related Features

This API is related with the following features:

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature List.

Functions
int	connection_profile_create (connection_profile_type_e type, const char keyword, connection_profile_h profile)
	Creates a profile handle.
int	connection_profile_destroy (connection_profile_h profile)
	Destroys a profile handle.
int	connection_profile_clone (connection_profile_h *cloned_profile, connection_profile_h origin_profile)
	Clones a profile handle.
int	connection_profile_get_id (connection_profile_h profile, char **profile_id)
	Gets the profile ID.
int	connection_profile_get_name (connection_profile_h profile, char **profile_name)
	Gets the profile name.
int	connection_profile_get_type (connection_profile_h profile, connection_profile_type_e *type)
	Gets the network type.
int	connection_profile_get_network_interface_name (connection_profile_h profile, char **interface_name)
	Gets the name of the network interface, e.g. eth0 and pdp0.
int	connection_profile_refresh (connection_profile_h profile)
	Refreshes the profile information.
int	connection_profile_get_state (connection_profile_h profile, connection_profile_state_e *state)
	Gets the network type.
int	connection_profile_get_ip_config_type (connection_profile_h profile, connection_address_family_e address_family, connection_ip_config_type_e *type)
	Gets the IP config type.
int	connection_profile_get_ip_address (connection_profile_h profile, connection_address_family_e address_family, char **ip_address)
	Gets the IP address.
int	connection_profile_get_subnet_mask (connection_profile_h profile, connection_address_family_e address_family, char **subnet_mask)
	Gets the Subnet Mask.
int	connection_profile_get_gateway_address (connection_profile_h profile, connection_address_family_e address_family, char **gateway_address)
	Gets the Gateway address.
int	connection_profile_get_dns_address (connection_profile_h profile, int order, connection_address_family_e address_family, char **dns_address)
	Gets the DNS address.
int	connection_profile_get_proxy_type (connection_profile_h profile, connection_proxy_type_e *type)
	Gets the Proxy type.
int	connection_profile_get_proxy_address (connection_profile_h profile, connection_address_family_e address_family, char **proxy_address)
	Gets the Proxy address.
int	connection_profile_set_ip_config_type (connection_profile_h profile, connection_address_family_e address_family, connection_ip_config_type_e type)
	Sets the IP config type.
int	connection_profile_set_ip_address (connection_profile_h profile, connection_address_family_e address_family, const char *ip_address)
	Sets the IP address.
int	connection_profile_set_subnet_mask (connection_profile_h profile, connection_address_family_e address_family, const char *subnet_mask)
	Sets the Subnet Mask.
int	connection_profile_set_gateway_address (connection_profile_h profile, connection_address_family_e address_family, const char *gateway_address)
	Sets the Gateway address.
int	connection_profile_set_dns_address (connection_profile_h profile, int order, connection_address_family_e address_family, const char *dns_address)
	Sets the DNS address.
int	connection_profile_set_proxy_type (connection_profile_h profile, connection_proxy_type_e type)
	Sets the Proxy type.
int	connection_profile_set_proxy_address (connection_profile_h profile, connection_address_family_e address_family, const char *proxy_address)
	Sets the Proxy address.
int	connection_profile_set_state_changed_cb (connection_profile_h profile, connection_profile_state_changed_cb callback, void *user_data)
	Registers the callback that is called when the state of profile is changed.
int	connection_profile_unset_state_changed_cb (connection_profile_h profile)
	Unregisters the callback that is called when the state of profile is changed.
Typedefs
typedef void *	connection_profile_h
	The profile handle.
typedef void(*	connection_profile_state_changed_cb )(connection_profile_state_e state, void *user_data)
	Called when the state of the profile is changed.

Typedef Documentation

typedef void* connection_profile_h

The profile handle.

Since :: 2.3.1

typedef void(* connection_profile_state_changed_cb)(connection_profile_state_e state, void *user_data)

Called when the state of the profile is changed.

Since :: 2.3.1

Parameters:

[in]	state	The state
[in]	user_data	The user data passed from the callback registration function

See also:: connection_profile_set_state_changed_cb(); connection_profile_unset_state_changed_cb()

Enumeration Type Documentation

enum connection_address_family_e

Enumeration for address family.

Since :: 2.3.1

Enumerator:

CONNECTION_ADDRESS_FAMILY_IPV4	IPV4 Address type
CONNECTION_ADDRESS_FAMILY_IPV6	IPV6 Address type

enum connection_ip_config_type_e

Enumeration for IP configuration type.

Since :: 2.3.1

Enumerator:

CONNECTION_IP_CONFIG_TYPE_NONE	Not defined
CONNECTION_IP_CONFIG_TYPE_STATIC	Manual IP configuration
CONNECTION_IP_CONFIG_TYPE_DYNAMIC	Config IP using DHCP client
CONNECTION_IP_CONFIG_TYPE_AUTO	Config IP from Auto IP pool (169.254/16). Later with DHCP client, if available
CONNECTION_IP_CONFIG_TYPE_FIXED	Indicates an IP address that can not be modified

enum connection_profile_state_e

Enumeration for profile state type.

Since :: 2.3.1

Enumerator:

CONNECTION_PROFILE_STATE_DISCONNECTED	Disconnected state
CONNECTION_PROFILE_STATE_ASSOCIATION	Association state
CONNECTION_PROFILE_STATE_CONFIGURATION	Configuration state
CONNECTION_PROFILE_STATE_CONNECTED	Connected state

enum connection_profile_type_e

Enumeration for network connection type.

Since :: 2.3.1

Enumerator:

CONNECTION_PROFILE_TYPE_CELLULAR	Cellular type
CONNECTION_PROFILE_TYPE_WIFI	Wi-Fi type
CONNECTION_PROFILE_TYPE_ETHERNET	Ethernet type
CONNECTION_PROFILE_TYPE_BT	Bluetooth type

enum connection_proxy_type_e

Enumeration for proxy method type.

Since :: 2.3.1

Enumerator:

CONNECTION_PROXY_TYPE_DIRECT	Direct connection
CONNECTION_PROXY_TYPE_AUTO	Auto configuration(Use PAC file). If URL property is not set, DHCP/WPAD auto-discover will be tried
CONNECTION_PROXY_TYPE_MANUAL	Manual configuration

Function Documentation

int connection_profile_clone	(	connection_profile_h *	cloned_profile,
		connection_profile_h	origin_profile
	)

Clones a profile handle.

Since :: 2.3.1

Remarks:: You must release cloned_profile using connection_profile_destroy().

Parameters:

[out]	cloned_profile	The handle of the cloned profile
[in]	origin_profile	The handle of the origin profile

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory

See also:: connection_profile_destroy()

int connection_profile_create	(	connection_profile_type_e	type,
		const char *	keyword,
		connection_profile_h *	profile
	)

Creates a profile handle.

The profile name, which you get from connection_profile_get_name(), will include the keyword you set.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/network.profile
http://tizen.org/privilege/network.get

Remarks:: You must release profile using connection_profile_destroy().
This API needs both privileges.

Parameters:

[in]	type	The type of profile CONNECTION_PROFILE_TYPE_CELLULAR and CONNECTION_PROFILE_TYPE_WIFI are supported.
[in]	keyword	The keyword included in profile name
[out]	profile	The handle of the profile

Returns:: 0 on success, otherwise negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_NOT_SUPPORTED	Not supported

See also:: connection_profile_destroy(); connection_profile_get_name()

int connection_profile_destroy ( connection_profile_h profile )

Destroys a profile handle.

Since :: 2.3.1

Parameters:

[out] profile The handle to the profile

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: connection_profile_create()

int connection_profile_get_dns_address	(	connection_profile_h	profile,
		int	order,
		connection_address_family_e	address_family,
		char **	dns_address
	)

Gets the DNS address.

Since :: 2.3.1

Remarks:: The allowance of the DNS address is 2. You must release dns_address using free().

Parameters:

[in]	profile	The profile handle
[in]	order	The order of DNS address it starts from 1, which means first DNS address.
[in]	address_family	The address family
[out]	dns_address	The DNS address

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_gateway_address	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		char **	gateway_address
	)

Gets the Gateway address.

Since :: 2.3.1

Remarks:: You must release gateway_address using free().

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[out]	gateway_address	The gateway address

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_id	(	connection_profile_h	profile,
		char **	profile_id
	)

Gets the profile ID.

The separate profiles can have the same name. So, you must use this API instead of connection_profile_get_name() if you want to get the unique identification. In case you create a profile, this value will be determined when you add the profile.

Since :: 2.3.1

Remarks:: You must release profile_id using free().

Parameters:

[in]	profile	The profile handle
[out]	profile_id	The ID of the profile

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory

See also:: connection_profile_get_name(); connection_add_profile()

int connection_profile_get_ip_address	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		char **	ip_address
	)

Gets the IP address.

Since :: 2.3.1

Remarks:: You must release ip_address using free().

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[out]	ip_address	The IP address

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_ip_config_type	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		connection_ip_config_type_e *	type
	)

Gets the IP config type.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[out]	type	The type of the IP config

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_name	(	connection_profile_h	profile,
		char **	profile_name
	)

Gets the profile name.

Since :: 2.3.1

Remarks:: You must release profile_name using free().

Parameters:

[in]	profile	The profile handle
[out]	profile_name	The name of the profile

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory

See also:: connection_profile_get_id()

int connection_profile_get_network_interface_name	(	connection_profile_h	profile,
		char **	interface_name
	)

Gets the name of the network interface, e.g. eth0 and pdp0.

Since :: 2.3.1

Remarks:: You must release interface_name using free().

Parameters:

[in]	profile	The profile handle
[out]	interface_name	The name of the network interface

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory

int connection_profile_get_proxy_address	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		char **	proxy_address
	)

Gets the Proxy address.

Since :: 2.3.1

Remarks:: You must release proxy_address using free().

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[out]	proxy_address	The proxy address

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_proxy_type	(	connection_profile_h	profile,
		connection_proxy_type_e *	type
	)

Gets the Proxy type.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[out]	type	The type of the proxy

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_state	(	connection_profile_h	profile,
		connection_profile_state_e *	state
	)

Gets the network type.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[out]	state	The state of the profile

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_subnet_mask	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		char **	subnet_mask
	)

Gets the Subnet Mask.

Since :: 2.3.1

Remarks:: You must release subnet_mask using free().

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[out]	subnet_mask	The subnet mask

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_get_type	(	connection_profile_h	profile,
		connection_profile_type_e *	type
	)

Gets the network type.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[out]	type	The type of the profile

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_refresh ( connection_profile_h profile )

Refreshes the profile information.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/network.get

Remarks:: You should call this function in order to get the current information because the profile information can be changed.

Parameters:

[in] profile The profile handle

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed
CONNECTION_ERROR_OUT_OF_MEMORY	Out of memory
CONNECTION_ERROR_PERMISSION_DENIED	Permission Denied

int connection_profile_set_dns_address	(	connection_profile_h	profile,
		int	order,
		connection_address_family_e	address_family,
		const char *	dns_address
	)

Sets the DNS address.

Since :: 2.3.1

Remarks:: The allowance of the DNS address is 2.

Parameters:

[in]	profile	The profile handle
[in]	order	The order of the DNS address. It starts from `1`, which means first DNS address.
[in]	address_family	The address family
[in]	dns_address	The DNS address; if you set this value to NULL, then the existing value will be deleted

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

See also:: connection_update_profile()

int connection_profile_set_gateway_address	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		const char *	gateway_address
	)

Sets the Gateway address.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[in]	gateway_address	The gateway address. If you set this value to `NULL`, then the existing value will be deleted.

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

See also:: connection_update_profile()

int connection_profile_set_ip_address	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		const char *	ip_address
	)

Sets the IP address.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[in]	ip_address	The IP address. If you set this value to `NULL`, then the existing value will be deleted.

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

See also:: connection_update_profile()

int connection_profile_set_ip_config_type	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		connection_ip_config_type_e	type
	)

Sets the IP config type.

If you set IP config type to CONNECTION_IP_CONFIG_TYPE_STATIC, then IP address, Gateway and Subnet mask will be set to the initial value "0.0.0.0".

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[in]	type	The type of the IP config

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

int connection_profile_set_proxy_address	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		const char *	proxy_address
	)

Sets the Proxy address.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[in]	proxy_address	The proxy address. if you set this value to `NULL`, then the existing value will be deleted.

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

See also:: connection_update_profile()

int connection_profile_set_proxy_type	(	connection_profile_h	profile,
		connection_proxy_type_e	type
	)

Sets the Proxy type.

If you set the Proxy type to CONNECTION_PROXY_TYPE_AUTO or CONNECTION_PROXY_TYPE_MANUAL, then Proxy will be restored.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	type	The type of the proxy

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

See also:: connection_update_profile()

int connection_profile_set_state_changed_cb	(	connection_profile_h	profile,
		connection_profile_state_changed_cb	callback,
		void *	user_data
	)

Registers the callback that is called when the state of profile is changed.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	callback	The callback function to be called
[in]	user_data	The user data passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

Postcondition:: connection_opened_cb() is invoked when the state of profile is changed.

See also:: connection_profile_state_changed_cb(); connection_profile_unset_state_changed_cb()

int connection_profile_set_subnet_mask	(	connection_profile_h	profile,
		connection_address_family_e	address_family,
		const char *	subnet_mask
	)

Sets the Subnet Mask.

Since :: 2.3.1

Parameters:

[in]	profile	The profile handle
[in]	address_family	The address family
[in]	subnet_mask	The subnet mask. If you set this value to `NULL`, then the existing value will be deleted.

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter
CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED	Not supported address family
CONNECTION_ERROR_OPERATION_FAILED	Operation failed

See also:: connection_update_profile()

int connection_profile_unset_state_changed_cb ( connection_profile_h profile )

Unregisters the callback that is called when the state of profile is changed.

Since :: 2.3.1

Parameters:

[in] profile The profile handle

Returns:: 0 on success, otherwise a negative error value

Return values:

CONNECTION_ERROR_NONE	Successful
CONNECTION_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: connection_profile_state_changed_cb(); connection_profile_set_state_changed_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation