Creation of CR initiates the process during which attempts at connecting, or satisfying, that CR will be made, and may result in eventual success or failure in establishing the required connection(s) leading to the requested meta-network. During the connection process, the CR owner will be notified of, potentially, many state transitions, each of which needs to be properly handled by the application.
In particular, a CR can be in two states,
i) Transient state – Being in this state, the status of the CR will change at some point to another status, ex. the connected state having status CONNMGR_STATUS_CONNECTED is transient.
ii) Non-transient state – When a CR is in this state, its status will never change. For example, a disconnected CR in non-transient state will continue to be disconnected (and have the same status) forever. If an application finds its CR in this state, and a connection to desired meta-network is still required, the application needs to release and recreate the CR.
The figure attached to this blog entry maps out possible status transitions, clearly defines the transient and non-transient states and is meant to be used as a guide in implementations handling status updates. The meaning of each of the statuses is summarized in the table below.
Note that the CONNMGR_STATUS_ status prefix has been omitted in status names to aid in readability. Also note that since the status of CR can always change to CONNECTIONCANCELED, all states are in fact transient (of course, except for the state having the canceled status). However, the canceled state is a special case, and can be handled as such.
Figure: Client status transitions.
The connection path leading to the requested network is now fully connected. After receiving this status notification, all sockets opened by the process-owner of this CR will use the selected connection path for sending data.
One of the connections used by this CR* is suspended as a result of an incoming or outgoing voice call. In this state, all active sockets of the process-owner of the CR will not be able to send or receive data until the connection is resumed (is CONNECTED). Note that if CR persists in this state for long enough, data sessions may timeout and they may need to be restarted.
This is the initial client status of all CRs. This status indicates that CR has not been evaluated.
This status will also be signaled if CR is not S/R-aware (didn’t have CONNMGR_FLAG_SUSPEND_AWARE set), but one of the connections used by this CR* is suspended as a result of an incoming or outgoing voice call. See SUSPENDED status for more information.
One of the connections used by this CR* failed to be connected or was prematurely terminated as a result of resource conflict with the same or higher priority CR, system entering secure mode, or some other error.
The CR was cancelled.
This CR is disabled and will not be connected. The CR is disabled if the bDisabled member of the CONNMGR_CONNECTIONINFO structure initially passed in call to ConnMgrEstablishConnection() is TRUE.
Connection planner could not find a suitable connection path that can satisfy the requirements of the CR including the specified cost, bandwidth, latency and the requested destination network.
VPN is connected, but the selected path to the requested destination network does not use the VPN connection.
Resources required by the selected path to the requested destination network cannot be reserved because the phone is in use.
The selected path to the requested destination network requires one of radio connections, but the radio is off (i.e. in flight-mode).
The system is in secure mode, that is, a secure connection, such as DTPT is connected. The selected path to the requested destination network cannot be connected because it doesn’t use the connected secure connection (or a more secure connection).
Reserved for internal use.
One of the connections used by this CR* failed to be connected or was prematurely terminated, typically by a remote disconnection, ex. PPP server terminated connection with client.
One of the connections used by this CR* and requiring credentials failed to be connected because of authentication failure.
CR asked for Wake-On-Incoming support (set CONNMGR_FLAG_WAKE_ON_INCOMING), but such path to requested destination network doesn’t exist.
A connection path for this CR was selected, required resources were successfully allocated, and now connections on the path are being connected. Indication with CONNECTED or disconnected (failed) status should follow.
A connection path for this CR was selected, but not all of the required resources could be reserved. This typically means that the resources are occupied by same or higher priority CR. If former, then the CR is now being disconnected, and this CR should transition to WAITINGCONNECTION within short amount of time; if latter, then this CR may remain in this state until the higher priority CR is disconnected or a new path becomes available.
This status indicates one of two things, (i) if the priority of this CR has LOWBKGND priority, then the CR cannot be connected because the path selected is not already connected by another higher priority CR, or (ii) if the priority of this CR is not LOWBKGND, but the CR has flag CONNMGR_FLAG_REGISTERED_HOME is set, then the connection path used by the CR contains a radio connection, and radio is not registered home, i.e. it is roaming.
This CR is being disconnected because, (i) the CR was canceled, or (ii) the CR has LOWBKGND priority, but the connection path used by this CR is not used by another higher priority CR, or (iii) this CR lost resources required to maintain its CONNECTED status to another same or higher priority CR.
This CR was in the process of being connected, but is now aborted for one of the reasons listed in WAITINGDISCONNECTION, above.
*) A connection that is used by a CR is one that appears on the connection path used by the CR.
Table: Meanings of client statues.