Purpose

Video Connection Utility is a library for managing network connections within the same scope for different SW components.

Video Connection Utility is a DLL that an SW component links and uses within its own process scope. However, the utility handles connections as a one: inside the Video Connection Utility scope. Different processes use Video Connection Utility individually, but they all use conceptually the same connection Access Point at the same device.

This scope is handled by Video Connection Utility in a way where every instance of Video Connection Utility communicates between each other by using Publish and Subscribe keys based on the roles (master or client) which each instance gets.

Constraints

This API is valid for all platforms running on the Symbian^ 1 and S60 5.1 or later.

Classification and release information

This API is a Domain API and was first published in S60 release 5.1.

Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

API description

This API is meant to be used by the clients that operate in the different process scope but use conceptually the same Internet connection so that from the user point of view there is only one connection and one connection creation procedure visible to the user. This is handled in a way where every instantiated Video Connection Utility communicates via Publish and Subscribe keys based on the role the instance gets when it starts up a connection. There are two different roles, master and slave.

The first process instance requiring a connection is considered as a "master". The master receives all events from the network, handles the integrity of the Publish and Subscribe key values and guides slaves to handle connection related operations. These are:

  • Roaming and IAP changes from the roaming.

  • Information about lost connection.

  • Information about possible IAP list changes.

The master is also responsible for always creating connection by using a predefined network destination and if there is no predefined destination, showing the connection selection dialog to the user. Video Connection Utility reads network destination from Central Repository. If the Central Repository key does not exist, the default destination is used. The Central Repository key is written by the Video Center settings engine.

The slave is responsible for opening and maintaining connection for its client. The slave is also responsible for requesting permission for roaming from its clients, and if roaming occurs, responsible for re-initiating its connections if IAP changes. Slave is also responsible to notify its client about lost connection. If the master disconnects its connection, the first free slave becomes master and takes the master's responsibilities.

Use cases

Main use cases are:

  • Connection Creation: Client gets the IAP identification number from the utility.

  • Disconnecting: Client disconnects or de-allocates the utility.

  • Response Application Level Roaming (ALR): Client receives events about IAP changes either from ALR or from other exceptional situations.

API class structure

The Video Connection Utility API is a used via the CVcxConnectionutility class, which is a singleton in the process's scope. In case the client is interested in events about roaming or other IAP related events, it needs to implement the MConnUtilEngineObserver interface.


Related APIs
  • CVcxConnectionutility

Using the Video Connection Utility API

The export library for Video Connection Utility is vcxconnectionutility.lib, which the application needs to link in order to use the API.

The application instantiates Video Connection Utility by calling the interface's InstanceL() method.

#include <vcxconnectionutility.h>

...

CVcxConnectionUtility* iConnUtil;

...

iConnUtil = CVcxConnectionUtility::InstanceL();

InstanceL() returns a pointer to Video Connection Utility and increases the reference count of the number of clients for that particular thread's scope. Whenever InstanceL() is called a thread's local reference count is increased by one. The client cannot deallocate the utility or close the connection before the local reference count is one or zero.

In case the client is interested in events about roaming or other IAP related events, it needs to implement the MConnUtilEngineObserver interface and register to be an observer of Video Connection Utility. If the client does not implement the observer, Video Connection Utility expects it to allow roaming. Observer interface declaration is in the vcxconnutilengineobserver.h header file.

iConnUtil->RegisterObserverL( this );

When Video Connection Utility is no longer needed, the client must call DecreaseReferenceCount. If there are no more references left, the memory allocated for the library is de-allocated and the possible active connection is closed. If the client has registered as an observer, it must deregister first.

iConnUtil->RemoveObserver();

// decrease local reference count by one. 
// if count reaches zero, utility will be deallocated and
// possible active connection will be disconnected
iConnUtil->DecreaseReferenceCount();  
iConnUtil = NULL;

Connection creation

A client can call the GetIap method to fetch an active connection's IAP ID. If there is not an active connection yet, the connection is created. The GetIap call blocks the client as long as the IAP ID is returned or error occurs.

If there are multiple active objects within the same client thread trying to connect, they are put to wait until the connection is established. If multiple threads are trying to create the connection at the same time, a semaphore is used to protect connection creation to make sure only one thread can establish a connection at the time.

First thread creating connection (there is no active connection yet) creates a connection and becomes the master. This happens because only one thread can be the master and receive events from the network.

TInt err( KErrNone );
TUint32 iapId( 0 );

// in case client do not want for "connecting" -dialog 
// shown, aSilent parameter should be ETrue
err = iConnUtil->GetIap( iapId, EFalse );

Related APIs
  • GetIap

Disconnecting

A client can call DisconnectL when it no longer needs a connection. If the thread's local reference count is more than one, Video Connection Utility assumes there are other local clients using connection and the connection is not closed.

The closing of the current thread's connection also occurs when Video Connection Utility is being de-allocated. This occurs when enough local clients have been called DecreaseReferenceCount, and the reference count reaches zero.

If the current thread is the master, the slaves notify this and the first slave reaching the event about change, becomes the master.

 // client can try to explicitly disconnect connection, but if other references 
 // using connection exist, the connection is not closed.
 iConnUtil->DisconnectL();

Related APIs
  • DecreaseReferenceCount
  • DisconnectL

Response to application level roaming

Video Connection Utility is notified when networking components think that there is a better IAP available. This results are the following:

  • The master sets its internal state to the Roaming state and queries all its observers by calling RequestIsRoamingAllowedL for all its observers. If there are no observers or all observers accept roaming, roaming is allowed from the master. If some observer does not accept roaming or some observer leaves from RequestIsRoamingAllowedL, the roaming is ignored.

  • When roaming is allowed from the master, it notifies all slaves about roaming via the Publish and Subscribe keys. Slaves notify this and call RequestIsRoamingAllowedL for their clients.

  • If the slave has no observers or all observers return ETrue, the slave increases the roaming response and acceptance counters by one. If some of the slaves' observers do not accept roaming, only the roaming response counter is increased. If a slave accepts roaming, it sets its internal connection status to roaming accepted. If not, it sets its internal connection status to roaming state.

  • Master receives notification about roaming response counter change. It then checks if all connected clients are responded and checks whether all have accepted the request.

  • If everyone has accepted roaming, this status is returned to the networking and the master's state is put to the Roaming accepted state. The master waits for networking to confirm the IAP change. If a new roaming request comes from the network at this stage, it is being accepted right away.

    If someone does not allow roaming, networking is also informed about this. No IAP change occurs, unless old IAP is lost, for example, due to a lost WLAN carrier.

  • When the networking has changed the IAP and the master is notified about it. Master handles this by first requesting information about the new connection, saving the information into Publish and Subscribe and then notifies its observers about this by calling its observers' IapChangedL. The client should then ask for the new IAP identification number by calling GetIap.

  • When the master has changed the connection information to the Publish and Subscribe, the slaves receive this information. The slaves then first disconnect the current connection and start up a new connection right away.

The following sequence diagram describes this from the client point of view:


In addition to normal roaming, there are some exceptional cases that fall into roaming and that client must take into account. They are listed below:

WLAN carrier lost after not accepted roaming

If some observer does not accept roaming from WLAN to some other carrier and the WLAN connection is lost, connection is eventually disconnected for all. All observers are notified of this by a IapChangedL() call.

Related APIs
  • IapChangedL()

Disconnecting during roaming

If the master is requested to disconnect during roaming, the disconnecting procedure blocks until roaming finishes. After that the normal disconnection routine proceeds.

User manually modifies destination IAPs' priorities

If the user changes the priorities of the current destination in use, a roaming request eventually arrives to Video Connection Utility and a normal roaming procedure follows.

Connection lost from the networking

If networking notifies about a Lost link layer or connection deletion (by some external application), the connection is disconnected. All observers are notified of this by the IapChangedL() call.

Related APIs
  • IapChangedL()
Related APIs
  • ETrue
  • GetIap
  • IapChangedL
  • RequestIsRoamingAllowedL

Error handling

GetIap returns KErrCancel, if the user explicitly cancels connection creation, for example, by pressing the Cancel button from the Connecting dialog.

In other error cases during connection creation, a system wide error is passed to the client. The IAP identification number is 0 and no connection is created.

Related APIs
  • GetIap
  • KErrCancel
Related APIs
  • DecreaseReferenceCount
  • InstanceL()

Glossary

Abbreviations

ALR Application Level roaming (see Definitions)

IAP

Internet Access Point

Definitions

Application Level Roaming Application level roaming (ALR) means switching an active data connection from one IAP to another so that the application has control whether or not to roam and on the timing of when the roaming happens.

Destination

A group of network/Internet Access Points used in connection creation.