The Network API

The Network API is implemented in the net.rim.device.api.io.transport and net.rim.device.api.io.transport.options packages. Most of the functionality is provided by the ConnectionFactory and TransportInfo classes. A ConnectionFactory object returns a ConnectionDescriptor object that contains a Connection object and information about the transport over which the connection was opened.

Choosing network transports using the Network API

In the Network API, the TransportInfo class provides information about the network transports that are available on a BlackBerry® device. You can retrieve a list of transports that currently have coverage, or use the API to determine whether a particular transport is available and has coverage.

If you don't provide an ordered list of preferred transports when you open a connection, the Network API chooses a transport for you. However, you should prioritize the transports that your application uses based on the type of user that your application targets. The API steps through an array of transport types that you set by using ConnectionFactory.setPreferredTransportTypes().

After you list your preferred transports, you should set options for any transports that require specific options. For example, the WAP 1.0 and 1.1 transports require information about an APN, and the gateway authentication, and so on. For more information, see "Network transport options".

You should also create a CoverageStatusListener object (in the net.rim.device.api.io.transport package), and register it using TransportInfo.addListener(). The device notifies your application about changes in coverage status so that your application can respond appropriately.

Back To Top

Opening a network connection using the Network API

After you decide which network transports to use, you can open a connection and use it to send and receive data. The ConnectionFactory object is responsible for opening connections. In addition to your preferred transports, you can use the ConnectionFactory to configure connection options such as:
  • Maximum number of connection attempts.
  • Maximum time to spend making connection attempts.
  • Delay between connection attempts.
  • Whether or not encryption is required between the connection end points.

When you are ready to open a connection, you should invoke one of the ConnectionFactory.getConnection() methods. Be sure that you call getConnection() on a thread that is separate from the main event thread. For more information about creating a thread, see the Thread class in the API reference for the BlackBerry® Java® SDK.

When you open a connection successfully, the ConnectionFactory returns a ConnectionDescriptor object. The ConnectionDescriptor contains a Connection object, and information about the transport that was used to open the connection.

For more information, see Open a network connection using the Network API and Send and receive data using a network connection.

Back To Top

Open a network connection using the Network API

CAUTION:
The ConnectionFactory.getConnection() method blocks thread execution. You should create a separate thread to call getConnection().
  1. Import the required classes and interfaces.
    import net.rim.device.api.io.transport.*;
    import net.rim.device.api.io.transport.options.*;
    import net.rim.device.api.io.transport.TransportInfo;
    import net.rim.device.api.ui.UiApplication;
  2. Create an ordered list of preferred transports.
    int[] intTransports =
    { TransportInfo.TRANSPORT_TCP_WIFI,
      TransportInfo.TRANSPORT_WAP2,
      TransportInfo.TRANSPORT_TCP_CELLULAR
    }
  3. Configure the options for the TCP Cellular transport, if applicable.
    TcpCellularOptions tcpOptions = new TcpCellularOptions();
    if(!TcpCellularOptions.isDefaultAPNSet())
    {
        tcpOptions.setApn("My APN");
        tcpOptions.setTunnelAuthUsername("user");
        tcpOptions.setTunnelAuthPassword("password");
    }
  4. Create a ConnectionFactory object.
    ConnectionFactory factory = new ConnectionFactory();
  5. Set any other ConnectionFactory options that are applicable to your application. In this case, TCP Cellular is one of the preferred transports, so set the TCP Cellular transport options.
    factory.setTransportTypeOptions(TransportInfo.TRANSPORT_TCP_CELLULAR, tcpOptions);
    factory.setAttemptsLimit(5);
  6. Create a thread to retrieve the connection. If the connection was successful, then ConnectionFactory returns a ConnectionDescriptor object that you can use. In this step, pass the ConnectionDescriptor object to another method (displayContent()) that is responsible for displaying the content.
    Thread t = new Thread(new Runnable()
    {
        public void run()
        {
            ConnectionDescriptor cd = _factory.getConnection
                                           ("http://www.blackberry.com");
            if(cd != null) 
            {
                Connection c = cd.getConnection();
                displayContent(c);
            }
         }
    
    });
    t.start();
    
  7. Implement displayContent(). In this case, push a screen that uses a Connection parameter to retrieve and display the content, after the connection retrieval thread completes.
    private void displayContent(final Connection conn) 
    {
        UiApplication.getUiApplication().invokeLater(new Runnable()
        {
            public void run() {
                UiApplication.getUiApplication().pushScreen(new HTTPOutputScreen(conn));
            }
        });
    }
After you finish: For more information about using a connection and implementing the HTTPOutputScreen class, see "Send and receive data using a network connection".

For a complete code sample, see "Code sample: Retrieving a web page using the Network API".

Back To Top

Was this information helpful? Send us your comments.