tilp core
Reference manual

What in this manual ?

This documentation is for those who want reuse the tilp core under different Operating System such as Linux, Windows or BeOS. The functions described are independent of the GUI (Graphic User Interface) which allow anyone to port the tilp core on another platform or design another linking program.
The documentation is divided into six chapters:

Chapter 1: Introduction discusses about the tilp core and provides an overview of available functions.

Chapter 2: Data types tells about the different definition of types which are provided to the user.

Chapter 3: Setting up core guides you through the steps to set up the core of tilp for using it.

Chapter 4: General functions details the software functions that are independent of the GUI.

Chapter 5: tilp functions details functions that are specific to ??.

Chapter 6: Appendices include installation instructions for the libTIcable library and procedures to add the lib to your system. In addition the Appendix D explains the procedure for compiling programs which use this library. For your convenience separate Appendices cover "Flags for use", a "Code Index" and a list of "Error messages".

I Introduction

Chapter 1 provides an overview of the tilp core. The topics covered are:

• overview,

• functions,

• conventions used in this manual.

Overview

The tilp core contains routines to handle the different basic procedures of a linking program for the TI calculators under different platforms.

The supported platform are: Linux, Windows9x, WindowsNT4, BeOS and maybe Macintosh. The platform is only limited by the portability of the Glib (http://www.gtk.org).
The 'tilp core' make an extensive use of linked list for handling selection, directory list, building header files. The linked list comes from the Glib.

The supported link cables are those are supported by the libti_cables library.
The supported calculators are those supported by the libti_calcs library.

The tilp core use the original TI's file format for storing the variables.

The tilp core supports these operations depending of the calculator capability:
- remote control/command
- screen capture
- sending and receiving of one variable or more variables into a single or a group file
- sending and receiving backups
- getting the ROM version
- getting a ROM dump
- FLASHing (free FLASH applications and Operating System of the calculator).

Although the tilp core is independent of the GUI, it is able to display some dialog boxes in order to interact with the user. This is made by some callbacks functions which contains the GUI dependant code but outside the core.

Functions

The 'tilp core' is a set of 'C' languages subroutines designed to provide the basic functions for building a linking program independantly of the platform and even the Graphic User Interface.

The tilp core (Linux version) was written and tested using gcc under Linux.
It was ported under Windows and tested using the Microsoft Visual C++ version 5.0. It seems that others compilers such as Borland C++ 4.0 or DJGPP do not work because they do not support long filenames ! In my mind, Microsoft compiler is a good choice (hmm, I prefer Linux !).
It was ported under BeOS ...
It was ported under Mac ...

The functions are supplied both in source form and linked as a DLL. The source code is released under the GPL licence and the libraries under the LGPL license.

Each function is presented with its formal definition, including data types of all input and output variables. A brief description of the purpose of the function is provided along with the legal values for inputs where applicable. All structures and flags used by the 'tilp core' are in Appendix G: "Flags for use".

Functions are written as "C" functions, i.e. they return values. A non zero value signifies an error.


Conventions used

To help differentiate between different kinds of information, the following text styles are used in the Reference Manual.

Functions look like this (charter font).
Variables look like this (courier font).
Parameter look like this (helmet font).
File names look like this (timmons font, bold).
FLAGS look like this (timmons font).

II Data types

Chapter 2 details the different data types provided to the user. These types are defined in the /indep/struct.h file.

The most important type are structures and are defined as below:

struct file_info

{

char *filename;

time_t date;

off_t size;

uid_t user;

gid_t group;

mode_t attrib;

};

This structure is able to store different informations about files such as the filename, the date, the size of the file, the attributes (defined in ./Win32/dirent.h), the user and the group (not used under Win32).
This structure is widely used by the functions which manipulate files.


extern struct clist_window

{

// GtkWidget *widget;

GList *dirlist;

char cur_dir[4*MAXCHARS];

GList *selection;

GList *file_selection;

int copy_cut;

char win_dir[4*MAXCHARS];

} clist_win;

This structure gathers some variables about the right windows of the program. This is the window which contains a directory listing of the local files (computer).
The 'dirlist' field is a Glib linked list of 'file_info' elements. It contains the directory listing of the current working directory.
The 'cur_dir' field maintains the current working directory. This is the directory where transfers take place.
The 'selection' field is equal to NULL if no selection is active, else it contains a list of the files which have been selected by the user. The linked list is composed of 'file_info' elements.
The 'file_selection' field is equal to NULL if no selection is active (for the cut/copy/paste functions), else it contains a list of the files have been selected by the user.
The 'copy_cut' variable defines whether the selected variable will be cutted or copied during the cut/copy/paste process.
At last, the 'win_dir' field contains the path where the executable is located ('C:\\Program Files\\roms\\tilp', depending of the InstallSHield installation procedure).


extern struct ctree_window
{
//GtkWidget *widget;
GList *varlist;
char cur_folder[9];
GList *selection;
} ctree_win;

This structure is similar to the previous one but about the left window of the program. This is the window which contains the directory listing of the remote files (calculator).
The 'varlist' field is a Glib linked list of 'varinfo' elements (see the libTIcalcs doc). It contains the directory listing of the calculator.
The 'cur_folder' field maintains the current working directory in the calculator. This is the directory where transfers take place if the 'local path' mode is active. In 'full path' mode, it is ignored.
The 'selection' field is equal to NULL if no selection is active, else it contains a list of the variabes which have been selected by the user. The linked list is composed of 'varinfo' elements.


extern struct goptions
{
int xsize;
int ysize;
int clist_sort;
int clist_sort_order;
int ctree_sort;
int ctree_sort_order;
int confirm;
int path_mode;
int show;
int file_mode;
int server; //used for tidev but obsolete...
int tidev; // not used any longer...
int plugins_loading;
int screen_format;
int screen_clipping;

struct ticable_param lp;

} options;

This structure contains all informations about the options and the configuration of tilp.
The 'xsize' and 'ysize' fields contains the size of the left window.
The 'clist_sort' is equal to one of the following flags: SORT_BY_NAME, SORT_BY_DATE, SORT_BY_SIZE, SORT_BY_USER, SORT_BY_GROUP or SORT_BY_ATTRB.
The 'clist_sort_order' field is equal either to SORT_DOWN either to SORT_UP.
The 'ctree_sort' is equal to one of the following flags: SORT_BY_NAME, SORT_BY_INFO, SORT_BY_SIZE or SORT_BY_TYPE.
The 'ctree_sort_order' field is equal either to SORT_DOWN either to SORT_UP.
The 'confirm' field is equal to either CONFIRM_YES, either CONFIRM_NO. Used whenever a file have to be replaced or deleted so that a dialog box to be displayed.
The 'path_mode' field is equal to either FULL_PATH either LOCAL_PATH. When the path_mode field is FULL_PATH, the calculator variables are sent with the full path else they are sent in the current folder of the calculator. See the libTIcalcs doc for more informations.
The 'show' field is used by the right window. It allows the display of the hidden files. Can be equal to either SHOW or HIDE.
The 'file_mode' field is equal to either EXTENDED_FORMAT, either NORMAL_FORMAT. See the libTIcalcs doc for more informations.
The 'plugins_loading' field will be widely documented later.
The 'screen_format' field contains the current file image format used for saving the screen dump. Can be one of the following flags: XPM, PCX or JPG. Actually, only the XPM (X pixmap) and the PCX (Paintbrush RLE encoded) format are supported.
The 'screen_clipping' field defines whether the screen dump should be displayed entirely or clipped. Can be one of the following flags: FULL_SCREEN or CLIPPED_SCREEN. See the libTIcalcs doc for more informations.
At last, the structure contains a last field which is also a structure. This structure is defined and explained in the libTIcalcs documentation.


struct screenshot
{
char **pixmap;
byte *bitmap;
struct screen_coord sc;
};

This structure is used by the 'cb_screen_capture' and 'cb_screen_save' functions for handling screen dumps.
The first field is a pointer on an array which will contains the screendump under the pixmap format.
The second one is a pointer on a bitmap array which contains the screen returned by the libTIcables functions.
The third one is a structure which contains the screen coordinates of the screen image (see the libTIcalcs documentation).
Remark: these pointer have NOT to be freed.

III Setting up the tilp core

Chapter 2 guides you through the steps to set up the 'tilp core' on your computer. Detailed operating instructions for the functions are described in Chapter 3.

To set up the tilp core:
1. at first, init your GUI according to your platform.
2. set up the GUI independent functions by filling the 'gui_functions' structure and next, call the 'set_gui_fncts' function.
3. set up the refresh functions by calling 'init_refresh_functions'.
4. at last, call the 'main_init' function for parsing the command line so that the tilp core can retrieve some configuration parameters or simply send files via the command line.

After, you can do what you want in you main program...

Remark: the 'main_init' function does not alter the command line. Specific 'tilp core' command line parameters are interpreted but not removed. This may change later. For the moment, simply ignore them.

IV General functions

Chapter 3 details the software functions that are independent of the GUI.
The flags included in each functions are defined in Appendix ?.

The functions listed below are described in this chapter:

tilp_set_gui_fncts
tilp_main_init

tilp_error

tilp_calc_is_ready
tilp_send_backup
tilp_receive_backup
tilp_id_list
tilp_rom_dump
tilp_rom_version
tilp_send_var
tilp_receive_var
tilp_dirlist
tilp_send_flash_app
tilp_send_flash_os
tilp_screen_capture
tilp_screen_save
tilp_save_config_file
tilp_load_config_file

tilp_probe_calc
tilp_probe_port

tilp_change_drive
tilp_check_access

tilp_read_rc_file
tilp_write_rc_file
tilp_is_rcfile_exist

tilp_clist_selection_destroy
tilp_ctree_selection_destroy


tilp_set_gui_fncts

Description: This functions is used to updating the gui_functions structure of the core. You have to fill you own 'gui_fncts' structure with pointers on your GUI dependant functions.

Syntax: void set_gui_fncts(GUI_FNCTS *gf)

Input parameters: none.

Output Parameters: none.

Return values: const char pointer, to a string.


tilp_main_init

Description: This functions retrieve the working directory, display the version number, parses the config file (if found), scans the command line (and do some actions or storing variables), init the libTicable and the libTIcalc and at last initialize and/or load the plugins.

Syntax: int main_init(int argc, char *argv[], char **arge)

Input parameters: similar to a 'main' function.

Output Parameters: none.

Return values: int, like a 'main' function.


tilp_error

Description: This functions get the error code passed by argument, search it and display the corresponding error message with a dialog box. It returns the error code.
A typical use of this function is something like:
if( (error(link_cable.term_port(options.lp.io_addr, options.lp.device))) )
{
...
}

Syntax: int error(int err_num)

Input parameters: err_num, an error code returned by a libTIcable or libTIcalc function.

Output Parameters: none.

Return values: int, the passed error code which is equal to 0 if no error occured.


tilp_calc_is_ready

Description: This functions checks whether the calc is ready.

Syntax: int cb_calc_is_ready(void)

Input parameters: none.

Output Parameters: none.

Return values: int, 0 if successful.


tilp_send_backup

Description: This functions send a backup to the calculator.

Syntax: int cb_send_backup(char *filename)

Input parameters: filename, a fully qualified name on the TI file backup to send.

Output Parameters: none.

Return values: int, 0 if successful.


tilp_receive_backup

Description: This function try to receive a backup. Once completely received, you have to move or rename the temporary backup file to your backup file. This backup file is located in the platform dependant temporary file and its name is "tilp.backup".

Syntax: int cb_receive_backup(void)

Input parameters: none.

Output Parameters: none.

Return values: 0 if successful.


tilp_id_list

Description: This function retrieve the ID list of the calculator (only for FLASH calculator whose the OS have been upgraded). The result is displayed in a dialog box.

Syntax: int cb_id_list(void)

Input parameters: none.

Output Parameters: none.

Return values: int, 0 if successful.


tilp_rom_dump

Description: this function try to obtain a ROM dump of the calculator. For TI92/92+, FARGO must be installed on the calculator.

Syntax: int cb_rom_dump(void)

Input parameters: none.

Output Parameters: none.

Return values: 0 if successful.


tilp_rom_version

Description: this function try to obtain the version number of the ROM. The result is displayed in a dialog box.

Syntax: int cb_rom_version(void)

Input parameters: none.

Output Parameters: none.

Return values: 0 if successful.

tilp_send_var

Description: this function send the variables have been selected by the user in the right window. The selection is in the 'clist_win.selection' variable. The function automatically manages the transfer of one or more files (single or group files) and displays a status box for showing the progress status.

Syntax: int cb_send_var(void)

Input parameters: none.

Output Parameters: none.

Return values: 0 if successful.


tilp_receive_var

Description: this function receives the variables which have been selected by the user in the left window. The selection is in the 'ctree_win.selection' variable. The function automatically manages the transfer of one or more files and displays a status box for showing the progress status. If there is a unique file, it is saved directly with this form 'varname.type', if there are more than one variable, it is saved in the temporary file 'tilp.PAK'. You have to rename or move to a group file name via a file selection dialog box for instance.

Syntax: int cb_receive_var(int *to_save)

Input parameters: none.

Output Parameters: to_save, if different of 0 then a valid group file has been received.

Return values: 0 if successful.


tilp_dirlist

Description: this function does a directory listing of the calculator. It fills the 'ctree_win.varlist' variable with a list (not a tree even if...) of the calculator variables.

Syntax: int cb_dirlist(void)

Input parameters: none.

Output Parameters: none.

Return values: 0 if successful.

Doc stops here...


tilp_send_flash_app

Description: this function does a directory listing of the calculator. It fills the 'ctree_win.varlist' variable with a list (not a tree even if...) of the calculator variables.

Syntax: int cb_dirlist(void)

Input parameters: none.

Output Parameters: none.

Return values: 0 if successful.


V Link cables functions

Chapter 4 details the software functions that are specific to link cable.

The functions listed below are described in this chapter:

init_port
open_port
put
get
close_port
term_port
probe_port
check_port

All functions described below returns an error code which can have different origins. It could be a timeout error, a byte error on the device, an error during the opening of a device or for obtaining some I/O permissions. You can get the corresponding error message with the get_cable_error function.


init_port

Description: this functions must be called prior to any of the following functions for initializing some internal variables and configuring ports or devices.

Syntax: int init_port(unsigned int io_addr, char *device)

Input parameters:
- io_addr, used by parallel, serial and Black TIGL cable. This is the base address of the I/O port where the cable is plugged. It must be a valid I/O address (often in the range 0x3ff).
This is also used for choosing the virtual link cable: either the #0 with VLINK0, either the #1 with VLINK1. By convention, the #0 is used by ab emulator for instance and the #1 is used by a linking software.
- device, used by the Grey/Gray TIGL cable.
Under Linux, this string contains the name of the character device where the cable is plugged in. Example: "/dev/ttyS0" ... "/dev/ttyS3".
Under Windows, this string contains the name of the COM port. Example: "COM1" ... "COM4".

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.


open_port

Description: this functions must be called prior to any transfers for initializing some things and flushing some buffers.

Syntax: int open_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.

put

Description: this functions send a byte (unsigned char) to the link cable.

Syntax: int put(byte data)

Input parameters: data, the byte to transmit on the link cable.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.

get

Description: this functions waits a byte (unsigned char) from the link cable.

Syntax: int get(byte *data)

Input parameters: none.

Output Parameters: data, the byte received from the link cable.

Return values: an error code which can be turned into a string with the get_cable_error function.

close_port

Description: this functions closes the transmission.You should call it whenever a transfer is finished.

Syntax: int close_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.

term_port

Description: this functions closes the port and frees some ressources or devices. It must be called if you quit your program or if you have changed the link cable type before using init_port.

Syntax: int term_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.


probe_port

Description: not useable for the moment.

Syntax: int probe_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.


check_port

Description: this functions can be called to check the status of the link cable: check if a byte has been received and so on. This function is useful to check the receiving buffer without calling the 'get' function which is a blocking function.

Syntax: int check_port(int *status)

Input parameters: none.

Output Parameters: status, the status of the link cable. For the moment, this value can take only 2 values which are STATUS_NONE or STATUS_BYTE_RCV when a byte has been received.

Return values: an error code which can be turned into a string with the get_cable_error function.

VI Appendices

Appendix A: installation instructions.
Appendix B: compiling programs under Linux and/or Windows.
Appendix C: flags for use.
Appendix D: software tools library
Appendix E: Code Index.
Appendix F: Error Messages.
Appendix G: Function Index.

Appendix A: installation instructions

This appendix explains the procedure for adding/using libTIcable library on your system.

Linux procedure: retrieve a tarball of the library source code, make a 'tar xvzf libticable.tar.gz', go into the libTIcable directory. Type 'configure' to check your system and create the Makefile. Next, type 'make' to compile the library and at last, type 'make install' to install it.
By default, the shared object 'libti_cable.so' is placed in the '/usr/lib' directory and necessary links are created.
The headers files are placed in the '/usr/include/ti' directory. For including them, you just have to place a #include <ti/foo.h> on the beginning of your program.

Windows procedure: retrieve a ZIP archive of the library source code and uncompress it in the default folder. Next, place the .DLL file in the same directory than your program (local folder) or place it either in the C:\Windows\System32 directory either in the C:\WinNT\System32 directory according to your OS type.


Appendix B: compiling programs under Linux and/or Windows

Linux procedure: I provide the source of the library. Its installation as described above provides the shared object and necessary headers files. You just have to include the right headers files and compile your program during the linking/last stage with the -lti_cable option on the gcc command line.

Windows procedure: I provide a DLL for use with all versions of Windows and for the Microsoft compiler only. If you want use it with a Borland compiler, you have to recompile the library since the calling conventions are not the same (standard call calling convention ("stdcall") for Borland, C calling convention ("cdecl") for Microsoft).
To compile Windows program, to link together with the appropriate DLL, perform the following steps:
1. a .lib file is provided. Include the .lib file as part of your project.
2. include the "cable_interface.h" header files at the top of your test program. This header file include three files. The first, "typedefs.h" contains some type definitions. The second, "cable_defs.h" contains...

Appendix C: flags for use

Flags are grouped according to the function in which they are used. Some flags are used in more than one function, and they are duplicated in each section for clarity. Most flags are input parameters to the functions they are listed under.

NOTE: Always use flags where provided, rather than the value associated with it, since values may change. For example, use LINK_TGL with set_cable rather than 1.


set_timeout

set_delay

set_baudrate

set_cable

init_port

Appendix D: software tools library

Appendix E: Code Index

The libTIcable is a set of 'C' language subroutines designed to handle the different link cable types though a unique set of functions. Below is an alphabetical listing of all libTIcable functions and the name of the C file which contains its programming code.

The functions below are exported functions:

The functions below are internal functions:

Appendix F: Error Messages

All routines in the libTIcable are written as 'C' functions i.e., thery return values. A non zero value signifies an error. Full error messages may be printed using the get_cable_error function. Below is a list of all error messages, the value of each, and an explanation of the error.

L = Linux
W = Windows9x or Windows NT4

Appendix G: Function Index

To do...

---------------------

I hope this documentation to be useful. If you have comments, suggestions, and so on, feel free to mail me.
If you want additional informations, fire me an e-mail...

tilp core, (c) 1999-2000, Romain Liévin
All code is placed under GPL license and libraries under the LGPL license.
tilp core, version 3.46.
Doc version 1.0, 16/10/2000.
This doc has been written with StarOffice 5.1 Personnal Edition for Linux. SGML could be a better choice but I have not enough time to learn it ...