<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-1D96687F-C81B-56FC-84A6-2C87216BF1F9" xml:lang="en"><title>Mobile

Network Tutorial</title><shortdesc>This tutorial describes how to get the current and home network

information using the <codeph>RMobilePhone</codeph> functions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<context id="GUID-E9BF1862-79FE-4212-AA18-ED59F5D542A8"><p>Use the <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone</apiname></xref> functions

to get information about the current, home, and detected networks. </p> <p>To

query what network information is available, use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::GetNetworkCaps()</apiname></xref>.

The <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone</apiname></xref> functions are used

to get the network information. </p> <p> <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>CRetrieveMobilePhoneDetectedNetworks</apiname></xref> is

provided to get a list of all the detected networks. </p> </context>

<steps id="GUID-F2274847-45EC-5EB3-8DC2-81B23D29A8BB">

<step id="GUID-FB4014AF-D48C-50EB-83A4-8A9477590453"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::GetCurrentMode()</apiname></xref> to

get information about the current network mode, for example, GSM or CDMA.

Modes are described by <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::TMobilePhoneNetworkMode</apiname></xref>. </cmd>

</step>

<step id="GUID-0DB34ABC-AC93-5315-AE52-5E52DF79CFD9"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::NotifyModeChange()</apiname></xref> to

get the notification of any changes to the mode. </cmd>

</step>

<step id="GUID-3F7B42A9-5A04-5B8E-AF43-861DCCE3B2F3"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::GetCurrentNetwork()</apiname></xref> to

get details, such as the network mode, status, and identity or name as appropriate

to the mode, of the current network. </cmd>

<info>The information is returned in a <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::TMobilePhoneNetworkInfoV2</apiname></xref> object

(<xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::TMobilePhoneNetworkInfoV1</apiname></xref> in

the v1 API). In GSM mode, it may also be possible to return information on

the current location of the phone, in an <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::TMobilePhoneLocationAreaV1</apiname></xref> object. </info>

</step>

<step id="GUID-051DF5D8-A5F7-5FD6-A459-CEBFB53FACAE"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::NotifyCurrentNetworkChange()</apiname></xref> to

get the notification of changes to the current network. </cmd>

</step>

<step id="GUID-3058F27E-7945-5092-AC3E-F6F763861EF8"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::GetHomeNetwork()</apiname></xref> to

get details about the home network. </cmd>

<info>This will be the same as the current network, unless the phone is roaming

as a guest on in another network. </info>

</step>

<step id="GUID-41B6818E-AAFF-5FCC-A5B0-88A4F19EB1BE"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::GetNetworkRegistrationStatus()</apiname></xref> to get information about the current network registration status. </cmd>

</step>

<step id="GUID-5C81C480-1AC6-559F-B156-64D26A347213"><cmd>Use <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone::NotifyNetworkRegistrationStatusChange()</apiname></xref> to get notification of any changes to the network registration status. </cmd>

</step>

</steps>

<example><title>Network information example</title> <p>The following code

checks if the information about the current network can be obtained, and if

so, gets that information, and reads from it the full network name. </p> <p>The

code assumes <codeph>iMobilePhone</codeph> is an <xref href="GUID-AA81AFA4-6FAC-3B0D-A082-BE0AEC58CCA8.dita"><apiname>RMobilePhone</apiname></xref> object. </p> <codeblock id="GUID-EE4F83AB-AD2A-53AC-B092-E7BDAAD913AC" xml:space="preserve">TUint32 networkCaps;

User::LeaveIfError(iMobilePhone.GetNetworkCaps(networkCaps));

RMobilePhone::TMobilePhoneNetworkLongName networkName;

if (networkCaps & RMobilePhone::KCapsGetCurrentNetwork)

    {

    RMobilePhone::TMobilePhoneNetworkInfoV1 mobilePhoneNetworkInfo;

    RMobilePhone::TMobilePhoneNetworkInfoV1Pckg mobilePhoneNetworkInfoPckg(mobilePhoneNetworkInfo);

    RMobilePhone::TMobilePhoneLocationAreaV1 mobilePhoneLocationArea;

    TRequestStatus status;

    iMobilePhone.GetCurrentNetwork(status, mobilePhoneNetworkInfoPckg, mobilePhoneLocationArea);

    User::WaitForRequest(status);

    User::LeaveIfError(status.Int());

    networkName = mobilePhoneNetworkInfo.iLongName;

    }</codeblock> </example>

<postreq id="GUID-CC5A9255-38BD-4DDA-8B83-F20FFBCCAAAB"><p>After retrieving the network information, the device has to selects

a network to use. See <xref href="GUID-89D0839A-942B-58FF-A0E6-A0FDBFC92236.dita">Mobile

Network Selection Tutorial</xref> for more information on how to get and set

the parameters to select a network. </p> <p>Once a network is selected the

user decides to automatically update the date and time from the network. See <xref href="GUID-CC05C1AA-02B0-5E94-9522-44BCF44CBA48.dita">Network Date and Time Tutorial</xref> for

more information on how to receive date and time from the network. </p> </postreq>

</taskbody></task>