Overview documentation: Psion Cabster Overview 1.0.0.pdf

Download Psion Cabster: Psion Cabster 2012-05-12.zip

Once downloaded the application needs to be registered. After executing Cabster for the first time it will register itself on Psion’s server, after which the license will need to be approved. Once approved the application will no longer need an internet connection. For license approval please contact me at: paul.kolozsvari@psion.com or paulkolo@gmail.com.

Psion Cabster

After some troubleshooting we discovered the issue to be Windows related. Microsoft Windows has what they call a desktop memory heap that manages objects (windows, menus etc.). According to Microsoft it sometimes happens that a process is not allocated enough memory in which case the process has insufficient memory to start up. There are three different types of desktop heaps which include the heaps for interactive (desktop applications) and non-interactive (windows services) heaps. The size of the heaps can be configured in the registry as described in this Microsoft article: http://blogs.msdn.com/b/ntdebugging/archive/2007/01/04/desktop-heap-overview.aspx

There’s a total accumulated number of bytes for all the desktop heaps running per user session. This total memory address is called the “Session View Space” and you can actually set this value in the registry too. On my machine it’s set to 30MB. So if a large number of processes get spawned each gets allocated a desktop heap, with a specific size. For example it could be 1024KB for each terminal that connects. So if the number of heap sizes exceeds the Session View Space (in my case 30MB) than any other new processes will fail to start, which is the problem we were facing. That is why in our case decreasing the size of desktop heaps fixed the issue. So chances are that if were to and  try connect even more terminals in the future we might face the same problem again. To fix that the size of the Session View Space can be increased as described in the above article. According to Microsoft:

“Where things go wrong

Normally this “just works”, and neither the user nor the application developer need to worry about desktop heap usage.  However, there are two primary scenarios in which failures related to desktop heap can occur:

1. Session view space for a given session can become fully utilized, so it is impossible for a new desktop heap to be created.
2. An existing desktop heap allocation can become fully utilized, so it is impossible for threads that use that desktop to use more desktop heap.”

• Download and install the Windows Mobile Developer Power Toys
• On your PC navigate to C:\Program Files\Windows Mobile Developer Power Toys\PPC_Command_Shell\arm
• Copy console.dll to the device’s Windows folder.
• Copy cmd.exe and shell.exe to anywhere on the device e.g. \My Documents.
• Edit the following registry key value on the device to be 0 : HKEY_LOCAL_MACHINE\Drivers\Console\OutputTo
• From the device’s File Explorer, just run cmd.exe and the command prompt should start up.

• Lock the device to user in order to restrict the user on the application and web sites he/she can access.
• Manage which applications the user can launch.
• Manage which web sites the user can launch. The application has a built in browser through which web sites are launched.
• Exiting the Kiosk, managing web sites and applications can only be done after having provided a password.
• The user scan view the battery status, display the on screen keyboard and disable/enable the scanner.

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows NT\Terminal Services\DisablePasswordSaving

​N.B. This setting only works in Windows CE 6.0 i.e. not any previous versions of Windows CE.

Basic steps:

• Download and install the Snippet Designer to make your life easier.
• Create snippet files either manually or using the Snippet Designer. These are simply XML files with the .snippet extension.
• Import them into the Code Snippets Manager in Visual Studio or simply point it to a folder containing the snippet files.
• Use the snippets in your code.

Suppose you a snippet of code for creating a region to surround your methods. Something like this:

#region Methods        


#endregion //Methods

The easiest way is to just modify the existing region snippet that comes with Visual Studio:

• Open the Code Snippets Manager from the Tools menu in Visual Studio.
• I’m using C#, I would select C# from the language drop-down.
• Expand the C# node and look and select “#region”.
• Navigate to the path displayed in the “Location” text box.
• Create another folder on your machine and copy and paste the pp_region.snippet file into it.
• Rename the file to something like region_methods.snippet.
• Open it in Visual Studio. If you’ve installed Snippet Designer. It will open the designer for the snippet. otherwise it will open it in the XML editor.
• Using the Snippet Designer change the name of the snippet at the top of the designer window to “methods region”.
• Using the Snippet designer change the snippet code to:

#region $name$

$selected$ $end$

#endregion //$name$

• I always like to add the region name as a comment after the #endregion directive so that when I’m browsing through code and see the end of a region I know exactly which region it is without having to scroll to the top of if. If you look at the above snippet, any variable is enclosed in $ signs. At the bottom of the designer you can set the “Defaults to” value to “Methods”. This ensures that $name$ is replaced with the default value. When you insert the snippet in your you’ll also notice that as you’re typing the name of the region, the comment after #endregion also changes to match the name at the same time.
• If you look under the Properties Window you’ll notice the Snippet Type property. It should be set to “SurroundsWith”. This ensures that if you select code in an editor and right click the selection and click “Surround With” and then a specific snippet like the we’re creating it will actually insert the selection within the snippet i.e. this is also achieved using the $selected$ variable you see in the snippet code.
• Also in the Properties Window change the “Author” and “Description”. In the description will be shown in the IntelliSense.
• Should you also want specific references to added to your project upon insertion of the snippet, you can add these references on the “References” property.
• Lastly change the “Shortcut” property to “regm”. This shortcut name will appear when scrolling through the IntelliSense.

Call me a bad programmer, shoot me if you want, but I decided to look at ways of being able to set the sequence/order in which my text fixtures and tests run. Initially I thought of downloading the NUnit source code and modifying it to use some sort of config file through which I set the sequence. The problem with this approach is twofold in my opinion. Firstly if a new release of NUnit comes out and they still decide not to include functionality for ordering of tests, but they do include some worthwhile new features, I’ll then have to reimplement the sequencing code, or at least copy and paste some code. Secondly, I don’t want some config file to set the sequence. That would mean I’d have to modify it every time I added another test, hitting alt-tab a million times etc. In short I basically wanted a way of simply setting the sequence in the source code, while I was coding.

NUnit actually runs tests in alphabetical order. So if you prefix every test with a number, such as _01_, _02_ etc., then you could effectively set a sequence to your tests. That’s allot of manual editing though. Not to mention that if you decide to add a test somewhere in the middle of the sequence, you’d have rename half your tests/fixtures. So what I’ve developed is a small library that just includes two attributes that can used to decorate your assembly and test fixtures, where you specify the sequence of your tests. I then built a small console app that can be called by setting a post-build event command on your test suite’s project. Once it runs it loads your built assembly and using Reflection it searches for the above attributes. Using Mono.Cecil the app then modifies the test fixture and test method names by prefixing them according to the specified sequence and then simply writes the new assembly to file. You then load it into NUnit and you’ll see the tests appear in the sequence you set through the attributes. Alright, so let me take you through it.

Firstly download the NUnit.Sequence assemblies from here: http://www.mediafire.com/?359rqn16f5lzx84

Suppose you have a library containing four methods performing basic arithmetic calculations:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace SampleLibrary
{
    public class Arithmetic
    {
        public double Add(double x, double y)
        {
            return x + y;
        }

        public double Subtract(double x, double y)
        {
            return x - y;
        }

        public double Multiply(double x, double y)
        {
            return x * y;
        }

        public double Divide(double x, double y)
        {
            return x / y;
        }
    }
}

You then write two text fixtures (for argument’s sake) to test the above methods:

• ArithmeticTests1 : containing test methods : SubtractTest & AddTest
• ArithmeticTests2 : containing test methods : MultiplyTest & DivideTest

If you run these tests, NUnit will run test fixture ArithmeticTests1 first and then ArithmeticTests 2. In the first it will run AddTest first and then SubtractTest. On the second test fixture it will run DivideTest followed by MultiplyTest. Suppose you want to change the sequence:

• Start by adding a reference to the NUnit.Sequencer.Coding.dll in your test suite project.
• To set ArithmeticTests2 to run first followed by ArithmeticTests1, expand the Properties folder in the Solution Explorer and open AssemblyInfo.cs. In this file add a SequencedTestAssembly attribute by specifying in its constructor the test fixture types’ full names (namespace included) according to the order in which you’d like them to run. The attribute’s constructor takes the names using the params keyword i.e. an array of strings.

[assembly: SequencedTestAssembly("NUnit.TestSuite.ArithmeticTests2", "NUnit.TestSuite.ArithmeticTests1")]

• Now in each of your text fixtures, add a SequencedTestFixture attribute to the class declaration by specifying in the attribute’s constructor the test method names which you’d like to sequence in the order in which you want them to run. Here’s the source code for the two text fixtures:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using NUnit.Framework;
using SampleLibrary;
using NUnit.Sequencer.Coding;

namespace NUnit.TestSuite
{
    [TestFixture]
    [SequencedTestFixture("DivideTest", "MultiplyTest")]
    public class ArithmeticTests2
    {
        private double _x;
        private double _y;
        private double _expected;
        private Arithmetic _arithmetic;

        [TestFixtureSetUp]
        public void Setup()
        {
            _x = 10;
            _y = 2;
            _arithmetic = new Arithmetic();
        }

        [Test]
        public void MultiplyTest()
        {
            _expected = _x * _y;
            Assert.IsTrue(_arithmetic.Multiply(_x, _y) == _expected);
        }

        [Test]
        public void DivideTest()
        {
            _expected = _x / _y;
            Assert.IsTrue(_arithmetic.Divide(_x, _y) == _expected);
        }
    }
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using NUnit.Framework;
using SampleLibrary;
using NUnit.Sequencer.Coding;

namespace NUnit.TestSuite
{
    [TestFixture]
    [SequencedTestFixture("SubtractTest", "AddTest")]
    public class ArithmeticTests1
    {
        private double _x;
        private double _y;
        private double _expected;
        private Arithmetic _arithmetic;

        [TestFixtureSetUp]
        public void Setup()
        {
            _x = 10;
            _y = 2;
            _arithmetic = new Arithmetic();
        }

        [Test]
        public void SubtractTest()
        {
            _expected = _x - _y;
            Assert.IsTrue(_arithmetic.Subtract(_x, _y) == _expected);
        }

        [Test]
        public void AddTest()
        {
            _expected = _x + _y;
            Assert.IsTrue(_arithmetic.Add(_x, _y) == _expected);
        }
    }
}

• You can also download the source code for this example here: http://www.mediafire.com/?e66ddg87kjbjs5x
• Copy the NUnit.Sequencer.exe (console app) and Mono.Cecil.dll files to the bin directory of the test suite’s project. You could also just add them to your project and set the “Copy to Output Directory” property of the files to “Copy if newer”. This will copy them automatically to the bin directory upon building the project.
• To get NUnit.Sequencer.exe to run after a build, right click the test suite project and then click “Properties” On the “Build Events” tab, copy and paste the following command:

NUnit.Sequencer.exe $(TargetPath)

• Build the project.
• Once built, you should find a newly created assembly in your bin directory with the name of your original test suite dll’s name with a .SEQUENCE suffix appended to it e.g. {assembly name}.SEQUENCE.dll
• Lastly, open the new assembly in NUnit and the test suite should look as follows:

In case for whatever reason NUnit.Sequencer.exe doesn’t execute correctly you could also run it from the command prompt to see where its execution stops e.g. you may have mistyped a test fixture type or method name.

Firstly you’ll need to build a simple .NET (SOAP) web service that has two methods. One to retrieve the server’s hostname and the other returns the current date and time on the server. I won’t go into detail on the steps required to develop this service as it’s pretty basic if you’re familiar with .NET. This is what the service code looks like:

<br />
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Services;
using System.Diagnostics;

namespace SampleNetService
{
    /// <summary>
    /// Summary description for Service1
    /// </summary>
    [WebService(Namespace = "http://tempuri.org/")]
    [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
    [System.ComponentModel.ToolboxItem(false)]
    // To allow this Web Service to be called from script, using ASP.NET AJAX, uncomment the following line. 
    // [System.Web.Script.Services.ScriptService]
    public class Service : System.Web.Services.WebService
    {
        [WebMethod]
        public string GetHostname()
        {
            return Environment.MachineName;
        }

        [WebMethod]
        public string GetServerDateTime()
        {
            return string.Format("Server Time: {0}", DateTime.Now.ToString());
        }
    }
}

The URL to the service on my machine is http://localhost/SampleNetService/Service.asmx.

I you’ve ever consumed a web service using a .NET client application, you’ll know that you normally just add a web reference on the project and Visual Studio automatically generates the stub classes which you can use on the client application i.e. the web service proxy. The first approach I came across is to use the KSoap libraries, but the implementation code looks incredibly verbose and it doesn’t look like there is anyway to generate the classes. Instead you pretty much have to code everything yourself (specifying the parameters, URL, method names etc.) and the libraries just handle the communication for you. If you’re interested in this approach you can have a look this tutorial on the subject:

• BlackBerry and .NET Web Service Tutorial – Part 1
• BlackBerry and .NET Web Service Tutorial – Part 2
• BlackBerry and .NET Web Service Tutorial – Part 3

I did find what seems to be a great API for generating stubs and consuming web services called WSClient++, which you can download from http://wsclient.neurospeech.com/. Unfortunately it’s a little too expensive for my liking. They have a demo version, but they limit you on accessing only two web services per project and being able to call (generate stubs for) only two web service methods.

So instead I opted for using the Java ME Platform SDK 3.0 to generate the stubs. It’s surprisingly easy and it just works. Firstly, download and install it from http://www.oracle.com/technetwork/java/javame/downloads/sdk30-jsp-139759.html. You can of course achieve the same result using the the Java Wireless Toolkit 2.5.2 which is the predecessor to the Java ME Platform SDK, which can be downloaded from http://www.oracle.com/technetwork/java/download-135801.html. If you’re interested in the nitty-gritty behind J2ME web services and consuming them, then have a look at this article http://developers.sun.com/mobility/apis/articles/wsa/.

Once you’ve gotten it in installed, navigate to the bin folder of your installation directory. On my machine it’s C:\Java_ME_platform_SDK_3.0\bin. The command line tool we’re going to use is wscompile.exe. To run the tool you’ll need to create a small config file which you’ll pass as an argument to wscompile.exe. So in this directory create a config.xml with the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  <wsdl location="http://10.120.6.24/SampleNetService/Service.asmx?wsdl" packageName="rpcdemo" />
</configuration>

In the wsdl element you’ll need to set the location to the URL of your web service including the ?wsdl suffix (which generates the wsdl file), as well as the packageName attribute. Also notice that in the URL I replaced localhost with the address of my machine hosting the web service. The reason being that the generated stubs will contain the URL which the device application will be pointed to. Therefore using localhost in the client application will result in it not being able to access the URL. You could obviously use the hostname of your machine instead of the IP address, provided that it will be able to resolve it. The package name corresponds to the package which will contain the generated stub classes.

Now from command prompt, navigate to the above directory and run the following command:

wscompile.exe -gen -cldc1.1 config.xml

After having run the command you should find a subdirectory in the bin directory named after the package name you specified in the config file. In my case it’s rpcdemo. If you get an error that it cannot parse the config file it’s because for whatever reason the tool does not recognize UTF-8 encoding. If you then in command prompt enter the following command to see the contents of the config.xml file, you’ll probably notice that there are some strange characters preceding the first line in the file:

type config.xml

To fix the issue, make sure that you create the config.xml file using a regular text editor as opposed to an XML editor.

Now let’s develop the BlackBerry application. Open the BlackBerry JDE and create a new workspace. Then create a new project in the workspace. We’ll now need to create a class extending MainScreen on which we’ll place two labels to display the info retrieved from the web service as well a button which initiates and performs the web service calls. We also need a class that extends UiApplication, which will push (display) the screen with the controls onto the screen stack. Separate packages aren’t strictly necessary, but in my example I create two separate packages to store these two classes in i.e. core (for the UiApplication) and ui (for the screen). So for each of the above two classes, right click the project and select Create new File in Project and append a subdirectory name to the path corresponding to the package you want created i.e. core or ui. The java files I’ve created for the screen and UiApplication are GetServerDateScreen.java (ui package) and  NetServiceBBConsumerApp.java (core package) respectively.

Open the NetServiceBBConsumerApp.java, clear the code in it and paste the following code:

</p>
/*
 * NetServiceBBConsumerApp.java
 *
 * © <your company here>, <year>
 * Confidential and proprietary.
 */

package core;

import net.rim.device.api.ui.*;
import ui.*;

/**
 * 
 */
public class NetServiceBBConsumerApp extends UiApplication
{
    public static void main(String[] args)
    {
        NetServiceBBConsumerApp app = new NetServiceBBConsumerApp();
        app.enterEventDispatcher();
    }
    
    NetServiceBBConsumerApp()
    {
    }
    
    public void activate()
    {
        if(getScreenCount() == 0)
        {
            //This is the first time the activate method has been called by the event dispatcher i.e. the app has just started up.
            this.pushScreen(new ui.GetServerDateScreen());   
        }
        else
        {
            //The application has just been reactivated e.g. the user might have switched to a different application deactivating this one and then switched back to this application.
            updateDisplay();
        }
    }
}

In the application’s entry method, main(String[] args), we create a new NetServiceBBConsumerApp which extends UiApplication. We then override the application’s activate function. This method gets called either when the application gets started or when perhaps a user navigates away from our application (by opening another application or taking a phone call) and then returns to our application. In this function we then check whether the application has just been launched (no screens exist on the stack yet) or whether the application has just been reactivated after another app has been closed (screens already exist on the stack). If this is a fresh start up of the appliation we create a new GetServerDateScreen (which contains our controls/fields) and push it onto the screen stack. If you’ve ever done .NET Compact Framework development or Windows Forms, you can think if this class as the Program class containing the main method that starts up the main form. Also notice that we’re importing the ui package at the top. Otherwise if this is a reactivation, we just call updateDisplay() which will refresh the device’s display for all the screens in the application.

In the GetServerDateScreen.java file, clear the code in it and paste the following code:

package ui;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import rpcdemo.*;

public class GetServerDateScreen extends MainScreen
{
    LabelField lblServerHostname = new LabelField("", LabelField.FIELD_LEFT);
    LabelField lblServerDate = new LabelField("", LabelField.FIELD_LEFT);
    ButtonField btnGetServerInfo = new ButtonField("Get Server Info", ButtonField.CONSUME_CLICK)
    {
        protected boolean navigationClick(int status, int time)
        {
            GetServerInfo();
            return true;
        }
    }
    public GetServerDateScreen()
    {
        setTitle("Current Server Date");
        add(lblServerHostname);
        add(lblServerDate);
        add(btnGetServerInfo);
    }

    public boolean onClose()
    {
        System.exit(0);
        return true;
    }

    public void GetServerInfo()
    {
        try
        {
            ServiceSoap_Stub service = new ServiceSoap_Stub();
            String serverHostname = service.getHostname();
            String serverDateTime = service.getServerDateTime();
            lblServerHostname.setText(serverHostname);                             lblServerDate.setText(serverDateTime);
        }
        catch(Exception e)
        {
            Dialog.alert(e.getMessage());
        }
    }
}

Here we basically create the two labels and a button on which we override its navigationClick method. This method gets called when the button gets clicked. So we handle this event by calling the GetServerInfo method which simply instantiates the ServiceSoap_Stub class that we generated earlier and calls the appropriate web service methods to retrieve the server’s hostname and date. Thereafter we display the results on the two labels. On this screen’s constructor we add the controls/fields to the screen.

The generated web service stub classes need to be imported into the project before we can build it. Copy the rpcdemo directory from C:\Java_ME_platform_SDK_3.0\bin to the your project’s directory. To import them, right click the project and select Add File to Project. Navigate to the project’s rpcdemo subdirectory and select all the java files in it. In this example there should be six of them. The project’s file structure should look as follows:

BlackBerry JDE demo file structure

If you open the ServiceSoap_Stub class, in its constructor you’ll notice the URL you specified in the config file. So if the location of the service ever changes this is where you can change the URL before rebuilding the mobile application. One very important thing to remember is that an application will by default try to connect to via MDS. So although you might find that it can connect to the web service on an emulator, it will fail to connect once deployed on the device if the device is not connected to the MDS. Therefore, you need to specify in your code whether to use MDS, a straight GPRS connection via your service provider or a connection via WiFi. You do this by appending a connection string to the end of your web service URL in the ServiceSoap_Stub’s constructor. For example to force a WiFi connection you would append “;interface=wifi”. For a straight GPRS connection, you would append “;deviceside=true”. Here’s a method you can include in your code that generates and appends the correct connection string to your URL depending on whether an MDS or WiFi connection is available, otherwise a straight GPRS connection.

    // Determines what connection type to use and returns the necessary string to use it.
    // @return A string with the connection info
    public static String getConnectionString(String connectionString)
    {
        // This code is based on the connection code developed by Mike Nelson of AccelGolf.
        // http://blog.accelgolf.com/2009/05/22/blackberry-cross-carrier-and-cross-network-http-connection                 

        // Simulator behavior is controlled by the USE_MDS_IN_SIMULATOR variable.
        if(DeviceInfo.isSimulator())
        {
            //Dialog.alert("Device is a simulator and USE_MDS_IN_SIMULATOR is false");
            connectionString += ";deviceside=true";                
        }                               

        // Wifi is the preferred transmission method
        else if( (WLANInfo.getWLANState() == WLANInfo.WLAN_STATE_CONNECTED) && RadioInfo.areWAFsSupported(RadioInfo.WAF_WLAN))
        {
            //Dialog.alert("Device is connected via Wifi.");
            connectionString += ";interface=wifi";
        }

        // Is the carrier network the only way to connect?
        else if((CoverageInfo.getCoverageStatus() & CoverageInfo.COVERAGE_DIRECT) == CoverageInfo.COVERAGE_DIRECT)
        {   
            //Dialog.alert("Carrier coverage.");
            String carrierUid = getCarrierBIBSUid();
            if(carrierUid == null)
            {
                // Has carrier coverage, but not BIBS.  So use the carrier's TCP network
                //Dialog.alert("No Uid");
                connectionString += ";deviceside=true";
            }
            else
            {
                // otherwise, use the Uid to construct a valid carrier BIBS request
                //Dialog.alert("uid is: " + carrierUid);
                connectionString += ";deviceside=false;connectionUID="+carrierUid + ";ConnectionType=mds-public";
            }
        }                

        // Check for an MDS connection instead (BlackBerry Enterprise Server)
        else if((CoverageInfo.getCoverageStatus() & CoverageInfo.COVERAGE_MDS) == CoverageInfo.COVERAGE_MDS)
        {
            //Dialog.alert("MDS coverage found");
            connectionString += ";deviceside=false";
        }

        // If there is no connection available abort to avoid bugging the user unnecssarily.
        else if(CoverageInfo.getCoverageStatus() == CoverageInfo.COVERAGE_NONE)
        {
            //Dialog.alert("There is no available connection.");
        }

        // In theory, all bases are covered so this shouldn't be reachable.
        else
        {
            //Dialog.alert("no other options found, assuming device.");
            connectionString += ";deviceside=true";
        }        

        return connectionString;
    }
    
    // Looks through the phone's service book for a carrier provided BIBS network
    // @return The uid used to connect to that network.
    private static String getCarrierBIBSUid()
    {
        ServiceRecord[] records = ServiceBook.getSB().getRecords();
        int currentRecord;
        for(currentRecord = 0; currentRecord < records.length; currentRecord++)
        {
            if(records[currentRecord].getCid().toLowerCase().equals("ippp"))
            {
                if(records[currentRecord].getName().toLowerCase().indexOf("bibs") >= 0)
                {
                    return records[currentRecord].getUid();
                }
            }
        }
        return null;
   }

Once you’ve built the project, using a command prompt window navigate to the project’s folder and there should find a new COD file. This is the BlackBerry executable that needs to be deployed to the device. To deploy, run the following command after connecting the device via a USB to the machine:

javaloader -usb load NetServiceBBConsumer.cod

On the device you need to set the permissions for the application by clicking Menu > Options > Applications, selecting the application and making sure every field is set to allow.

Next we need to configure the device to connect to the WiFi, test the connectivity with your machine and web service and lastly test the application.

WiFi:

• Enable WiFi on the device by clicking Menu -> Manage Connections and checking the WiFi checkbox.
• In the same pop up menu select Wi-Fi Options.
• To connect to a specific WiFi AP (Access Point), click Menu > New and then Scan For Networks.
• Select your WiFi network/AP and enter all the relevant wireless settings for your AP i.e. security type, key etc. and then click Connect.

Test the connectivity to the server (your development machine) and web service:

• Click Menu > Manage Connections > Wi-Fi Options > Menu > Wi-Fi Tools
• Select Wi-Fi Diagnostics from above available tools menu to ensure you’re connected to the correct WiFi network and view your IP Address.
• From your machine try pinging your device with the above IP address.
• From the device select the Ping tool from the above tools menu and enter the IP Address of your machine followed by clicking Menu > Send Ping.
• To go a step further you can establish whether the device can access the service, by opening the device’s internet browser.
• Once inside the browser, in the top right hand corner you should see a WiFi icon. Otherwise if any other icon such as EDGE is displayed you won’t be able to access any resource on the WiFi network. Unfortunately as we all know a BlackBerry phone is a merely a phone, not an iPhone, therefore it’s not smart enough to choose the least expensive network automatically. To switch to WiFi for browsing, in your browser, click Menu > Options > General Properties and from the Default Browser drop down select Hotspot Browser followed by clicking Menu > Save Options. Then click the Broser Configuration menu item and from the Browser drop down ensure that Hotspot Browser is selected and then save the options by clicking Menu > Save Options.
• Lastly in your browser, enter the URL of your web service in the address bar and hit enter on the device’s keyboard.

Test the application:

• Click Menu > Downloads and select the application you’ve just built and deployed.
• Once it starts up, click the Get Server Info button and it should now hit the service and shortly after display the server’s hostname and date on the two labels.

That’s pretty much it. You can also download the source code from here: http://www.mediafire.com/?g3hnbhwrd2k3s5e

Firstly you’ll need to decide on the type of application you’ll develop. These are your options:

• RIMlet : a native BlackBerry application that utilizes the BlackBerry APIs to provide the application with a BlackBerry look and feel by using the native UI APIs, as well as other BlackBerry services such as the BlackBerry Enterprise Server to send/receive emails (an many more) or send BBMs. A RIMlet uses the CLDC API’s which are part of J2ME. The only drawback being that a RIMlet can only run on a BlackBerry device.
• MIDlet : a generic J2ME application based on the UIDP and CLDC specifications. As I’m sure you know like with any Java application, the basic idea behind a MIDlet is that you supposedly “write once, run anywhere” i.e. it should run on any device without any modifications. Using this approach you can develop the MIDlet in your favorite Java IDE, but you cannot however just deploy and run the JAR//JAD files on the device. They instead need to be converted to a native BlackBerry executable, which is a COD file. In my short experience with MIDlets for BlackBerry, this isn’t as great or as easy as it sounds. Primarily because I’ve noticed that on some occasions, the conversion process results in build errors. Also the application doesn’t necessarily behave the same way on a BlackBerry as it does on the J2ME emulator. One of the reasons being that it seems like J2ME applications seem to be targeted at devices with the retro style left/right (select/menu) keys. This according to the documentation requires remapping of the keys etc. I didn’t spend much time on MIDlets to be quite honest, but personally I wouldn’t recommend this approach unless you have an existing MIDlet you’re attempting to port to a BlackBerry. If you insist on this approach, you might want to go through this tutorial on Programming the BlackBerry With J2ME which you faind here http://www.oracle.com/technetwork/systems/index-139239.html.

Regardless of the type of application you’ll be building, you’ll need to create a BlackBerry developer account to access the downloads, documentation and forums. You can do that from here: http://us.blackberry.com/developers/.

Let’s have a look at the different IDEs that you can use:

• BlackBerry JDE: If you’re going to be developing using Java, this IDE is a must. You might however, get away without it if you’re using the BlackBerry plugin for Eclipse. Personally after struggling with IDEs I eventually settled for the BlackBerry JDE. It turned out be the only environment where everything seems to just work out of the box. It does seem a little primitive relative to other IDEs like NetBeans and Visual Studio. It has an IntelliSense/Autocomplete feature, but it isn’t that great. The API documentation is included with the installer but class/method specific documentation is not displayed in the Intellisense. There is a feature that allows you to right click a class in the editor and select “Show help for <class name>”, which opens the documentation in your browser. Each version of the JDE maps to a specific version of the BlackBerry OS running on a device. According to the documentation, the APIs are backwards compatible. In other words an application built using the JDE 5.0 should in theory run on a device running OS 6.0, but not vice versa. I’m using a BlackBerry Curve 9300 with OS 5.0. Therefore I downloaded version 5.0 of the JDE. You can download it from http://us.blackberry.com/developers/javaappdev/javadevenv.jsp and the version specific documentation and guides from http://docs.blackberry.com/en/developers/subcategories/?userType=21&category=Development+Guides.
• BlackBerry Eclipse plugin : this environment seems to provide pretty much the same results as the JDE with the exception that Eclipse is a more mature environment with more features. BlackBerry provides a full installer that includes Eclipse bundled with the plugin, which you can get from http://us.blackberry.com/developers/javaappdev/devtools.jsp. At the time of writing I downloaded version 1.3, which only includes the BlackBerry JRE 6.0. The plugin has a feature that allows you to download component packages required for a specific OS version. When initiating the download you need to enter the update site URL. I’ve found various URLs which didn’t work, so clearly the URL seems to change from time to time. As far as I’ve heard, the update feature on the plugin has been discontinued, but I did find a URL that worked : http://www.blackberry.com/go/eclipseUpdate/3.6/java. To perform the update in Eclipse, click Help > Install New Software. In the dialog that appears click Add and then enter either the above URL or enter the location of the component package on your machine if you’ve downloaded it directly from the site. I didn’t spend too much using this IDE, mainly because there were way too many hoops I had to jump through i.e. I couldn’t figure out how to start the emulator or debug on it or on the device for that matter using the 5.0 JRE. Reading through online forums, it seems I’m not the only developer not happy with this plugin. Lastly regarding this IDE, if you’re keen on trying to get it working on an Ubuntu box (i.e. Linux), you can have a look through this post http://od-eon.com/blogs/bogdan/blackberry-environment-setup-under-ubuntu/. It’s a bit of a hack, but I managed to get the IDE installed and running, but it’s running through Wine i.e. you won’t be running the Linux version of Eclipse, but rather the Windows one.
• NetBeans : since this is such a great IDE, this was my first choice, but unfortunately I did have numerous problems in getting anything working. You can download it from http://netbeans.org/. Firstly, to develop a native BlackBerry application you need to point your project to the correct APIs. Just to do that you need write up your own build config file. Next, after you’ve gotten the project to build you’ll need to write a config file to get the BlackBerry simulator to run. You can get all the gory details here http://www.scribd.com/doc/29831850/Setting-Up-Blackberry-Development-Environment. Once you’ve gotten all of that working you’ll notice that you can’t attach the debugger to the simulator or device for that matter. I remember reading some post, on getting it working in the simulator by some guy that reversed engineered the APIs to find out how to get it working. In the short time I spent playing with NetBeans I got the impression that using it is pretty much a hack. I’m not even sure why RIM says that it’s a supported IDE. Obviously, if you’re going to develop J2ME applications, NetBeans is your friend. Once you’ve built your MIDlet into JAR/JAD files, you’ll need to convert it to a COD file using either the BlackBerry JDE or a command line cool that comes with the JDE called rapc e.g. rapc import=”c:\BlackBerryJDE3.6\lib\net_rim_api.jar” codename=LoginMIDlet -midlet jad=LoginMIDlet.jad LoginMIDlet.jar. From what I gather most developers using NetBeans develop and build their applications in it and then copy the source files into the JDE for debugging, which is possible, I’ve tested. Once you’ve copied the JAR and JAD files into a JDE project, regardless of whether it’s a native BlackBerry application or MIDlet it will try to convert them to a COD file when you build the project. After adding the Java source files to the project and setting breakpoints you can then attach the debugger to the simulator or device and do the debugging.
• Visual Studio : RIM used to have an MDS plugin for Visual Studio that allowed you to create screens in a drop and drag fashion similar to .NET Compact Framework applications and all event handlers had to be coded in JavaScript. You can read all about it here http://kvnc.net/content/binary/BlackBerryNet.pdf. I’m not sure why, but this plugin has been discontinued. Instead, they now have a the BlackBerry WebWorks plugin for Visual Studio, through which you build web applications using ASP.NET and the plugin provides a BlackBerry simulator. It’s basically just a web browser with a BlackBerry skin around it. You can download it from http://us.blackberry.com/developers/browserdev/devtoolsdownloads.jsp and the documentation, guides and videos on it from http://supportforums.blackberry.com/t5/Web-Development/How-to-Use-the-BlackBerry-WebWorks-Plug-in-for-Microsoft-Visual/ta-p/446830.

Alright, so now that you’ve got your IDE in place, this might be a good time to start coding something. I’ve found some great posts to help you get your feet wet by developing some sample native BlackBerry applications using the BlackBerry JDE:

• How to write your first BlackBerry application – Lesson 1 : UI Fields
• How to write your first BlackBerry application – Lesson 2 : Mail API Invoke and API Menu
• How to write your first BlackBerry application – Lesson 3 : Create Shortcuts and more

If you ever run into any issues, there are developer forums available here http://supportforums.blackberry.com/t5/Developer-Support-Forums/ct-p/blackberrydev as well as being able to mail development support center using the devsupport@rim.com. Don’t get your hopes up the email address, I’ve sent two or three mails to this address and still haven’t gotten a reply.

Now depending on the device you’re planning on developing for you’ll need to download and install the corresponding simulator for it. You can the download the simulators from http://us.blackberry.com/developers/resources/simulators.jsp. As I mentioned before, my preferred IDE is the BlackBerry JDE so I’ll only mention how to get the emulator running in the JDE, but even if you’re running it in NetBeans you can still use the JDE to set it up. So to get a project running in a given simulator, once you’ve installed it, you’ll need to open the JDE, click Edit > Preferences and select the Simulator tab in the dialog that opens. From the Profile drop down box select the simulator you’ve just installed. Now you should be able click Debug > Go and the simulator will start running and your application will be deployed to the to it. Also note that unlike other platforms, the application doesn’t just start running once the emulator has booted up. Instead it gets deployed to the Downloads folder from where you’ll need to start it up i.e. Menu -> Downloads. One of the issues I’m sure you’ll notice is that the emulator takes incredibly long to boot and there doesn’t seem to be a way of saving its state like with the Windows Mobile emulators. In other words, on first inspection it seems like every time you want to debug you have to restart the emulator and wait roughly 30 seconds. One workaround is to instead start the emulator from the Start menu > Research In Motion > BlackBerry Smartphone Simulators <platform version> > <platform version>. Then in your JDE instead of clicking Debug > Go, click Build > Build / Build All. Then in your simulator click on File > Load BlackBerry Application or Theme. Browse to your project’s directory and select the COD file. The application will get installed in the Downloads folder on the simulator. In the JDE click on Debug > Attach to > Simulator. This may take a little while so be patient.  Then simply set breakpoints, start your app on the simulator and debug your heart out. One issue you might encounter with the simulator is that it might appear like the keys are not working i.e. pressing keys has no effect or you only see a change on the screen after perhaps 30 seconds. Before you throw your toys out the cot, on the simulator, click View > Graphics Acceleration and select it to be Off.

Running and debugging your application on a device is fairly straight forward. Once you’ve built the project and connected the device to your machine via a USB cable, open a command prompt and go to the project folder containing the COD file. Type the following command : javaloader -usb load <file_name>.cod. Your device’s screen should go white indicating an installation and then return to normal. The application will be in your Downloads folder. Upon attempting to run the application you may be prompted to set the permissions on the application. If not, then navigate to Menu > Options > Applications and select your application. Click Menu > Edit Permissions and ensure that Connections and User Data are set to Allow, with Interactions  possibly set to Custom. Should you not set the permissions your application will probably not run. To Debug, in the JDE click Debug > Attach to > Handheld > <device’s name>. This again might take a little while and if one or two error messages pop up, just remember that these error messages are only there to make you scared of BlackBerry development … but don’t be afraid, just click OK, nothing bad will happen. Once it’s done, set your breakpoints and start the application from the device.

You might find it also useful to be able to control your device from your PC. You can purchase the SOTI Pocket Controller for BlackBerry for that purpose, which can connect to the device either through USB or WiFi.

Lastly, if you went through all of the above mentioned tutorials, you will have noticed that you can run them on the simulator, but on the device you get an error saying that the application is trying to access restricted BlackBerry APIs. The reason for this is that RIM secures their APIs to prevent people from developing possibly malicious software and therefore they want to keep track of who developed what application and which APIs they’re utilizing. Therefore you’re required to get a signing key from RIM and sign every application that uses any of the restricted APIs. Apparently in the past, getting this key was not for free, but now it is. The basic process for submitting a request, receiving a key and signing an application is as follows according to RIM:

1. Get a CSI file from RIM by applying for code signing keys here https://www.blackberry.com/SignedKeys/. It may take RIM up to 48 hours to them to respond.
2. Configure communication to the RIM Signing Authority.
3. Register with the RIM signing authority using the provided CSI file.
4. Request a BAR file signature from RIM Signing Authority.
5. Create or provide an existing developer certificate.
6. Sign the BAR file with the developer certificate.
7. Publish the application.

The whole signing process is also explained in the documentation related to your JDE as well as here http://docs.blackberry.com/en/developers/deliverables/23959/Signing_your_application_1422721_11.jsp

Once you’ve received the CSI files (you should get 3 of them through email), simply follow the process as described in their emails i.e. create private key password etc. You need to do that with all the CSI  files you received from. Lastly once you’ve built a project in the JDE, go to the project folder and ensure that it contains the COD file as well as a CSO file, both of which get created by the JDE. To sign the COD file, simply double click it and a signing dialog should appear, indicating which utilized APIs of the application require signing. Select the API that requires signing and Click on the Request button. The status of that API should change to Signed. You will also receive an email indicating your success of failure to sign your application.

Alright, so hopefully you now you have a basic idea of the basics on getting started with BlackBerry development. Since I’ve also just started I’d really appreciate it if anyone can provide this post with more tips/tricks/advice on things you might have experienced or problems you were faced with and solved.

Read my next post on  how to develop a BlackBerry native application that consumes a .NET Web Service using the Java ME Platform SDK 3.0.

http://whatpaulhaslearnt.wordpress.com/