One Click Connectivity (OCC) - A guide for developers
From Symbian Developer Community
One Click Connectivity (OCC) is the next big step in advanced connectivity usability in Symbian^3 and follows the introduction of Application Level Roaming (ALR) in S60 3.2. The main benefits OCC brings are:
- Connectivity settings gathered in a centralised place
- New global settings to configure platform wide connectivity behaviour: cellular access in home/visitor network, forced reconnection to higher priority connection, e.g., from cellular to WLAN
- Extended Connection Preferences API (Extendedconnpref API) that can be used to control the connection behaviour.
- New connection state related soft-notes
The objective of the OCC initiative is to create a consistent user experience for connectivity applications in Symbian devices: no unnecessary prompts and no unnecessary dialogs.
This information is written to explain this new functionality in the context of how different applications should adapt and take advantage of this new middleware which the OCC initiative will introduce on a platform-wide basis from Symbian^3.
Contents |
From Symbian^2, users can create a WLAN connection using the WLAN Sniffer. This connection is referred to as the "user connection". "User connection" is offered to an application requesting connection to the Internet SNAP, Connection Selection Dialog ("Ask when needed"), default connection or to an IAP that belongs to Internet SNAP. Applications can disregard user connection by requesting a connection to a specific IAP using the new Extended Connection Preferences API. Applications utilising ALR will see creation of "user connection" as a call to preferredCarrierAvailable() function.
A selection of code examples for each of the features described in this section can be found here.
See also a guide for migrating from Access Point Engine APIs to Connection Settings API here.
Extended Connection Preferences API
A new Extendedconnpref API is introduced with Symbian^3 that allows applications to have more control over the connectivity behaviour. Normal applications requiring internet connectivity should not need to use this API but it may be useful in some specific use cases. Applications that need to pass any parameters (IAP, SNAP, etc.) to RConnection, should use Extended Connection Preferences API instead of the old alternatives, TConnSnapPref or TCommDbConnPref. Below is a short description of its features. Code examples on using Extendedconnpref API can be found here.
Opening a connection without the new discreet pop-ups
In Symbian^3, there will be new discreet pop-ups indicating the state of the connection. These pop-ups provide visibility to the end-user about how the phone connects to the Internet. Tapping the pop-up opens the Connection Manager view which allows the user to see more information about the connection and disconnect it if needed. If for some good reason, an application doesn't wish to show these pop-ups, Extendedconnpref API can be used to hide them.
Opening a connection without any queries
OCC introduces two new platform wide settings to control the use of cellular data in home and visitor networks. If the setting is set to "Confirm", the end user will be shown a dialog and the user will have to explicitly grant a permission to open a cellular connection. Extendedconnpref API can be used to hide these dialogs. It should be noted that the platform wide settings will be obeyed still. If the setting is set to "Always ask" or "WLAN only", the connection opening will just fail with KErrPermissionDenied. If an IAP ID is passed via the Extendedconnpref API, the functionality is the same as in current 3.2 and 5.0 products (see "Opening a connection to a specific IAP").
Handling contention
Extendedconnpref API can be used to hide the Disconnect Dialog. Some applications wish to handle contention situations themselves. The Disconnect Dialog is shown e.g. when there are too many packet data connections already active. The Disconnect Dialog shows a list of active connections and the end user can select the one to be disconnected to allow the new connection request to proceed.
Bearer filtering
Extendedconnpref API allows the application to request a connection and use a bearer filter to limit the used bearer e.g. to WLAN. One use case would be to use Internet destination but allow only WLAN connections. See code example here.
Disallow forced reconnection
Forced reconnection to higher priority connection, e.g., from cellular to WLAN, is a new feature in Symbian^3. From application point of view, a connection with lower priority (usually cellular connection) gets disconnected when a connection with higher priority (usually a known WLAN access point) becomes available. It is up to the application to do a reconnect in such a situation. If such sudden disconnection cannot be tolerated by the application, Extendedconnpref API can be used to disable it for the connection the application is using. See code example here.
Opening a connection to a specific IAP
If an application requests a connection to a specific IAP (i.e. doesn't use destinations), even cellular connection is opened without the access permission dialog regardless whether the end user has allowed automatic connections with that IAP or not. This functionality will remain the same in Symbian^3 with the exception that in a visitor network, the cellular usage confirmation is shown in case the new "Cellular data usage abroad" setting is set to "Always ask". If the setting is "WLAN only", cellular data connection establishment will fail both in home network and in foreign networks. In Symbian^3, if an application requests a connection to a specific IAP using Extendedconnpref API, no other connections are offered to the application but it will get a connection to the requested IAP, regardless of the existence of the user connection.
Opening a connection with a SNAP
Extendedconnpref API can be used to set the purpose of the SNAP (destination). This functionality enables applications to start a connection to e.g. Internet SNAP or intranet SNAP without indexing through all SNAPs to find the ID.
OCC direct impacts on applications
Below is a list of a 3 important recommended changes needed for all current applications using data connectivity. By making these code changes within the application, OCC aims to ensure a consistent and smooth user experience for all data applications.
1. Remove connecting notes indicating connection state
OCC implements discreet pop-ups that tell the status of the connection process. These notes will be rather small and disappear automatically without user interaction. The image below illustrates the soft-note in connecting case. A discreet pop-up will be displayed for a short while, and then it will automatically “minimize” itself into the top-left corner. The pop-up is non-intrusive and does not interfere with user interaction, allowing the user to continue using the application. Tapping the discreet pop-up will take the user to the Connection Manager UI. The pop-up will also be visible on top of full screen applications. Notice that the pop-up is not shown, if there is an active connection which a new connection request will share.
Applications should remove any application specific "Connecting to IAP/SNAP" notes or dialogs. If notes are needed they should be related to the application's own behaviour (i.e. "Connecting to Server"). If they are not removed, the same information will be shown twice to the end-user. Soft-notes from the middleware are therefore designed to provide a consistent user experience for all applications.
In particular cases where the application has a specific and well justified reason for keeping its own notes, connection openings can be done silently by utilising the extended connection preferences in the connection creation phase. See here for a code example on how to open a connection silently without the discreet pop-ups. Silent connections are useful for background type of applications that don't have a UI context.
2. Remove cellular roaming dialogs and settings
OCC incorporates platform wide settings to control the usage of cellular data in visitor and home networks. This setting will override applications' own preferences.
Both "Data use in home netw." and "Data use when roaming" can now be set to: "Automatic", "Always ask" or "WLAN only". When set to "Automatic", no questions will be asked from the user if WLAN is not available and cellular data is used. "Always ask" setting causes a dialog when WLAN is not available so the user needs to manually confirm cellular data usage. "WLAN only" setting will disable cellular data usage. No dialogs are shown in the case when WLAN is not available and the active application will not get network access. The default setting for the home network is "Automatic" and "Always ask" for abroad. The figure below illustrates the "Always ask" dialog for home network.
Selecting "Connect automatically" for home network will change the corresponding system wide setting to "Automatic". Selecting "Connect this time" will allow one time access to the cellular data and system wide settings are not affected.
For visitor network, “Always ask” dialog is slightly different having only “Connect” and “Cancel” buttons. Selecting “Connect” will allow one time access to the cellular data and system wide settings are not affected.
If any current application has its own setting or prompt for allowing/disallowing cellular data usage, it will be in conflict with this platform setting. Therefore OCC requires the removal of application based dialogs and settings code which relate to cellular roaming. If the application code requires the status of the cellular roaming setting, it can be obtained using the Connection Settings API. You can fine a code example here.
3. Remove network access permission queries
The new centralised cellular usage settings provide control over when cellular usage is prompted from the user and when it is not so the actual usage of the cellular network will be controlled only by the platform wide implementation. The default value for the "Data use in home netw." and "Data use when roaming" are “Automatic” and "Always ask", respectively.
If the application carries its own prompt for network access, with OCC, the user will be given 2 dialogs with the same query when the setting is “Always ask”. However, it is the OCC setting which now controls the application behaviour. Therefore, removing network access prompts from the application is required to maintain a smooth user experience. The security framework will however still prompt the user in case the application is lacking required capability to use the network (NetworkServices).
OCC recommended changes to existing applications
All data applications should consider the new services being offered by OCC. The following sections are a set of recommendations which may allow applications requiring data connectivity to take advantage of the new middleware elements.
1. Implement reconnect logic to cope with disconnected situations
It is a very common case that the user moves out of WLAN coverage area and WLAN gets disconnected. OCC will have a new setting that will also cause the existing cellular data connection to be disconnected in the event that a higher priority connection becomes available. If the new WLAN doesn't match the application's preferences, its primary link will not get disconnected. This forced reconnection feature is controlled from the Connectivity Settings. The "Connection to WLAN" setting can be set to either "Known WLANs only" or "Manual". When set to "Known WLANs only", lower priority connection (usually cellular) will be disconnected if the phone enters the coverage area of a higher priority connection (usually a known WLAN access point). The default value for "Connection to WLAN" is "Known WLANs only" which enables forced reconnection feature for applications. Applications that have ALR implemented will also be affected by the "Connection to WLAN" setting, that is, if WLAN becomes available during connection it is not offered to ALR applications if "Connection to WLAN" is set to "Manual".
By enabling the forced reconnection feature, applications and application frameworks can be made to switch to use WLAN and provide an automatic and cost efficient user experience without having any connection switching logic coded into application. The cellular data connection will get disconnected only if the application is using Internet SNAP and the found WLAN is from the Internet SNAP.
Applications must not show an error note on the screen in case the network link is disconnected by the middleware. Symbian applications that use the RConnection API directly can determine the cause of the disconnection from the returned error code value. Runtimes and applications that are not directly exposed to the RConnection error code values, should implement a retry logic that tries to connect to the network after the link has been disconnected. The table below illustrates the RConnection error code values and preferred actions.
| Error Code | Case | Preferred Action |
| KErrDisconnected | Connection lost because used network is not reachable anymore. This can be either due to lost WLAN coverage or automatic WLAN usage feature disconnecting cellular data connection. | Automatic re-connecting encouraged, but number of tries limited. |
| KErrConnectionTerminated | Connection closed manually from Connection Manager, or end key. | Don’t reconnect immediately unless the user does an explicit action that requires a connection. |
| KErrCancel | User cancels connection setup from UI. | Don’t reconnect immediately unless the user does an explicit action that requires a connection. |
| KErrNotFound | Connection request fails, because no suitable access points are available (when SNAP is used). | Don’t reconnect immediately unless the user does an explicit action that requires a connection. |
| KErrPermissionDenied | Connection request fails, because settings prohibit the connection to be opened. | Don’t reconnect immediately unless the user does an explicit action that requires a connection. |
| All other error situations. E.g. bearer specific connection failures, NifMan idle timers (KErrTimeout) | Default handling. | Don’t reconnect immediately unless the user does an explicit action that requires a connection. |
If the application wants to be in control of the roaming decision, it can implement ALR. If the application cannot tolerate disconnection of the network link but doesn't need ALR, it can use Extendedconnpref API during connection creation to disable forced reconnection feature (see code example here. The extended connection preferences don't affect system wide behaviour, only applications’ own connection.
2. Update Connectivity Settings
Different applications have different ways of configuring their connectivity settings. Access Point Engine API and Access Point Settings API have been deprecated already in S60 3.2 but they are still widely used. These APIs don't support the SNAP concept and must not be used anymore. Two new APIs were introduced to replace the old ones: Connection Settings API and Connection Settings UI API. These APIs provide support for both SNAP and IAP configuration and must be used if the application can connect to different destinations. Guide for migrating from Access Point Engine APIs to Connection Settings API can be found from here.
Applications that always connect to Internet can remove their own connectivity settings and open a connection without any preferences. In Symbian^3, the default connection is mapped to Internet destination so the best available connection to Internet is selected automatically. Figures below illustrate the Network Selection dialog launched using Connection Settings UI API (SNAP selection left, IAP selection on the right).
SNAP support provides a way for applications to make use of WLAN when available and cellular data when they are not available. Using Connection Settings API and Connection Settings UI API provide a consistent user experience for applications that need their own connectivity settings. The old Access Point Engine APIs are no longer maintained and will be removed in future Symbian releases.
If the application needs to have its own connectivity settings it must use the Connection Settings UI API for showing the destination selection dialog. In case the application connects always to Internet, it is advised to just open an RConnection without any preferences. This will cause the best available Internet connection to be established. Example code can be found here.
3. Implement support for Application Level Roaming (ALR)
Application Level Roaming brings the control of switching between access methods to the application. The support for ALR has been in S60 platform since release 3.2. ALR provides a way for the application to provide continuous service regardless of changing network conditions. Switching dynamically to a WLAN network also reduces the cost of connection. Application Level Roaming is an extension to RConnection API.
If your application fulfills the three criteria listed below, your application will benefit from ALR:
- Your application can work over multiple accesses (WLAN and GPRS)
- Your application requires lengthy connections to the network
- Your application cannot tolerate forced reconnection implying a sudden loss of network access and then reconnecting again.
Code example how to implement ALR can be found here.
Comments
Contents |
Mod said…
Richardc said…
yes. this has been highlighted and will soon form part of this guide.
--Richardc 15:10, 3 February 2010 (UTC)
Kujawk said…
Will the automatic switch from cellular to WLAN disconnect the cellular connection while it's actively being used or will it wait until the connection is idle?
--Kujawk 21:43, 18 February 2010 (UTC)
Jleppila said…
Yes, OCC will force applications to reconnect to more preferred bearer by disconnecting the sockets and RConnection handle. Applications that need persistent connections and more control, can implement ALR and use ALR APIs to control the switch so that it happens only after the connection is idle.
--Jleppila 17:02, 1 March 2010 (UTC)
Kujawk said…
What is the difference between the new forced reconnect feature and its user setting "Switch to WLAN" and ALR? Can somebody provide specific examples where they differ?
--Kujawk 18:32, 17 March 2010 (UTC)
Torantan said…
Are you asking what is the difference between forced reconnection feature and ALR? If yes, the answer is that in ALR, application decides whether its connection is switched over to another bearer whereas in forced reconnection, OCC does that decision on behalf of the application. Let me know if this didn't answer your question.
--Torantan 15:06, 21 March 2010 (UTC)
Kujawk said…
After rereading the page above, I think I see the difference. With ALR, if the middleware finds a better (higher priority) IAP it calls PreferredCarrierAvailable() at which point you have a choice to either migrate to or ignore the new IAP. Whether or not ALR is implemented depends on who wrote the application. I understand that, since not all applications support ALR, you want to make this behavior application independent and you are doing this by having the middleware forcefully disconnect a connection with KErrDisconnected when a WLAN comes into play. This leads to an additional question. How does an application block its connection from being forcefully disconnected by the middleware?
--Kujawk 15:04, 23 March 2010 (UTC)
Torantan said…
Application can disable forced reconnection using TExtendedConnPref::SetForcedRoaming( EFalse ). Full code example is here: http://developer.symbian.org/wiki/index.php/IP_connection_management_code_examples#Opening_a_connection_and_disabling_forced_reconnection
SetForcedRoaming( EFalse ) disables all forceful disconnections for that specific connection. There is no possibility to block one forceful disconnection and allow another one later on for the same connection.
--Torantan 08:27, 22 April 2010 (BST)
Rwnilsen3 said…
The guide says "Symbian applications that use the RConnection API directly can determine the cause of the disconnection from the returned error code value."
How can I tell when a connection that I have created using Start() has gone down?
And if I have used Start() to open an RConnection to a destination, how can I tell which IAP I have been connected to?
--Rwnilsen3 04:14, 18 May 2010 (BST)
Torantan said…
You can detect connection down by monitoring progress notifications. You'll get an idea how it works from http://developer.symbian.org/main/documentation/reference/s3/pdk/guid-6013a680-57f9-415b-8851-c4fa63356636/guid-3d0ac087-79ee-467f-b6ed-d71eafa40d9c.html. This monitors different states in connection creation. You need to do it for connection down event. You can get the IAP you are connected to with: TUint32 iap( 0 ); connection.GetIntSetting( _L("IAP\\Id"), iap );
--Torantan 16:42, 26 May 2010 (BST)
Sign in to comment…
is it possible to add sample code to use all of the described features?
--Mod 14:52, 28 January 2010 (UTC)