Generic Connection Framework

If you develop applications for BlackBerry® device users who are running BlackBerry® Device Software 4.7 or earlier, you need to use the GCF to open a network connection. However, any code that you write that uses the GCF also runs on later versions of BlackBerry® Device Software. The GCF is implemented in the javax.microedition.io.Connector class. You can call Connector.open() to create any type of supported connection. The open() method accepts a connection string that specifies the type of connection to make, the end point, and optional configuration details for the connection.

The connection string that is used by the GCF comprises three parts:

<scheme> : <hierarchical location information> ; <additional information>

The <scheme> indicates the protocol to use to establish the connection. The <hierarchical location information> describes the end point for the connection. Finally, the <additional information> controls the transport that is used, and provides authentication details for a proxy server if they are required. For more information about transport options, see "Network transport options".

For example, in the following code sample, the connection string specifies the HTTP protocol and uses a host name to indicate the connection end point. The interface=wifi parameter is included to specify that the Wi-Fi® radio should be used to establish the connection.

HTTPConnection c = (HTTPConnection)Connector.open("http://example.com;interface=wifi");

Open a network connection using the GCF

The following task shows you how to open an HTTP connection using the BlackBerry® Mobile Data System transport. You can use a similar process to open a connection using other protocols and transports.
CAUTION:
The Connector.open() method is not thread-safe. Ensure that you invoke open() on a thread that is separate from the main event thread.
Before you begin: Make sure that the transport that you want to use is available and has coverage.
  1. Import the required classes and interfaces.
    import net.rim.device.api.ui.UiApplication;
    import java.io.IOException;
    import javax.microedition.io.*;
  2. Create a new thread to open the connection.
    Thread t = new Thread(new Runnable()
    {
        public void run()
        {
  3. Create a local variable for your Connection object.
            Connection conn = null;
  4. Invoke open(). Specify the connection string.
            try
            {
                conn = Connector.open("http://www.blackberry.com;deviceside=false");
            } catch (IOException e)
            {
                // Process your error condition
            }
  5. If the connection attempt was successful, open() returns a Connection object that you can use. Pass the connection object to another method (displayContent()) that is responsible for displaying the content.
            if (conn != null)
            {
                displayContent(conn);
            }
        }
    });
  6. Start your thread.
    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 GCF".

Back To Top

Was this information helpful? Send us your comments.