GThing Shell API and Tool Development

This page contains all shell commands implemented in GThing as well as information to help in the development of GThing Tools. The GThing Shell and Tools have access to the same API set making the shell an important part of tool development. The rest of this page explains what constitues a tool, the shell API, and an example tool

GThing tools are lua programs with specific extensions for manipulating LG 3G mobile phones. A GThing tool comprises of a .lua file containing the lua script to be executed and a .txt file containing a description of the tool along with how to operate it and any risks involved with running the tool. GThing tools have access to the standard lua libraries of: base, table, string, and math. GThing specific extensions are accessed through the "gt" library as follows:

string = gt.Device()

Returns the device name of the connected phone.

Example:
gt.Device();
U8380

string = gt.Directories()

Returns a list of top-level directories supported on this phone. The directories are returned as a string with elements seperated by colons.

Example:
gt.Directories();
Images:Audios:Videos:Java:VoiceRecord:Animations

string = gt.IMAGES()
string = gt.VIDEOS()
string = gt.AUDIOS()

Returns a localised version of the "Images" (videos, or audios) directory string. The Images directory varies between handsets and also between selected languages. This function always return the correct string for the Images directory.

Example:
gt.IMAGES();
Immagini

string = gt.FileList(directory)

List files in given directory and return the list as a colon seperated list. Directories end in '>D', other filetypes may have other extensions.

Example:
gt.FileList(gt.IMAGES());
blue.jpg:bluepengu.jpg:green.jpg:orange.jpg:pink.jpg:Default images>D

string = gt.GetFile(filename, directory)

Retrieve a file from the handset with given filename in given directory

Example:
data = gt.GetFile('blue.jpg', gt.IMAGES());

gt.PutFile(filename, directory, data)

Uploads data to the handset to a given file in a given directory.

Example:
gt.PutFile('new.jpg', gt.IMAGES(), imageData);

gt.DeleteFile(filename, directory)

Deletes a given file from a given directory.

Example:
gt.DeleteFile('blue.jpg', gt.IMAGES());

gt.RenameFile(directory, oldname, newname)

Renames a given file 'newname' in given directory to 'newname'.

Example:
gt.RenameFile(gt.IMAGES(), 'blue.jpg', 'new.jpg');

gt.CreateDirectory(directory)

Creates a new directoy on the handset with given directory name. Not all devices support the directory protocol and thus this function is not supported on all devices, however, always appears to succeed.

Example:
gt.CreateDirectory(gt.IMAGES() .. '/newImages');

gt.RenameDirectory(directory, newdirectory)

Renames new directoy on the handset with given existing and new directory name. Not all devices support the directory protocol and thus this function is not supported on all devices, however, always appears to succeed.

Example:
gt.RenameDirectory(gt.IMAGES() .. '/newImages', gt.IMAGES() .. '/newImagesBackup');

gt.DeleteDirectory(directory)

Deletes directoy on the handset with given directory name. Not all devices support the directory protocol and thus this function is not supported on all devices, however, always appears to succeed.

Example:
gt.DeleteDirectory(gt.IMAGES() .. '/newImages');

result = gt.SaveFile(filename, data)

Requests to save a file to the local computer with a reccommended filename from given data. Returns true if the file was saved or false if the user aborted the save request. This function opens a "Save as.." dialog box for the user so that they can choose where to save the file. No direct file access is included to ensure tools cannot write to arbitrary files on the host computer.

Example:
gt.SaveFile('blue.jpg', jpgData);

data = gt.LoadFile()

Requests to load a file from the local computer. Returns the loaded file if the load operation completed successfully or nil if the user aborted the file load. This function opens a "Open.." dialog box for the user so that they can choose which file to open. No direct file access is included to ensure tools cannot read from arbitrary files on the host computer.

Example:
jpgData = gt.LoadFile()

gt.Message(string)

Presents a message box to the user containing 'string' and waits for user interaction before proceding. The user can cancel at this point which will terminate the current lua program without returning from the Message call.

Example:
gt.Message('Welcome to MyTool v1.0');

gt.Choice(string)

Presents a message box to the user containing 'string' and waits for user interaction before proceding. The user must either choose 'yes' or 'no' in response to the message. Choosing 'yes' results in Choice returning true, 'no' returns false. The user can also cancel at this point which will terminate the current lua program without returning from the Choice call.

Example:
gt.Choice('Proceed to backup all images?');

table = gt.Options(table)

Presents a list of combo boxes and/or text entry boxes with default values. The table parameter defines which widget is displayed and what its possible values are. The table uses three elements per widget as follows:

A short name for the input item, eg "Filename"
A list of possible values in the case of a combo box, or the empty string in the case of an edit box, eg "blue.jpg:red.jpg:green.jpg" or ""
A default value in the form of a string, eg "blue.jpg"

Each widget does not have to be of the same type, ie, you may have both text entry widgets and combo boxes in any order on the same options screen. The table may be of any size. Options returns a table where each single element is the resulting data from the choice screen for the widget of the same index in the input table. Returns nil if the user canceled the request.

Example:
res = gt.Options({"Filename", "blue.jpg:red.jpg:green.jpg", "blue.jpg", "Create Backup", "Yes:No", "Yes", "Backup Filename", "", "backup.jpg"});
{"red.jpg", "Yes", "redbackup.jpg"}

Please note that in order to see string results in the shell you will need to print the returned data from a function, eg, print(gt.Directories());.

Additional function may be added at the request of developers. Current plans are to include JAR handling routines and unicode functions in future releases.

An Example GThing Tool

This example tool simply shows how to use the gt.Choice function. It allows the user to select a directory and possbile sub directories, download a file, and prompt the user to save it to disk.

downloader.lua

   1  -- Downloader
   2  
   3  --Perform a UI loop looking for a specific file
   4  lastDirectory = "";
   5  dir = "";
   6  filename = ">D";
   7  directories = gt.IMAGES() .. ">D:" .. gt.AUDIOS() .. ">D:" .. gt.VIDEOS() .. ">D";
   8  while (string.find(filename, ">D") ~= nil) do
   9  	-- Prompt for directory/file to download
  10  	lastDirectory = string.gsub(filename, ">D", "");
  11      default = string.sub(directories, string.find(directories, "[^:]"));
  12      optTable = {"Directory or file to download", directories, default};
  13      downloadTbl = gt.Options(optTable);
  14      if (downloadTbl == nil) then
  15          return;	
  16      end
  17      filename = downloadTbl[1];
  18  
  19  	-- If a directory was chosen, update the current directory
  20      if (string.find(filename, ">D") ~= nil) then
  21  		if (string.len(dir) == 0) then
  22  		    dir = string.sub(filename, 1, -3);
  23  		else
  24  		    dir = dir .. "/" .. string.sub(filename, 1, -3);
  25  		end
  26          directories = gt.FileList(dir);
  27  	end
  28  end
  29  
  30  -- Download the file
  31  data = gt.GetFile(filename, dir);
  32  if (data == nil) then
  33      gt.Message("Unable to download file");
  34  	return;
  35  end
  36  
  37  -- Request to save it if possible
  38  gt.SaveFile(filename, data);