V3m.exe
09/03/2007 Dolphin Hawkins (spam.vault@gmail.com)

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

This tool can be used to convert a J2ME application contained in a jar file for use with 
a Sprint V3M, then copy the file to the phone.
V3m can be used from the command line, or from windows by dragging and dropping the files
that you want to convert to V3m.exe.
After each run, the v3m.ini file is updated with the last used options.  Run v3m from 
the command line or edit v3m.ini to change the options to your liking.

V3m can take any number of jar files or folders as arguments.  A folder argument will
process all jar files in that directory (but does not process sub folders).

If you have python installed on your system, you can use the script version of this app
'v3m.py' which should have been included with the distribution.  You will need to install
BitPim and its dependencies as well as PIL (http://www.pythonware.com/products/pil/).

BitPim:
The communication with the phone is done using BitPim (www.bitpim.org) libraries.  It is 
recommended that you first get your phone working with BitPim before using the phone
transfer features of this application.


V3m.ini:
All the optiosn can be configured via the command line, or editing the V3m.ini file that
is created the first time you run V3m.  The descritpion of the options are as follows:

category:   This is the slot to put the app into in the menu.  'Games' is supported, I 
            don't know what else works.
quit:       If this is False, the console window will remain open until you press a key.
comport:    This is the port to use when pushing games down to the phone.  Set it to 0
            to disable phone communication or the number of the port you have your phone
            connected to.
continue    Set this to true if you want to skip errors in converting files.
action      none - Create the jad and jar files, but skip all phone actions.
            copy - copy the created files, but do not restart the phone.
            install - restart the phone after the files are copied.
            verify - report on the success or failure of the copied files and remove the
              generated files for the successful ones.
output      directory to put the generated files, relative to the first jar file
icon        icons must be 15x15 png files.  If the game lists an icon, but does not 
            actually contain one in the jar file, add this one in its place.
            
            




Problems:

    * If your phone hangs when going to the games menu, this usually means that there 
      was a problem with one of your files, or you put it in the wrong place.  My phone
      will hang for 10-15 seconds while it is deleting the files, and then work normally.

    * Sound - most of the games I have tried didnt have working sound.  There may need 
      to be something added to the .jad to get it to work (assuming the game has working 
      sound on the phone at all.

    * Some games are just not compatible.  I haven't hurt my phone yet copying apps over 
      that don't run, but make sure that you trust the source of your apps, and they are 
      designed for this phone.
    

=========

Read below for a more detailed explantion of how this tool works.

My V3m is set up as described in this thread:

http://www.motomodders.net/Default.aspx?tabid=55&forumid=79&postid=282296&view=topic
 
The V3m is not fully supported with BitPim, but we only need the Filesystem feature, and 
that works fine.

I may have also done some seem edits that effect this, but I am not sure, let me know if 
you have any problems.

I am going to walk through the process of installing midpman.jar (downloaded from this 
site).


Process:

1. The games you install must be named using a number (any number seems to work). To make
things easy just start with 1.  This number is only used to install, so if you are 
installing one game at a time you can always use 1.  The phone will properly change the 
filenames when it installs them. 

2. Extract the file META-INF/MANIFEST.MF from your jar file and open it up in notepad 
(jar files are basically renamed zip files, use any toosl you have for unzipping files 
to get it).  Take a look at the MIDlet-1 entry.  There will be 3 parts to it; the second 
one is the application icon, in this case MIDP-Man.png.  Unfortunately this file doesnt 
exist in the jar file, so we have a problem.  We either need to add a file to the jar 
file, or edit the manifest to make the second entry blank.  (Note: icon files must be 
15x15 png files.  Most of the games that I have tried use different size icons.  You 
will need to convert them, or just deal with the default icon).  I chose to add the 
file, but you can omit it by changing the line to:

    MIDlet-1: MIDP-Man,, midpman

If you edit the manifest, make sure you move it back into your jar file.

3. Save a copy of the manifest file as 1.jad and a copy of the jar file as 1.jar.

4. Edit 6.jar and add the following lines:

    MIDlet-Jar-Size: 24078
    MIDlet-Jar-URL: 1.jar
    Content-Folder: Games
    MIDlet-Icon: MIDP-Man.png

The jar size you can get by right clicking on the file and selecting properties.  Set 
the jar URL to the name of the jar file.  Your size might be different if you used a 
different icon (or no icon).  If you chose no icon, you still need the icon line:

    MIDlet-Icon:

Just leave the part after the : blank.

*5. This file doesnt have any wrapped lines, but you might need to correct them for 
other games.  A wrapped line will start with a space like (this step may be unnecessary):

    MIDlet-Permissions: javax.microedition.io.Connector.
     datagram,javax.microedition.io.Connector.data
     gramreceiver, javax.microedition.io.Connector.htt
     p, javax.microedition.io.Connector.sms

These need to be changed so they are all on one line (turn off word wrap to make sure 
they are all on one line).  Position your cursor after the space an hit backspace twice 
to connect it to the previous line (this probably will wrap in the browser window):

    MIDlet-Permissions: javax.microedition.io.Connector.datagram,javax.microedition.io.Connector.datagramreceiver, javax.microedition.io.Connector.http, javax.microedition.io.Connector.sms

  (step removed, the 1.txt file is not needed, it  will be auto generted)

6. Copy both of these files to /motorola/shared/jas/temp/install while you are at the 
default phone menu (if you are on the games menu, your game will not be installed).    
Restart your phone and (if everything was done correctly) the game will show up in the 
games menu.

 

Problems:

    * If you get the error Failed to open application manifest Then there is a problem 
    with your manifest file, your jad file, or the two dont match.  The manifest file 
    is probably okay (unless you edited it), but the jad file MUST have an icon line, 
    and the icon MUST match the icon in the MIDlet-1 line.  ALSO if there is an icon, it 
    MUST be present in the jar file.  If the icon is there, but is not the correct 
    format, your game will load fine, with the default icon in the menu
 

Notes on the txt file:  You can copy a txt file for each game into the install dir, but it is not necessary.  I am not sure if you gain anything by having a differet txt file.
JARF and JADF should be set to the gameId.
MSIZ is the combined size of the jar and jad file.  With both files selected, right click and select properties and use the size in bytes (without , or .).
ISIZE is the size of the icon file x2
NAME, VEND and ICON are copied out of the jad file.
RSIZ - 0 1000 128000 256000
DOMA - 0 2 3
PERM - the values can be set to 0 1 or 2
SGLE - 0 115
ROLE - 0 20
DLCK - 0 1
ALOW - 0 1
CATE - I think this is the category that the app shows up in, 1 appears to be games
STAT - 0 1
COID - seen a couple of different strings here
TIME - this appears to be a timestamp of some sort, probably used for apps that disable after a certain time.