lua_functions.h File Reference

Detailed Description

References for all of the lua functions.

Note that these are represented in a "C-like" state so that they can be processed by doxygen! However, all function names, return values, and parameters listed here are how they are when called inside lua!

Go to the source code of this file.

Functions
void	wlua_sleep (uint32_t ms)
	Puts the core to sleep for X amount of milliseconds.
uint32_t	wlua_get_random_seed ()
	Gets a random 32 bit number to seed lua's random functions.
int	wlua_ffopen (char *filename, char *access_mods)
	Opens a file from the pathname.
int	wlua_ffclose (int fd)
	Closes a file from a file descriptor.
char *	wlua_ffread (int fd, uint32_t len)
	Reads an arbitrary amount of text upto len bytes from the file.
char *	wlua_ffgets (int fd, uint32_t len)
	Reads a string upto len bytes from the file.
int	wlua_ffwrites (int fd, char *in)
	Writes a string to a file.
int	wlua_ffseek (int fd, long pos)
	Sets the file read/write pointer.
int	wlua_fftell (int fd)
	Gets the current file read/write pointer.
int	wlua_ffunlink (char *filename)
	Deletes a file or directory.
int	wlua_ffstat (char *filename)
	Checks file size and/or existence.
int	wlua_send_file_raw (int fd)
	Sends a file's raw ascii contents over USB.
int	wlua_ffmkdir (char *dirname)
	Creates a new blank directory.
int	wlua_ffopendir (char *dirname)
	Opens a directory for reading it's files.
int	wlua_ffclosedir (int dd)
	Closes a directory.
char *	wlua_ffreaddir (int dd)
	Reads through all files in a directory.
int	wlua_usb_send_ascii_string (char *in)
	Send a full ascii string over usb.
int	wlua_usb_send_key (char *key, char *mods)
	Sends a key and modifiers.
void	wlua_usb_start_defaults ()
	Starts the USB using default values.
void	wlua_usb_start_custom (char lang_0, char lang_1, char manufacturer_string[32], char product_string[32], char serial_string[32], uint16_t vid, uint16_t pid)
	Starts the USB using custom values.
int	wlua_usb_start_pubdisk (uint32_t sector_size, uint32_t sector_count, bool is_writable)
	Enables the fake disk to exposed via USB.
void	wlua_usb_enable_sd_passthrough (bool is_writable)
	Enables direct SD passthrough over USB. Note that this will expose ALL contents, including the payload script.
void	wlua_usb_send_reset_report ()
	Sends a full NULL keyboard report.

Function Documentation

wlua_ffclose()

int wlua_ffclose

(

int

fd

)

Closes a file from a file descriptor.

Parameters

fd	File descriptor for an open file.

Returns

0 on success, -1 on failure.

wlua_ffclosedir()

int wlua_ffclosedir

(

int

dd

)

Closes a directory.

Parameters

dd	Directory descriptor of an open directory.

Returns

0 on success, -1 on failure.

wlua_ffgets()

char * wlua_ffgets	(	int	fd,
		uint32_t	len )

Reads a string upto len bytes from the file.

Parameters

fd	File descriptor for an open file that can be read.
len	Max amount of bytes to be read from the file. Note that if len > the file size it will just read till end of file or full string has been found.

Note that this function works based on the internal file position similar to the POSIX standard functions. To see or change the file pointer see wlua_fftell() and wlua_ffseek().

This function is almost identical to wlua_ffread() but instead reads up to either a '\n' or '\0'.

Returns

The read text or -1 on error.

wlua_ffmkdir()

int wlua_ffmkdir

(

char *

dirname

)

Creates a new blank directory.

Parameters

*dirname

Name for the new directory.

Returns

0 on success, -1 on failure.

wlua_ffopen()

int wlua_ffopen	(	char *	filename,
		char *	access_mods )

Opens a file from the pathname.

Parameters

*filename	Absolute pathname for the file. For instance for a file in the root directory you'd just do "/file.txt" or "file.txt".
access_mods	Access modifiers for the file.

The access modifiers for opening files is as follows:

• 'r' = Read.
• 'w' = Write.
• '+' = Read & Write.
• 'a' = Append.
• 'x' = Create new file if not already open.

These can be combined in several ways, ie. "r+x", "+x", "ax", etc.

Note write & append cannot be used at the same time! Note this file returns a file descriptor (noted as 'fd' throughout the docs) which corresponds to the file internally. You should hold onto this file descriptor because it's the only thing that allows you to close the file or do operations on it.

Returns

-1 if the file does not exist or cannot be created. The fd for the file is returned if it exists or can be created.

wlua_ffopendir()

int wlua_ffopendir

(

char *

dirname

)

Opens a directory for reading it's files.

Parameters

*dirname

Name of the directory to open.

Note that this returns a directory descriptor, or 'dd', to close and do directory operations. This is the same as a file descriptor but for directories.

This function can also be used to check for the existence of a directory since if it does not exist it will return -1.

Returns

The directory descriptor, 'dd', or -1 on failure.

wlua_ffread()

char * wlua_ffread	(	int	fd,
		uint32_t	len )

Reads an arbitrary amount of text upto len bytes from the file.

Parameters

fd	File descriptor for an open file that can be read.
len	Max amount of bytes to be read from the file. Note that if len > the file size it will just read till end of file.

Note that this function works based on the internal file position similar to the POSIX standard functions. To see or change the file pointer see wlua_fftell() and wlua_ffseek().

Returns

The read text or -1 on error.

wlua_ffreaddir()

char * wlua_ffreaddir

(

int

dd

)

Reads through all files in a directory.

Parameters

dd	Directory descriptor of an open directory.

This function loops through every object in a directory. Each call will iterate one object (either file or directory) through the directory. When all objects have been enumerated in the directory it will first return either -1 or a blank string and then start back at the first object.

Returns

Filename/pathname for whatever file/directory found. -1 or a blank string at end of list.

wlua_ffseek()

int wlua_ffseek	(	int	fd,
		long	pos )

Sets the file read/write pointer.

Parameters

fd	File descriptor for an open file.
pos	Position to change. Note that if you input a negative number the file pointer will go backwards until it reaches zero. If the input is greater than the size then it will go to the end of the file.

Returns

0 on success, -1 on failure.

wlua_ffstat()

int wlua_ffstat

(

char *

filename

)

Checks file size and/or existence.

Parameters

*filename

File to be checked.

Returns

Either returns the file's size (anything >= 0), or -1 if the file does not exist.

wlua_fftell()

int wlua_fftell

(

int

fd

)

Gets the current file read/write pointer.

Parameters

fd	File descriptor for an open file.

Returns

The current read/write pointer position, or -1 on failure.

wlua_ffunlink()

int wlua_ffunlink

(

char *

filename

)

Deletes a file or directory.

Parameters

*filename

File or directory to be deleted.

Note that it's typically not possible to delete an opened file, therefore ensure that the file is closed before trying to delete it. It's also not possible to delete a directory if it still has files in it.

Returns

0 on success, -1 on failure.

wlua_ffwrites()

int wlua_ffwrites	(	int	fd,
		char *	in )

Writes a string to a file.

Parameters

fd	File descriptor for an open file that can be written to.
in	Input string. Must be null terminated (should automatically happen in lua).

This file will either append or override the current text in the file based on the access modifiers when the file was opened.

Note that this function works based on the internal file position similar to the POSIX standard functions. To see or change the file pointer see wlua_fftell() and wlua_ffseek().

Returns

The number of bytes written or -1 on error.

wlua_get_random_seed()

uint32_t wlua_get_random_seed

(

)

Gets a random 32 bit number to seed lua's random functions.

Use this in tandem with math.randomseed to setup random number generation.

Returns

Random 32 bit number.

wlua_send_file_raw()

int wlua_send_file_raw

(

int

fd

)

Sends a file's raw ascii contents over USB.

Parameters

fd	File descriptor for an open file that can be read.

This will send the entire file from the current read/write pointer is. Therefore, you may need to adjust or reset the file pointer accordingly to send the whole or parts of the file.

Note that it will automatically include proper capitalization modifiers.

Returns

0 on success, -1 on failure.

wlua_sleep()

void wlua_sleep

(

uint32_t

ms

)

Puts the core to sleep for X amount of milliseconds.

Parameters

ms	Milliseconds to sleep for.

Note that this function only puts the core that lua is running on to sleep and will not sleep the other core, allowing USB functions to continue like normal.

wlua_usb_enable_sd_passthrough()

void wlua_usb_enable_sd_passthrough

(

bool

is_writable

)

Enables direct SD passthrough over USB. Note that this will expose ALL contents, including the payload script.

Parameters

is_writable

Determines whether or not the drive is read-only or not. Setting this to false makes it ready-only and vice versa.

Note that making the SD passthrough read-only does not make the entire SD card read-only allowing application code to still make changes.

wlua_usb_send_ascii_string()

int wlua_usb_send_ascii_string

(

char *

in

)

Send a full ascii string over usb.

Parameters

*in	Null-terminated ascii string.

Note that this will automatically take care of capitalization and the user does not need to supply modifiers. Also treats newlines or carriage returns as the ENTER key.

Returns

0 on success, -1 on failure.

wlua_usb_send_key()

int wlua_usb_send_key	(	char *	key,
		char *	mods )

Sends a key and modifiers.

Parameters

*key	Either single key or special key (ie. ENTER).
*mods	Modifiers to be applied. See below.

All standard single character ascii keys can be used (capatilization is ignored).

"Special" keys that can be used:

• F1-24
• ENTER
• ESCAPE
• BACKSPACE
• TAB
• CAPSLOCK
• NUMLOCK
• END
• DOWNARROW
• PAGEDN
• LEFTARROW
• RIGHTARROW
• HOME
• UPARROW
• PAGEUP
• INSERT
• DELETE
• LCTRL
• LSHIFT
• LALT
• LWIN
• RCTRL
• RSHIFT
• RALT
• RWIN

Modifiers list:

• LALT
• LWIN
• LCTRL
• LSHIFT
• RALT
• RWIN
• RCTRL
• RSHIFT

Modifiers can be used in tandem by putting a '+' in between, ie. "LSHIFT+LALT".

Returns

0 on success, -1 on failure

wlua_usb_start_custom()

void wlua_usb_start_custom	(	char	lang_0,
		char	lang_1,
		char	manufacturer_string[32],
		char	product_string[32],
		char	serial_string[32],
		uint16_t	vid,
		uint16_t	pid )

Starts the USB using custom values.

Parameters

lang_0	First byte of the langcode.
lang_1	Second byte of the langcode.
manufacturer_string	Manufacturer string, must be no more than 32 bytes in length.
product_string	Product string, must be no more than 32 bytes in length.
serial_string	Serial string, must be no more than 32 bytes in length.
vid	2 byte vendor id. Hexadecimal format, ie. 0x2020.
pid	2 byte product id. Hexadecimal format, ie. 0x2020.

Note that if any of the provided values are invalid then they revert to the defaults. For default see wlua_usb_start_defaults()

wlua_usb_start_defaults()

void wlua_usb_start_defaults

(

)

Starts the USB using default values.

The default values are:

• Lang Code: [ 0x04, 0x09] (English)
• Manufacturer String: "vllabs"
• Product String: "'whiskers'"
• Serial String: blank or the vll_wsk_0xxx serial string on the device.
• VID: 0xcafe
• PID: 0x0400

wlua_usb_start_pubdisk()

int wlua_usb_start_pubdisk	(	uint32_t	sector_size,
		uint32_t	sector_count,
		bool	is_writable )

Enables the fake disk to exposed via USB.

Parameters

sector_size	Size of each sector/block of the fake disk. Typically the user should just leave this to 512.
sector_count	Amount of sectors. To set the fake disk to a certain volume size (say 8 gb) you'd need to divide the total size in bytes by the sector_size to get this value.
is_writable	Determines whether or not the drive is read-only or not. Setting this to false makes it ready-only and vice versa.

Note: the minimum size a disk can be is 8kb.

Please see the 'Advanced Usage' page to learn more how to use this feature!

Returns

0 on success, -1 on failure.