Video Connection Utility APIChanges in Video Connection Utility API documentation
PurposeVideo 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. API descriptionThis 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:
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 casesMain use cases are:
API class structureThe Video Connection Utility API is a used via the
Related APIs
Using the Video Connection Utility APIThe 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
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.
When Video Connection Utility is no longer needed, the client must call
Connection creationA client can call the
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.
Related APIs
DisconnectingA client can call
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
If the current thread is the master, the slaves notify this and the first slave reaching the event about change, becomes the master.
Related APIs
Response to application level roamingVideo Connection Utility is notified when networking components think that there is a better IAP available. This results are the following:
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 roamingIf 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
Related APIs
Disconnecting during roamingIf 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' prioritiesIf 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 networkingIf 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
Related APIs
Related APIs
Error handling
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
Related APIs
GlossaryDefinitions
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|

