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


void OSLinkReset (void);

Resets the link interface.

OSLinkReset resets the link interface. It also resets all link variables and performs OSLinkClose.

short OSWriteLinkBlock (const char *buffer, unsigned short num);

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.

unsigned short OSReadLinkBlock (char *buffer, unsigned short num);

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.

void OSLinkOpen (void);

Opens low-level link communication.

OSLinkOpen clears both transmit and receive queues, then set a flag which tells that the communication is opened.

void OSLinkClose (void);

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.

unsigned short OSLinkTxQueueInquire (void);

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.

short OSLinkTxQueueActive (void);

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.

void reset_link (void);

Resets the link interface.

reset_link is an alias (known from DoorsOS) for the function OSLinkReset.

short transmit (const char *buffer, unsigned short num);

Inserts bytes into the link transmit buffer.

transmit is an alias (known from DoorsOS) for the function OSWriteLinkBlock.

unsigned short receive (char *buffer, unsigned short num);

Reads bytes from the link receive buffer.

receive is an alias (known from DoorsOS) for the function OSReadLinkBlock.

void flush_link (void);

Flushes link buffers.

flush_link is an alias (known from DoorsOS) for the function OSLinkOpen.

unsigned short tx_free(void);

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.

short OSCheckSilentLink (void);

Checks the link state.

OSCheckSilentLink returns an integer which determines the link state. The meaning of returned value is:

0None (the link is silent)
1A variable header or extended header is received
2A direct command, a screen dump, a request with size or a request is in progress
3The 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).

void OSLinkCmd (short NormalState);

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").

unsigned short LIO_SendData (const void *src, unsigned long size);

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).

unsigned short LIO_RecvData (void *dest, unsigned long size, unsigned long WaitDelay);

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).

unsigned short sendcalc (const char *SymName, short allowSysVars, unsigned char DevType, unsigned char *compat);

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.

void getcalc (const char *SymName);

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


enum Bool

Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};

type size_t

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;

const NULL

NULL is a null-pointer value, defined as (void *) 0.

type LIO_CTX

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):

0Expression
4List
6Matrix
10Data
11Text
12String
13GDB variable
14Geometry figure
16Picture
17Picture (???)
18TI-Basic program
19TI-Basic function
20Geometry macro
21In Link protocol, cause execution of assembly block
25Directory list (used recursively, unless VarType 26 follows)
26List the folder table entries
27List contents of a given folder (VarType 26 should follow)
28Other (OTH) file
29Backup file
31Folder entry symbol in group files
32Used for getting a certificate
33ASM program
35Used for installing a product code
37Used for installing a certificate

Return to the main index