Force Command API Functions

fc_tputc - write single character to terminal

API_ID: 0x0

Signature: void fc_tputc(int c)

Output a single character to the ANSI soft terminal. See section ANSI Terminal for details on how terminal interprets characters.

• int c - character to display - byte value in LSB

fc_tputs - write string to terminal

API_ID: 0x1

Signature void fc_tputs(const char* str)

Output the sequence of characters in the null terminated c-string 'str'. See section ANSI Terminal for details on how terminal interprets characters.

• const char* str - address of 0 terminated byte sequence to display

fc_getstr - read string from terminal input

API_ID: 0x2

Signature void fc_getstr(char* var, int limit, int backspace)

Read text input from user. The cursor appears at the current screen location.

• char* var - the buffer to receive user input into. If index 0 of the buffer is not 0, then the buffer is displayed for editing.
• int limit - the maximum length of the buffer var
• int backspace - if 0, the left arrow moves without erasing. if 1, left arrow acts as backspace.

fc_kscan - scan keyboard for keypress

API_ID: 0x3

Signature unsigned int fc_kscan(unsigned int mode)

Read the keyboard (or joystick) in the given mode. Returns the key that is currently pressed.

• unsigned int mode - Same modes as TI BASIC CALL KEY

fc_sams_map_page - set page to address

API_ID: 0x4

Signature: void fc_sams_map_page(int page, int addr)

If sams is available, maps the page number to the given address. When the system starts, pages 0 and 1 are allocated to lower memory expansion and used by Force Command for data and stack. Page 2, is used to hold command line history. When a program is loaded, upper memory expansion is populated with the next 6 available pages. These pages are automatically freed when the program returns back to Force Command, or previous calling executable before it is mapped back in.

• int page - SAMS page number to map into the given address
• int addr - memory address to assign page to. Should be on a 4K boundary between and including 0xA000 and 0xF000

fc_sams_alloc_pages - reserve a set of pages

API_ID: 0x5

Signature: int fc_sams_alloc_pages(int count)

Return the base page number for the set of allocated pages.

• int count - number of pages to allocate

fc_sams_free_pages - release a set of pages

API_ID: 0x6

Signature: int fc_sams_free_pages(int count)

Free pages returning the number of the first free page.

• int count - number of pages to free

fc_sys_info - retrieve DSR related data pointers

API_ID: 0x7

Signature: void fc_sys_info(struct SystemInformation* info)

Populate information into SystemInformation structure. Providing:

• dsrList - array of device names and their DSR address. List ends if name is empty.
• currentDsr - pointer to DSR entry for device of current working directory.
• currentPath - null terminated string of shell current working directory.
• vdp_io_buf - VDP address dsr routines use to buffer data.

fc_display_info - fetch display characteristics from system

API_ID: 0x8

Signature: void fc_display_info(struct DisplayInformation * info)

Reads from the system the details about the display.

types:

DisplayInformation:

• int isPal - 1 == console is a 50hz system, 0 == console is 60hz wrt VDP interrupt.
• int vdp_type - indicate VDP processor type:
  • 0xF18A == Matthew Hagerty's F18A,
  • 0x9958 == Yamaha Y9958,
  • 0x9938 == Yamaha Y9938,
  • 0x9918 == TMS9918, TMS9918A, TMS9928, TMS9929
• int displayWidth - 40 or 80 column display
• int displayHeight - 24, 26, or 30 row display
• int imageAddr - vdp address of pattern image table
• int patternAddr - vdp address of pattern definition table
• int colorAddr - vdp address of color attribute table
• int spritePatternAddr - vdp address of sprite pattern definition table

fc_sams_info - retrieve SAMS page allocation details

API_ID: 0x9

Signature: void fc_sams_info(struct SamsInformation* info)

• next_page - number of next page that would be allocated.
• total_pages - number of 4K pages the SAMS board supports.

fc_vars_get - get environment variable

API_ID: 0xA

Signature: char* fc_vars_get(char* name)

Returns the address of the value of an environment variable. Becomes invalid if variable is changed.

fc_vars_set - set environment variable

API_ID: 0xB

Signature: void fc_vars_set(char* name, char* value)

Changes the value of an environment variable. Value of 0 unsets the variable.

fc_exec - run a Force Command commandline

API_ID: 0xC

Signature: int fc_exec(char* command)

Run the command as though it was typed in the ForceCommand shell. If command runs another executable then SAMS is required, the current executable will be paged out, and new pages will be assigned to the executable. When it exits, the calling executable will be paged back in.

fc_dsr_ea5load - run an EA5 Program Image

API_ID: 0xD

Signature: unsigned int fc_dsr_ea5load(struct DeviceServiceRoutine * dsr, const char *fname)

Load and run an Editor Assembler Option 5 style machine code binary PROGRAM image file series. If the file exists, the VDP and other memory configurations will be set as close to Editor Assembler as possible (except the lower memory expansion utils are not loaded, unless part of the PROGRAM series). If there is any failure to load the sequence of files, the console is reset. Return from the EA5 PROGRAM will reset the console.

fc_dsr_open - open a file

API_ID: 0xE

Signature: unsigned int fc_dsr_open(struct DeviceServiceRoutine* dsr, struct PAB* pab, const char* fname, int flags, int reclen)

Perform a file open operation for record type files. Peripheral Access Block (PAB) struct will be initialized for the file and operation. Does not scan DSR lists, but uses the specified DSR. Use fc_find_dsr to search the list if necessary.

flags should be the bitwise combination ( or them together ) of DSR_TYPE_* constants representing the open mode, and record type for the file.

fc_dsr_close - close a file

API_ID: 0xF

Signature: unsigned int fc_dsr_close(struct DeviceServiceRoutine* dsr, struct PAB* pab)

Perform a close operation using the state from the previously used PAB.

fc_dsr_read - read a file record

API_ID: 0x10

Signature: unsigned int fc_dsr_read(struct DeviceServiceRoutine* dsr, struct PAB* pab, int recordNumber)

Perform a record read operation. Data will be at the VDP RAM address of pab.VDPBuffer. Number of bytes read is in pab.CharCount.

fc_dsr_write - write a file record

API_ID: 0x11

Signature: unsigned int fc_dsr_write(struct DeviceServiceRoutine* dsr, struct PAB* pab, unsigned char* record, int reclen)

Perform a record write operation. record is the data to write. reclen specifies how many bytes to write. record is not a null terminated C string.

fc_dsr_status - get file status

API_ID: 0x12

Signature: unsigned int fc_dsr_status(struct DeviceServiceRoutine* dsr, struct PAB* pab)

Perform a status operation on the file. Useful for end of file checking. If pab is initialized manually, can be used to check on files that have not been opened yet.

fc_dsr_reset - seek to record in file

API_ID: 0x13

Signature: unsigned int fc_dsr_reset(struct DeviceServiceRoutine* dsr, struct PAB* pab, int record)

Perform a reset operation on an open file. Reset of a DSR_TYPE_SEQUENTIAL or DSR_TYPE_VARIABLE file will reset to record 0.

fc_dsr_delete - delete a file

API_ID: 0x14

Signature: unsigned int fc_dsr_delete(struct DeviceServiceRoutine* dsr, struct PAB* pab)

Remove a file from disk. Name must be set in pab manually.

fc_dsr_catalog - visit each entry in a catalog file

API_ID: 0x15

Signature: unsigned int fc_dsr_catalog(struct DeviceServiceRoutine* dsr, const char* pathname, vol_entry_cb vol_cb, dir_entry_cb dir_cb)

Read a device CATALOG file, calling vol_cb on record 0 with the volume name and other volume details. For each file in the CATALOG dir_cb will be called with the individual file details.

fc_path2iocode - get lvl2 IO subprogram and drive unit number

API_ID: 0x16

Signature: unsigned int fc_path2iocode(const char* currentPath)

Level2 IO routines require knowledge of what subprogram names in the BASIC subprogram DSR list to use. Different controllers use different names, but follow a pattern. Given a file path, this returns the iocode to pass to the fc_lvl2_* routines. This iocode embeds the mask for the subprogram names, and the unit number for the device.

fc_lvl2_input - direct file block input

API_ID: 0x17

Signature: unsigned int fc_lvl2_input(int crubase, unsigned int iocode, char *filename, unsigned int blockcount, struct AddInfo *addInfoPtr)

Perform LVL2 IO direct input from file. This is used to read blocks of a file, or the filesystem entry details (block 0). Blocks are 256 bytes. Use fc_path2iocode to get value for iocode parameter.

To read the file metadata, initialize AddInfo.first_sector with 0, and read a blockcount of 1. AddInfo.flags will be populated with the file type information, along with other fields in AddInfo.

To read file content, initialize AddInfo.first_sector to block number (1 through total number of blocks) and AddInfo.buffer to VDP address that read blocks should be stored in.

fc_lvl2_output - direct file block output

API_ID: 0x18

Signature: unsigned int fc_lvl2_output(int crubase, unsigned int iocode, char *filename, unsigned int blockcount, struct AddInfo *addInfoPtr)

Perform LVL2 IO direct output to a file. This is used to write blocks of a file, or create a file from filesystem entry details with block 0.

Blocks are written by taking the data in VDP at AddInfo.buffer. They are written to block specified by AddInfo.first_sector.

fc_lvl2_protect - protect or unprotect a file

API_ID: 0x19

Signature: unsigned int fc_lvl2_protect(int crubase, unsigned int iocode, char *filename, int protect)

set protect flag on a file.

fc_lvl2_rename - rename a file

API_ID: 0x1A

Signature: unsigned int fc_lvl2_rename(int crubase, unsigned int iocode, char *oldname, char *newname)

Rename a file. oldname and newname are limited to 10 characters.

fc_lvl2_setdir - set device directory for subsequent lvl2 operation

API_ID: 0x1B

Signature: unsigned int fc_lvl2_setdir(int crubase, unsigned int iocode, char* path)

When performing lvl2 IO operations that use only the 10 character filename and unit number embedded as iocode, you must set the directory for the device before performing the operation.

path should include the full device path for the directory, such as: TIPI.GAMES.ADVENTURES.

fc_lvl2_mkdir - create a new directory

API_ID: 0x1C

Signature: unsigned int fc_lvl2_mkdir(int crubase, unsigned int iocode, char *dirname)

Create a new directory. dirname is the 10 character name of the directory to create.

fc_lvl2_rmdir - remove a directory

API_ID: 0x1D

Signature: unsigned int fc_lvl2_rmdir(int crubase, unsigned int iocode, char *dirname)

Remove a directory. dirname is the 10 character name of the directory to remove.

fc_lvl2_rendir - rename a directory

API_ID: 0x1E

Signature: unsigned int fc_lvl2_rendir(int crubase, unsigned int iocode, char *oldname, char *newname)

Rename a directory, from oldname to newname. oldname and newname are 10 character directory names.

fc_tcp_connect - open a tcp client socket

API_ID: 0x1F

Signature: unsigned int fc_tcp_connect(unsigned int socketId, unsigned char* hostname, unsigned char* port)

Use TIPI to open a TCP socket connection to the specified server hostname and port. Asssociate the open socket to the given socketId. Returns the message result documented by TIPI TCP socket API.

fc_tcp_close - close a tcp socket

API_ID: 0x20

Signature: unsigned int fc_tcp_close(unsigned int socketId)

Use TIPI to close an open TCP socket. socketId is the handle number used when the socket was opened.

fc_tcp_read_socket - read from a tcp socket

API_ID: 0x21

Signature: int fc_tcp_read_socket(unsigned int socketId, unsigned char* buf, int bufsize)

Use TIPI to read data from a socket. Reading is non-blocking. Returns the number of characters read. This will be 0 if no data was available. Data will be stored in buf, upto the limit specified by bufsize.

fc_tcp_send_chars - write to a tcp socket

API_ID: 0x22

Signature: int fc_tcp_send_chars(unsigned int socketId, unsigned char* buf, int size)

Use TIPI to write data to a socket. Returns TIPI messaging result. May fail if remote has closed the connection. Remote closure is only detectable by performing this write, until it fails.

fc_tipi_on - map in TIPI rom and IO

API_ID: 0x23

Signature: void fc_tipi_on()

Bank in the TIPI DSR ROM and memory mapped IO ports.

fc_tipi_off - unmap TIPI rom and IO

API_ID: 0x24

Signature: void fc_tipi_off()

Remove the TIPI DSR ROM and memory mapped IO ports from the active memory map.

fc_tipi_sendmsg - send low level message to TIPI

API_ID: 0x25

Signature: void fc_tipi_sendmsg(unsigned int len, const unsigned char *buf)

Publish a message to TIPI. See the TIPI Wiki for documentation on raw extensions.

fc_tipi_recvmsg - receive low level message from TIPI

API_ID: 0x26

Signature: void fc_tipi_recvmsg(unsigned int *len, unsigned char *buf)

Read a message from TIPI.

fc_datetime -

API_ID: 0x27

Signature: void fc_datetime(struct DateTime* datetime)

Read real-time clock data into the fields of a DateTime structure. Which source RTC is controlled by the CLOCK environment variable.

Fields of struct DateTime:

• unsigned char dayOfWeek : 1 - 7
• unsigned int year : yyyy
• unsigned char month : 1 - 12
• unsigned char day : 1 - 31
• unsigned char hours : 0 - 23
• unsigned char minutes : 0 - 59
• unsigned char seconds : 0 - 59
• unsigned char pm : 0 indicates AM, 1 indicates PM

fc_find_dsr - return the device service routine info for a given device name. Search starts at given crubase.

API_ID: 0x28

Signature: struct DeviceServiceRoutine* fc_find_dsr(char* devicename, int crubase)

Use crubase of 0 to search all drives like a traditional DSRLNK. Use a specific crubase to restrict search to DSRs of a single expansion board.

fc_parse_path_parm - set canonical file name and dsr for given path name.

API_ID: 0x29

Signature: void fc_parse_path_param(char* str_in, struct DeviceServiceRoutine** dsr, char* buffer, int requirements)

Given str_in update the address of a DSR and normalize the path name into buffer. requirements can be PR_OPTIONAL, PR_REQUIRED, or PR_WILDCARD.

• PR_OPTIONAL - file specified by str_in does not have to exist already.
• PR_REQUIRED - str_in must specify an existing file.
• PR_WILDCARD - interpret * wildcards, returning parent directory into buffer. Wildcard pattern is staged for use with fc_dsr_catalog.

fc_uint2str - convert unsigned integer to null terminated string

API_ID: 0x2A

Signature: char* fc_uint2str(unsigned int)

Returns the string form of an integer in a static buffer. Subsequent calls will overwrite the string.

fc_uint2hex - convert unsigned integer to a hexidecimal string representation

API_ID: 0x2B

Signature: char* fc_uint2hex(unsigned int)

Returns the hex string form of an integer in a static buffer. Subsequent calls will overwrite the string.

fc_atoi - convert a decimal string to an integer

API_ID: 0x2C

Signature: int fc_atoi(char* decimal)

Returns the integer form of the number represented by the decimal string.

fc_htoi - convert a hexidecial string to an integer

API_ID: 0x2D

Signature: int fc_htoi(char* hexstring)

Returns the integer form of the number represented by the hexidecimal string.

fc_strcpy - c string copy

API_ID: 0x2E

Signature: char* fc_strcpy(char* d, char* s)

Copy string from s (source) into d (destination). Returns d. -- Prefer fc_strncpy to prevent buffer overruns

fc_strncpy - c string copy with limit

API_ID: 0x2F

Signature: char* fc_strncpy(char* d, char* s, int limit)

Copy a string from s to d, returning d. Copy upto the limit number of characters.

fc_strcat - concatinate a c string to the end of an existing string

API_ID: 0x30

Signature: char* fc_strcat(char* d, char* s)

Copy a string s to end of string d. Return d.

fc_strtok - take a token from the front of a c string

API_ID: 0x31

Signature: char* fc_strtok(char* str, int delim)

Tokenize a string. Uses a common buffer for return value. If str is set, find occurance of delim character in the string, and set it to the null terminater, returning str. The location of delim is stored internally for subsequent calls.

If str is 0, then the previous location of delim is continued from. The new value of delim is searched for, the string is terminated and returned.

If delim is not found, the entire string is returned.

This modifies in place the original input string.

fc_strtokpeek - peek at a token from the front of a c string

API_ID: 0x32

Signature: char* fc_strtokpeek(char* str, int delim)

Return the str, or if str is 0, the continuation point from a previous call to strtok. Does not modify the string in place, but instead copies the found token to a common buffer before returning it. Does not advance the cursor for subsequent calls.

fc_strlen - return length of a c string

API_ID: 0x33

Signature: int fc_strlen(char* str)

Return the length of the null terminated c string str

fc_strcmp - compare 2 c strings lexographically

API_ID: 0x34

Signature: int fc_strcmp(char* a, char* b)

Lexigraphical comparison of string a to b. Returns -1 if a is before b, 1 if a is after b, 0 if a and b are equal.

fc_strcmpi - case insensitive string comparison

API_ID: 0x35

Signature: int fc_strcmpi(char* a, char* b)

Dictionary order comparison of string a to b. Returns -1 if a is before b, 1 if a is after b, 0 if a and b are equal. Like lexigraphical order, but ignoring uppercase vs lowercase differences.

fc_indexof - find index of character in string

API_ID: 0x36

Signature: int fc_indexof(char* str, int c)

Find index in str of character c starting from the beginning of str. Returns -1 if c is not found.

fc_lindexof - find last index of character in string

API_ID: 0x37

Signature: int fc_lindexof(char* str, int c, int start)

Find index of c in str, starting at offset start, searching backwards toward offset 0. Returns -1 if c is not found.

fc_str_startswith - test if string starts with a given prefix

API_ID: 0x38

Signature: int fc_str_startswith(const char* str, const char* prefix)

Return 1 if str begins with prefix, otherwise return 0.

fc_str_endswith - test if string ends with a given suffix

API_ID: 0x39

Signature: int fc_str_endswith(const char* str, const char* suffix)

Return 1 if the end of str is equal to the suffix, otherwise return 0.

fc_basictocstr - convert a BASIC format string to a c string

API_ID: 0x3A

Signature: int fc_basictocstr(const char* str, char* buf)

Copy a BASIC string, to a null terminated c string. A BASIC string is not null terminated, and the first byte is the length of the string, such as { 0x04, 'f', 'o', 'u', 'r' }

fc_strset - set a block of memory to a given character

API_ID: 0x3B

Signature: void fc_strset(char* buffer, int value, int limit)

Set memory at buffer to buffer + limit, such that all bytes have the given value.

fc_next_token - cursor approach to tokenizing string

API_ID: 0x3C

Signature: char* fc_next_token(char* dst, char* str, int delim)

Copies a token from str upto occurance of delim into dst. Returns address in str after occurance of delim. The return pointer is typically passed in as str on subsequent calls to get the next token. Returns 0 if no the end of str was reached.

fc_beep - play classic TI-99/4A affirmative tone

API_ID: 0x3D

Signature: void fc_beep()

Play typical affirmative sound, such as that used in a TI BASIC prompt.

fc_honk - play classic TI-99/4A failure tone

API_ID: 0x3E

Signature: void fc_honk()

Play typical negative tone, such as used in TI BASIC for bad input.

fc_set_identify_hook - set callback for terminal identify request

API_ID: 0x3F

Signature: void fc_set_identify_hook(identify_callback cb)

Set address of function the ANSI terminal emulator can use to respond to a network server terminal identify request. Useful only if implmenting a TCP network terminal client, such as telnet. THe Terminal screen normally only responds to commands by displaying data to the screen in a controlled way. However the identify command is not meant to be shown to the user, but instead sent back by the client to the network server. If you are implementing something like telnet you can register a function that receives a flag containing identify response information. If the identify request was a CSI 'c' command, flag will be 0. If the identify request was a CSI 'n' command, the flag will have the high bit set, along with the current cursor coordinates packed in.

fc_vdp_setchar -

API_ID: 0x40

Signature: void fc_vdp_setchar(int addr, int ch)

Write ch to VDP address addr.

fc_vdp_get_cursor_addr -

API_ID: 0x41

Signature: unsigned int fc_vdp_get_cursor_addr()

Return VDP address of terminal cursor.

fc_ui_drop_down -

API_ID: 0x42

Signature: void fc_ui_drop_down(int lines)

Draw a ANSI character bordered window shade type drop down for prompting or modal dialog style text UI such as used by the built-in ED command when saving files.

fc_ui_gotoxy -

API_ID: 0x43

Signature: void fc_ui_gotoxy(int x, int y)

Move terminal cursor to x, y coordinate. Coordinates are 1 based.

fc_speech_reset -

API_ID: 0x44

Signature: void fc_speech_reset()

Send reset command to speech synthesizer.

fc_detect_speech -

API_ID: 0x45

Signature: int fc_detect_speech()

Return 0 if no speech synthesizer is present. Return 1 if it is present.

fc_say_vocab -

API_ID: 0x46

Signature: void fc_say_vocab(int speechAddr)

Issue a command to the speech synthesizer to say vocabular word at speech address speechAddr. Constants for all the built-in vocabulary word speech addresses are in vocab.h

fc_say_data -

API_ID: 0x47

Signature: void fc_say_data(const char* addr, int len)

Given a buffer in CPU ram of LPC code, stream it to the speech synthesizer. This is a blocking operation, that waits until the last segment of the speech data has been accepted into the synthesizer's fifo.

fc_speech_start -

API_ID: 0x48

Signature: void fc_speech_start(struct LpcPlaybackCtx* ctx)

Given a LpcPlaybackCtx with a pointer to the LPC data, and the remaining byte count to send, send the first command code and intial fifo (16 bytes) worth of LPC data to the synthesizer. Use fc_speech_continue with the same LpcPlaybackCtx to continue. Modifies ctx to track remaining data to send.

fc_speech_continue -

API_ID: 0x49

Signature: void fc_speech_continue(struct LpcPlaybackCtx* ctx)

Checks the speech synthesizer status if there is room in the fifo to accept more data. If so, send upto 8 more bytes of data to the fifo. Modifies ctx to track remaining data to send. Call this function repeatedly until ctx->remaining is 0 which indicates all data has been sent to the synthesizer.

fc_speech_wait -

API_ID: 0x4A

Signature: void fc_speech_wait()

Block in a loop checking the speech synthsizer status until it indicates the LPC fifo is empty and the synthesizer is no longer speaking.

fc_tipi_mouse -

API_ID: 0x4B

Signature: void fc_tipi_mouse(struct MouseData8 mouseData)

Read mouse data from TIPI device. Does not manipulate mouse pointer or any display attributes. Works in any video mode. MouseData pointerx and pointery fields are not set.

Fills in MouseData fields:

• char mx - delta for movement on x-axis
• char my - delta for movement on y-axis
• char buttons - byte holding which buttons were pressed on last read.
• int pointerx - used by fc_mouse_enable, fc_mouse_move, and fc_mouse_disable functions

Constants for buttons:

• MB_LEFT - 0x01
• MB_RIGHT - 0x02
• MB_MID - 0x04

fc_tipi_mouse_move -

API_ID: 0x4C

Signature: void fc_tipi_mouse_move(struct MouseData* mouseData)

Note: Requires ForceCommand to be on F18A in 80x30 column mode.

Reads mouse data from TIPI and updates location of sprite #1 and #2 as a 2 color mouse pointer. Mouse pointer will not show up unless fc_tipi_mouse_enable has been called.

fc_tipi_mouse_enable -

API_ID: 0x4D

Signature: void fc_tipi_mouse_enable(struct MouseData* mouseData)

Note: Requires ForceCommand to be on F18A in 80x30 column mode.

Setup initial values of mouse pointer location and sprite patterns for sprite #1 and #2, and enable the sprites. Initial location is at the center of the screen.

fc_tipi_mouse_disable -

API_ID: 0x4E

Signature: void fc_tipi_mouse_disable()

Note: Requires ForceCommand to be on F18A in 80x30 column mode.

Hide sprites disabling the mouse pointer.

fc_tls_connect -

API_ID: 0x4F

Signature: unsigned int fc_tls_connect(unsigned int socketId, unsigned char* hostname, unsigned char* port)

Use TIPI to open a TLS socket connection to the specified server hostname and port. Asssociate the open socket to the given socketId. Returns the message result documented by TIPI TCP socket API.

fc_tls_close -

API_ID: 0x50

Signature: unsigned int fc_tls_close(unsigned int socketId)

Use TIPI to close an open TLS socket. socketId is the handle number used when the socket was opened.

fc_tls_read_socket -

API_ID: 0x51

Signature: int fc_tls_read_socket(unsigned int socketId, unsigned char* buf, int bufsize)

Use TIPI to read data from a TLS socket. Reading is non-blocking. Returns the number of characters read. This will be 0 if no data was available. Data will be stored in buf, upto the limit specified by bufsize.

fc_tls_send_chars -

API_ID: 0x52

Signature: int fc_tls_send_chars(unsigned int socketId, unsigned char* buf, int size)

Use TIPI to write data to a TLS socket. Returns TIPI messaging result. May fail if remote has closed the connection. Remote closure is only detectable by performing this write, until it fails.

fc_init_socket_buffer -

API_ID: 0x53

Signature: void fc_init_socket_buffer(struct SocketBuffer* socket_buf, int tls, unsigned int socketId)

Initialize a socket buffer for use with fc_readline and fc_readstream. Sets if the socket is TLS and what TIPI socketId was used when connecting.

The SocketBuffer is a stateful context for taking upto 256 byte single line data or fixed size buffer data that doesn't necessary fit nicely into the data volume transfered when reading from the socket. It has a 256 byte line buffer, and 256 byte raw byte buffer, as well as book-keeping attributes.

fc_readline -

API_ID: 0x54

Signature: char* fc_readline(struct SocketBuffer* socket_buf)

Read a line from a TCP or TLS socket using buffered IO. Can only handle lines upto 255 characters long. socket_buf must have been initialized once for use with the desired socket. Reads from the socket when necessary to refill the buffer if a line terminator is not reached. Line terminator is 0x10 or 0x13, 0x10.

fc_readstream -

API_ID: 0x55

Signature: int fc_readstream(struct SocketBuffer* socket_buf, char* block, int limit)

Read upto limit characters into block, a buffer you provide, from the socket_buf. Will try to refill socket_buf if limit is not reached. Returns the actual number of bytes copied into block.

fc_list_init -

API_ID: 0x56

Signature: void fc_list_init(struct List* list, void* addr, void* ceiling)

Initialize a List sructure to reference a bound chunk of CPU memory. The List struct has the following fields:

• char* addr - low address of list data
• char* end - address of free space at end of list
• char* ceiling - top address that cannot be exceeded.

fc_list_push -

API_ID: 0x57

Signature: void fc_list_push(struct List* list, char* buffer, int length)

Copy the data in buffer to a new entry at the front of the list, typically for use of the list as a LIFO. If there is not room in the list, without exceeding ceiling, then first-in items are dropped to make room. So this is silently lossy.

fc_list_pop -

API_ID: 0x58

Signature: void fc_list_pop(struct List* list, char* buffer, int limit)

Copy the data from the front of the list to buffer, upto limit. Item is then removed from the list.

fc_list_get -

API_ID: 0x59

Signature: struct ListEntry* fc_list_get(struct List* list, int index)

Get pointer to ListEntry at given index. Index is 0 based. Data remains in list.

ListEntry has 2 fields:

• int length - number of bytes in data
• char* data - address of actual data

fc_textcolor -

API_ID: 0x5A

Signature: unsigned int fc_textcolor(unsigned int color)

Directly set the foreground color of the screen for future writes. If in 40 column mode, changes the color for all characters on the screen. Returns the old value of the foreground color.

There are constants for all 16 colors in fc_api.h starting with COLOR_, such as COLOR_CYAN.

fc_bgcolor -

API_ID: 0x5B

Signature: unsigned int fc_bgcolor(unsigned int color)

Directly set the background color for text of future writes. If in 40 column mode, sets the background color of all tiles immediately. Returns the old value of the background color.

fc_bordercolor -

API_ID: 0x5C

Signature: unsigned int fc_bordercolor(unsigned int color)

Directly set the border color that surrounds the screen's writeable tile area. Does not set the text attribute color. Returns 0.