Developers

Local Navigation

Home > Developers > Developers Knowledge Base

Back

What Is - Network Diagnostic Tool

Last Updated: 19 March 2009
Article Number: DB-00684

Summary

This article applies to the following:

  • BlackBerry® smartphones based on Java® technology
  • BlackBerry® Device Software 4.5 and later

Details

BlackBerry smartphones support many different transports that facilitate reliable data communication between third-party applications and the Internet. The transports available are direct Transmission Control Protocol (TCP), BlackBerry® Mobile Data System (BlackBerry MDS), BlackBerry® Internet Service Browsing (BIS-B), BlackBerry® Unite!™ software, Wireless Access Protocol (WAP)1.0, WAP2.0 and Wi-Fi® technology. It is important to understand the differences between these transports and how and when to leverage each transport. It is also crucial to determine if a transport is available for use before trying to use it. The Network Diagnostic Tool is essentially a role model that answers all these questions and is a functional diagnostic tool for testing a URL over various transports supported by the BlackBerry solutions, as well as for displaying the values of many network attributes during the test period.

This article refers to the source code of the Network Diagnostic Tool, which can be downloaded here.

To better understand how each transport works, see the video Network Transports found on blackberrydeveloper.com.

Determining transport availability

The first step to determining the availability of a transport is to check if the ServiceRecord for that transport is available. This can be done programmatically as follows:

  1. Get the ServiceBook instance by calling the static method ServiceBook.getSB().
  2. Get the ServiceRecords from the ServiceBook by calling the instance method ServiceBook.getRecords().
  3. Iterate through each ServiceRecord and determine if it is for the transport you are looking for.

This is demonstrated in the Network Diagnostic Tool's IOThread.initializeTransportAvailability().

The next step is to determine if the BlackBerry smartphone has network coverage to communicate through the transport. This can be accomplished by calling the application programming interface (API) CoverageInfo.isCoverageSufficient(int coverageType).

Refer to the method IOThread.initializeTransportAvailability()for a sample implementation of this.

Creating connections

Developer knowledge base article DB-00396 illustrates how to create an Hypertext Transfer Protocol (HTTP) or socket connection.

The IOThread.get*URL() methods in the source code shows how to construct URLs for each transport.

Once you have the URL you need, you can create an HTTPConnection instance using the Connector.open(String url) static method and start communicating with that URL. See the IOThread.do*() methods in the Network Diagnostic Tool source code to see a detailed implementation of this.

Note: The BIS-B transport is available only to partners of the BlackBerry Alliance Program, and therefore is not implemented in the attached source code of the Network Diagnostic Tool. For more information on the BlackBerry Alliance Program, visit http://na.blackberry.com/eng/partners/why_join.jsp.

Displaying network and radio information

Besides testing the different transports for a given URL, the Network Diagnostic Tool also displays network and radio information such as signal level, network name and type, and available network services. Refer to the method ReportScreen.displayNetworkInfo() in the Network Diagnostic Tool source code for more information on how to display this information.

RadioStatusListener

It is also possible for an application to listen for changes in the radio such as signal level and available network services. To accomplish this, you must implement the interface RadioStatusListener. The Network Diagnostic Tool implements this interface in the class named IOThread.

Automatically detecting wireless service providers

It is very useful to be able to detect wireless service providers, especially for applications using the Direct TCP transport for BlackBerry smartphones that operate using Global System for Mobile communications® (GSM®). For these BlackBerry smartphones, correct access point name (APN) information must be specified by the BlackBerry smartphone user before any application can leverage the Direct TCP transport.

APN information can also be set programmatically, which is demonstrated in the referenced Network Diagnostic Tool source code. The details are also explained in DB-00532. If the current wireless service provider for the BlackBerry smartphone can be determined, then the APN information can be set up programmatically from the application. This improves the BlackBerry smartphone user's experience because the APN does not need to be specified manually. To detect the wireless service provider, use a table that contains the name, mobile country code (MCC), mobile network code (MNC) and the APN details of each wireless service provider. Compare the MCC and MNC values returned by the BlackBerry smartphone against the values in the table. Once a match is found, set the corresponding APN information programmatically. For more information on how to read the MCC and MNC values from the BlackBerry smartphone, see DB-00688.

The complete process to automatically detect wireless service providers is also demonstrated by the Network Diagnostic Tool. The Network Diagnostic Tool stores the wireless service provider table in an Extensible Markup Language (XML) file that can be downloaded from here. This file must be stored on the BlackBerry smartphone in the following location: file:///store/netdiag/carrier_info.xml unless this path is changed in the source code. You can add details for as many wireless service providers as you want to the XML file.

Changes required for earlier versions of the BlackBerry Java Development Environment

Although this article is targeted for BlackBerry® Java® Development Environment (BlackBerry JDE) 4.5 or later, the source code of the Network Diagnostic Tool can be easily modified and compiled using earlier versions of the BlackBerry JDE. Consider the following changes:

  1. Before BlackBerry JDE 4.3, RadioStatusListener had an additional method named mobilityManagementEvent(int eventCode, int cause). This method must be implemented if you are using BlackBerry JDE 4.2 or earlier.
  2. CoverageInfo.COVERAGE_DIRECT is not supported until BlackBerry JDE 4.5. For BlackBerry JDE 4.3 or earlier, use CoverageInfo.COVERAGE_CARRIER.
  3. WLANInfo class is not available until BlackBerry JDE 4.5. For BlackBerry JDE 4.3 or earlier, use the following logic:

    4. if(CoverageInfo.isCoverageSufficient(CoverageInfo.COVERAGE_CARRIER,RadioInfo.WAF_WLAN, false)){
        coverageWiFi = true;
        wifiLog.addlog("Coverage Status: Online");
    }

  4. RadioInfo.NETWORK_SERVICE_GAN is not supported in BlackBerry JDE 4.2.1 or earlier. Remove any references to this constant for those versions of the BlackBerry JDE.
  5. RadioInfo.NETWORK_SERVICE_EVDO_ONLY and RadioInfo.NETWORK_SERVICE_UMTS are not supported in BlackBerry JDE 4.2.1 or earlier. Remove any references to these constants for those versions of the BlackBerry JDE.
  6. The CoverageInfo class is introduced in BlackBerry JDE 4.2.0. Remove any references to this class if you are using an earlier version of the BlackBerry JDE to compile this application. However, it is possible to do the following in versions of the BlackBerry JDE earlier than 4.2.0:
    1. if(RadioInfo.getSignalLevel() != RadioInfo.LEVEL_NO_COVERAGE) the BlackBerry smartphone has radio signal.
    2. if(RadioInfo.getNetworkService() & RadioInfo.NETWORK_SERVICE_DATA)>0 the BlackBerry smartphone has data connectivity.

Keywords

network diagnostic tool, http, connection, transport, direct tcp, mds, bis, unite, wap, wap2, wap2.0, radiostatuslistener

By downloading, accessing or otherwise using the Knowledge Base documents you agree: (a) that the terms of use for the documents found at http://www.blackberry.com/support/knowledgebase/disclaimer.shtml apply to your use or reference to these documents; and (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.