The <link.h> header file
This header file contains the following functions:
flush_link getcalc LIO_Get
LIO_GetMultiple LIO_Receive LIO_RecvData
LIO_Send LIO_SendData LIO_SendProduct
OSCheckSilentLink OSLinkClose OSLinkCmd
OSLinkOpen OSLinkReset OSLinkTxQueueActive
OSLinkTxQueueInquire OSReadLinkBlock OSWriteLinkBlock
receive reset_link sendcalc
transmit tx_free
and the following constants and predefined types:
Bool LIO_CTX NULL
size_t
NOTE: Some functions from this header file are straightforward and quite simple for use, but
some of them require a good knowledge of TI communication protocols (much better than my
knowledge about it, so don't ask me about details).
Functions
Resets the link interface.
OSLinkReset resets the link interface. It also resets all link variables and
performs OSLinkClose.
Inserts bytes into the link transmit buffer.
OSWriteLinkBlock inserts num bytes from buffer into the link transmit buffer.
Returns 0 if the operation was sucessful, else returns a non-zero value. num must be
in the range 1-128. An error occurs if num is out of range or if there is not enough
room in the transmit buffer to insert num bytes.
NOTE: This function is a low-level function. See also LIO_SendData
for a higher-level variant of this function.
Reads bytes from the link receive buffer.
OSReadLinkBlock reads at most num bytes into buffer from the link receive
buffer. Returns the number of bytes read.
NOTE: This function is a low-level function. See also LIO_RecvData
for a higher-level variant of this function.
Opens low-level link communication.
OSLinkOpen clears both transmit and receive queues, then set a flag which tells that the
communication is opened.
Closes a low-level link communication.
OSLinkClose waits until eventual bytes waiting in transmit queue are sent out, then clears
both transmit and receive queues, and clear a flag which tells that the communication
is opened.
Determines the number of free bytes in the transmit buffer.
OSLinkTxQueueInquire returns the number of free bytes in the link transmit buffer. Note that
this number may change in a time without any obvious actions, because the link communication
is interrupt driven.
Determines whether the transmit queue is active.
OSLinkTxQueueActive returns TRUE if the transmit queue is active,
else returns FALSE. This function checks bit b1 in I/O port 0x60000C
(interrupt on transmit buffer empty).
NOTE: In previous releases of TIGCCLIB (prior to 2.0) the information about this function
was wrong: function OSLinkTxQueueInquire performs
what was described as the job of this function.
Resets the link interface.
reset_link is an alias (known from DoorsOS) for the function OSLinkReset.
Inserts bytes into the link transmit buffer.
transmit is an alias (known from DoorsOS) for the function
OSWriteLinkBlock.
Reads bytes from the link receive buffer.
receive is an alias (known from DoorsOS) for the function
OSReadLinkBlock.
Flushes link buffers.
flush_link is an alias (known from DoorsOS) for the function
OSLinkOpen.
Determines the number of free bytes in the transmit buffer.
tx_free is an alias (known from DoorsOS) for the function
OSLinkTxQueueInquire.
NOTE: In previous releases of TIGCCLIB (prior to 2.0) this function was wrongly aliased
from OSLinkTxQueueActive instead of
OSLinkTxQueueInquire. This is a bug in DoorsOS which
was reflected here.
Checks the link state.
OSCheckSilentLink returns an integer which determines the link state. The meaning of returned
value is:
0 | None (the link is silent) |
1 | A variable header or extended header is received |
2 | A direct command, a screen dump, a request with size or a request is in progress |
3 | The link is ready |
This function is called from high-level keyboard reading functions like
kbhit and ngetchx, and if it returns
non-zero, OSLinkCmd is called to process the received packet (as the
link is interrupt-driven, a packet may be received asynchronously, without the request from
the program itself). So, TIOS can receive variables from the link whenever the program is
waiting for a keypress (used mainly when the calculator is in the Home Screen).
Process the command received through the link port.
OSLinkCmd should to be called after OSCheckSilentLink if the
result returned from it is non-zero (this means that there is a packet received from the link
port, which waits to be processed). This function handles link commands when the calculator
is in the Home Screen for example (link commands are stored in packets). Parameter
NormalState should to be set to TRUE if
the calculator is in a "normal receiving state", i.e. if the current application is "Home
Screen", if the screen is not splitted, and if there is no any event-driven "applets" installed
using EV_captureEvents (see
events.html for more info). This parameter helps TIOS to conclude
which link commands should be processed, and which commands should be rejected (for example,
the calculator can not receive variables if it is not in a "normal receiving state").
Sends data through the link interface.
LIO_SendData sends size bytes from the address src through the link interface.
This function calls repeatedly OSWriteLinkBlock function
as many times as necessary to send all of data. Returns zero if the operation was successful,
else returns a non-zero value (this value describes the type of the error, but I am not sure
about the concrete meaning of particular values).
Receives data from the link interface.
LIO_RecvData reads size bytes through the link interface, and stores received bytes
at the address dest. This functions calls repeatedly OSReadLinkBlock function
as many times as necessary to receive wanted amount of data. Parameter WaitDelay is
the maximal allowed waiting time: if no data is received during WaitDelay timer ticks
(one timer tick is 1/20 seconds by default), the reading fails. When WaitDelay is set
to zero, this means "waiting forever". Anyway, this operation may be interrupted by pressing ON
key. LIO_RecvData returns zero if the operation was successful, else returns a non-zero value
(this value describes the type of the error, but I am not sure about the concrete meaning of
particular values).
NOTE: This functions registers LIO_TIMER for measuring
the time. See OSRegisterTimer for more info.
unsigned short LIO_Send (LIO_CTX *file, unsigned char DevType);
Sends a file through the link interface.
LIO_Send is a high-level function which sends a file (a variable, a screen dump file, etc.)
described by the LIO_CTX structure pointed to by file through
the link interface. However, this function is not so easy for usage, because you need to fill
the file context structure pointed to by file manually before using this function. If
you want just to send a variable through the link interface, function sendcalc
is much easier to use. The advantage of this routine is greater generality in comparing to
sendcalc (for example, it allows transfer even between incompatible TI
models, if properly used; sorry, I don't know too much about it).
Parameter DevType determines the device type (this information is stored in the header
of each packet during the communication). It is a collection of flags. Bit b7 is 0 during
transfer from a computer to a calculator and 1 during transfer from a calculator to a computer
or another calculator. Bits b6 and b5 are reserved (keep them to 0). Bit b4 is 1 if a device
is a "special" device, whatever it means (so far, I know that this bit is set if a device is
TI-89 or CBL). Bits b3-b0 determine the calculator type (so far, I know the following meanings:
0010 for TI-82, 0011 for TI83, 0101 for TI85, 1000 for TI-89 or TI-92 Plus, and 1001 for TI-92).
So, DevType should to be 0x98 for sending from TI-89 or 0x88 for sending from TI-92 Plus.
LIO_Send returns zero if the operation was successful, else returns a non-zero value
(this value describes the type of the error, but I am not sure about the concrete meaning of
particular values).
unsigned short LIO_Receive (LIO_CTX, unsigned char DevType, short skipmuch);
Receives a file from the link interface.
LIO_Receive is a high-level function which receives a file (a variable for example) through
the link interface and fills the LIO_CTX structure pointed to by file
accordingly. However, this function is not so easy for usage, because you need to interpret
the file context structure pointed to by file manually after using this function, which
is not a trivial task. If you want just to receive a variable through the link interface,
function getcalc is much easier to use. The advantage of this routine is
greater generality in comparing to getcalc (for example, it allows
transfer even between incompatible TI models, if properly used; sorry, I don't know too much
about it).
Parameter DevType determines the device type (see LIO_Send for
the explanation about its meaning). It seems that it is possible to set DevType to zero
(it probably means "receive from anything"). Parameter skipmuch is an unknown Boolean parameter
(when it is non-zero, a lot of code in this function is skipped over, but I don't know what
it means). LIO_Receive returns zero if the operation was successful, else returns a non-zero
value (this value describes the type of the error, but I am not sure about the concrete meaning
of particular values).
unsigned short LIO_Get (LIO_CTX *file);
Gets a CBL file from the link interface.
LIO_Get is a high-level function which receives a CBL (Calculator-Based Laboratory) file through the link interface and fills
LIO_CTX structure pointed to by file accordingly (note that I don't
know much more about it). LIO_Get returns zero if the operation was successful, else returns a
non-zero value (this value describes the type of the error, but I am not sure about the concrete
meaning of particular values).
short LIO_GetMultiple (LIO_CTX *file);
Gets a multiple (???) from the link interface.
Yet another unclear high-level link routine. It is called often as a subroutine in other
high-level linking routines. In fact, it just performs
LIO_Receive (file, 0, 0);
but returns a different result. If LIO_Receive returns 0,
LIO_GetMultiple returns -1. If LIO_Receive returns 0xFFFF,
LIO_GetMultiple returns 0. Else, LIO_GetMultiple returns the same value returned from
LIO_Receive. Don't ask me what it means. Any additional
info is welcomed.
unsigned short LIO_SendProduct (LIO_CTX *file, unsigned short DevType);
Sends a product code through the link interface.
LIO_SendProduct is a high-level function which sends a Product Code through the link interface.
What exactly will be sent is described in LIO_CTX structure pointed to by
file. Parameter DevType determines the device type (see LIO_Send for
the explanation about its meaning). This routine is called from the VAR_LINK menu.
Returns zero if the operation was successful, else returns a non-zero
value (this value describes the type of the error, but I am not sure about the concrete meaning
of particular values).
Sends a variable (or program) through the link interface.
sendcalc sends a variable (or program) through the link interface (this is exactly what
TI-Basic command SendCalc does). SymName is a pointer to the variable name.
allowSysVars is a Boolean parameter. If it is TRUE, transfer of
a system variable will be allowed, and if it is FALSE, such transfer will
be rejected. DevType determines the device type (see LIO_Send for
the explanation about its meaning). If Compat is not a NULL pointer,
sendcalc also stores in a byte variable pointed to by compat compatibility information
about the variable which will be transfered (see info about SYM_ENTRY
structure in vat.h header file for more info about compatibility flags).
Note that SymName is not an ordinary C string. Instead, it is zero-started zero-terminated
string, and SymName points to the TERMINATING byte of it (many TIOS functions for
manipulating with TIOS variables uses such strings). See SymFind and
other functions from vat.h header file for more info about symbol names).
Macro constructor $ (also defined in vat.h)
may be useful for constructing such names. For example, to send a variable called "example" from
one TI-89 unit to another, use the following command:
sendcalc ($(example), FALSE, 0x98, NULL);
Replace 0x98 with 0x89 to simulate TI-Basic SendChat command instead of SendCalc. See also
cmd_sendcalc and cmd_sendchat
functions from bascmd.h header file.
sendcalc returns zero if the operation was successful, else returns a non-zero
value (this value describes the type of the error, but I am not sure about the concrete meaning
of particular values). This function also may throw an error in a case of various fatal errors,
so error traping (using functions from error.h header file) is
recommended.
Receives a variable (or program) from the link interface.
getcalc receives a variable (or program) from the link interface (this is exactly what
TI-Basic command GetCalc does). SymName is a pointer to the variable name.
Note that SymName is not an ordinary C string. Instead, it is zero-started zero-terminated
string, and SymName points to the TERMINATING byte of it (many TIOS functions for
manipulating with TIOS variables uses such strings). See SymFind and
other functions from vat.h header file for more info about symbol names).
Macro constructor $ (also defined in vat.h)
may be useful for constructing such names.
NOTE: getcalc enters a loop which will not end until the data is received. The only method
to break such loop (if no data is received) is pressing ON key.
Constants and predefined types
Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};
size_t is a type proposed in ANSI C for defining size of strings and
memory blocks. It is defined here as
typedef unsigned long size_t;
NULL is a null-pointer value, defined as (void *) 0.
LIO_CTX is a file context structure used in some high-level link commands. Some fields of this
structure is not so clear for me. However, in many applications all fields need not to be set
properly, so limited usage of this structure is possible. This structure is defined as
typedef struct
{
unsigned short hVar; // File handle (or 0 if no handles associated)
union
{
const void *pVar; // Pointer to the file, used only if hVar is 0
struct
{
unsigned short FindFlags;
unsigned short NameSym;
} DirVars; // Used only when hVar is non-zero
} extra;
const char *VarName; // Pointer to the var name (ordinary C string)
unsigned short VarSize; // Size of the variable
unsigned short Index; // Only for CBL access - data sent as float array
unsigned short Unknown; // Sent after index
unsigned char VarType; // See below
unsigned char VarCompat; // See info about SYM_ENTRY in vat.h header file
} LIO_CTX;
Field VarType may contain the following values (I don't know much more than I
wrote in this table, so don't ask me about details):
0 | Expression |
4 | List |
6 | Matrix |
10 | Data |
11 | Text |
12 | String |
13 | GDB variable |
14 | Geometry figure |
16 | Picture |
17 | Picture (???) |
18 | TI-Basic program |
19 | TI-Basic function |
20 | Geometry macro |
21 | In Link protocol, cause execution of assembly block |
25 | Directory list (used recursively, unless VarType 26 follows) |
26 | List the folder table entries |
27 | List contents of a given folder (VarType 26 should follow) |
28 | Other (OTH) file |
29 | Backup file |
31 | Folder entry symbol in group files |
32 | Used for getting a certificate |
33 | ASM program |
35 | Used for installing a product code |
37 | Used for installing a certificate |