class::sys::Link

This class is used to access devices running Stratify OS from a remote platform (desktop/mobile/web).

This class is a wrapper for the Stratify OS serialization protocol which allows complete access to Stratify OS system calls and filesystems.

This class is not available on native Stratify OS applications.

Summary

Link()

~Link()

int chmod(

const arg::SourceFilePath path,
const fs::Permissions & permissions
)

int chown(

const arg::SourceFilePath path,
const arg::OwnerId owner,
const arg::GroupId group
)

int close(

const arg::FileDescriptor fd
)

int closedir(

const arg::LinkDirp dirp
)

int connect(

const arg::SourceFilePath path,
const arg::IsLegacy is_legacy
)

int copy(

const arg::SourceFilePath src,
const arg::DestinationFilePath dest,
const fs::Permissions & permissions,
const arg::IsCopyToDevice to_device,
const ProgressCallback * progress_callback
)

int copy_file_from_device(

const arg::SourceFilePath src,
const arg::DestinationFilePath dest,
const fs::Permissions & permissions,
const ProgressCallback * progress_callback
)

int copy_file_to_device(

const arg::SourceFilePath src,
const arg::DestinationFilePath dest,
const fs::Permissions & permissions,
const ProgressCallback * progress_callback
)

int disconnect()

link_transport_mdriver_t * driver() const

const var::String & error_message() const

int format(

const arg::SourceDirectoryPath path
)

int get_bootloader_attr(

bootloader_attr_t & attr
)

var::Vector< var::String > get_dir_list(

const arg::SourceDirectoryPath directory
)

var::Vector< LinkInfo > get_info_list()

bool get_is_connected() const

int get_is_executing(

const arg::Name & name
)

int get_pid(

const arg::Name & name
)

var::Vector< var::String > get_port_list()

int get_time(

struct tm * gt
)

const LinkInfo & info() const

int install_app(

const arg::SourceFile source,
const arg::DestinationDirectoryPath path,
const arg::DestinationFileName name,
const ProgressCallback * progress_callback
)

int ioctl(

const arg::FileDescriptor fd,
const arg::IoRequest request,
const arg::IoArgument arg
)

bool is_bootloader() const

bool is_connected() const

bool is_connected_and_is_not_bootloader() const

bool is_legacy() const

int kill_pid(

int pid,
int signo
)

int lseek(

const arg::FileDescriptor fd,
const arg::Location offset,
int whence
)

int mkdir(

const arg::DestinationDirectoryPath directory,
const fs::Permissions permissions
)

const var::String & notify_path() const

int open(

const arg::FilePath file,
const fs::OpenFlags & flags,
const fs::Permissions & permissions
)

int opendir(

const arg::SourceDirectoryPath directory
)

const var::String & path() const

int progress() const

int progress_max() const

int read(

const arg::FileDescriptor fd,
const arg::DestinationBuffer buf,
const arg::Size nbyte
)

int read_flash(

int addr,
void * buf,
int nbyte
)

int readdir_r(

const arg::LinkDirp dirp,
struct link_dirent * entry,
struct link_dirent ** result
)

int reconnect(

const arg::RetryCount retries,
const arg::RetryDelay delay
)

int reinit()

int rename(

const arg::SourceFilePath old_path,
const arg::DestinationFilePath new_path
)

int reset()

int reset_bootloader()

int rmdir(

const arg::SourceDirectoryPath directory
)

int run_app(

const arg::SourceFilePath path
)

const var::String & serial_no() const

const var::String & serial_number() const

void set_disconnected()

void set_driver(

arg::ImplicitLinkDriver driver
)

void set_driver_options(

const void * options
)

void set_progress(

int p
)

void set_progress_max(

int p
)

int set_time(

struct tm * gt
)

int stat(

const arg::SourceFilePath path,
struct link_stat & st
)

int symlink(

const arg::SourceFilePath old_path,
const arg::DestinationFilePath new_path
)

const sys::SysInfo & sys_info() const

int unlink(

const arg::SourceFilePath filename
)

int update_binary_install_options(

arg::DestinationFile destination,
const AppfsFileAttributes & attributes
)

int update_os(

const arg::SourceFile image,
const arg::IsVerify is_verify,
const ProgressCallback * progress_callback,
const arg::BootloaderRetryCount bootloader_retry_total
)

int update_os(

const arg::SourceFile image,
const arg::IsVerify is_verify,
arg::ProgressPrinter progress_printer,
const arg::BootloaderRetryCount bootloader_retry_total
)

int write(

const arg::FileDescriptor fd,
const arg::SourceBuffer buf,
const arg::Size nbyte
)

int write_flash(

int addr,
const void * buf,
int nbyte
)

static var::String convert_permissions(

link_mode_t mode
)

enum @16

Members



const arg::SourceFilePath path,
const fs::Permissions & permissions
)

Changes the mode of a file.

Returns

Zero on success.

Ownership is not supported on all filesystems.


const arg::SourceFilePath path,
const arg::OwnerId owner,
const arg::GroupId group
)

Changes the ownership of a file.

Returns

Zero on success.

Ownership is not supported on all filesystems.


const arg::FileDescriptor fd
)

Closes an open file descriptor

Parameters

  • fd File descriptor to close

Returns

Zero on success


const arg::LinkDirp dirp
)

Closes an open directory.


const arg::SourceFilePath path,
const arg::IsLegacy is_legacy
)

Connects to the specified Stratify OS device. After calling this, other applications will not have access to the device.

Parameters

  • path The path to the serial device

  • serial_number The serial number to connect to

  • is_legacy True if connected to older devices


const arg::SourceFilePath src,
const arg::DestinationFilePath dest,
const fs::Permissions & permissions,
const arg::IsCopyToDevice to_device,
const ProgressCallback * progress_callback
)

This copies a file either from the device to the host or from the host to the device depending on the value of toDevice.

Returns

Zero on success


const arg::SourceFilePath src,
const arg::DestinationFilePath dest,
const fs::Permissions & permissions,
const ProgressCallback * progress_callback
)

Copes a file from the target device to the host.

Parameters

  • src Path to the source file on the target device

  • dest Path to the destination file on the host

  • mode Mode for file creation on host

  • update Callback to execute as file is copied

  • context Argument to pass to update callback

Returns

Zero on success


const arg::SourceFilePath src,
const arg::DestinationFilePath dest,
const fs::Permissions & permissions,
const ProgressCallback * progress_callback
)

Copies a file to the target device.

Parameters

  • src Path to the source file.

  • dest Path to the destination file on the target device.

  • mode Mode for file creation on target

  • update Callback to execute as file is copied

  • context Argument to pass to update callback

Returns

Zero on success


This disconnects from the device. After calling this, other applications can access the device.


Returns the driver needed by other API objects.

Other objects need the link driver in order to operate correctly. If the driver is not provided, the program will crash.

Consider the following example:

#include <sapi/sys.hpp>

Link link;

link.connect("path_to_device", "serial_number");

File file(link.driver()); //allows File to open a file on the target using this link driver
File crash_file; //any operations use this will cause the program to crash

Gets the error message if an operation fails.


const arg::SourceDirectoryPath path
)

Formats the filesystem on the device.

Returns

Zero on success


bootloader_attr_t & attr
)


const arg::SourceDirectoryPath directory
)

Loads the entries of a directory.




const arg::Name & name
)

Checks to see if a process called name is running.

Parameters

  • name Name of the application to check

Returns

The pid of the running process or -1 if no processes match the name


const arg::Name & name
)

Gets the PID of the specified application name.

Parameters

  • name The name of the application to find the pid

Returns

The PID or -1 if the application is not currently running



struct tm * gt
)

Reads the time from the device.

Returns

Zero on success



const arg::SourceFile source,
const arg::DestinationDirectoryPath path,
const arg::DestinationFileName name,
const ProgressCallback * progress_callback
)

Installs a binary to the specified location.

Parameters

  • source The source of the binary file

  • dest The location to install the file (directory)

  • update A callback to update the caller on the progress of the install

  • context First argument passed to update

Returns

Zero on success or -1 with error() set to an appropriate message

To install i nthe MCU RAM or flash, use /app as the dest value. The binary will be install in either /app/flash or /app/RAM depending on the binary installation flags.

The application can be installed in an embedded filesystem such as /home but will then need to be installed by target device before it can be executed.


const arg::FileDescriptor fd,
const arg::IoRequest request,
const arg::IoArgument arg
)

Performs an IO control operation on an open file descriptor.

Parameters

  • fd File descriptor (returned from open())

  • request ioctl() request value

  • ctl Pointer to 3rd argument

Returns

Value returned based on request and fd


Checks to see if the target is in = mode.

Returns

Non zero if = mode is active.


Returns true if the device is connected.




int pid,
int signo
)

Sends a signal to the specified process.

Parameters

  • pid Process ID

  • signo Signal number

Returns

Zero on success or less than zero on error


const arg::FileDescriptor fd,
const arg::Location offset,
int whence
)

Performs an lseek fd.

Parameters

  • fd File descriptor from open()

  • offset Offset for seek

  • whence Type of seek

Returns

Zero on success


const arg::DestinationDirectoryPath directory,
const fs::Permissions permissions
)

Creates a directory on the target device.


The path of the currently connected (or last connected) notify device


const arg::FilePath file,
const fs::OpenFlags & flags,
const fs::Permissions & permissions
)

Opens a file (or device such as /dev/adc0) on the target device.

Returns

The file descriptor on success or -1 on failure

The target device has a limit on how many files can be open at a time. It is important that the host close any files that it opens.

File access is more easily performed using fs::File rather than accessing files using this object.

#include <sapi/sys.hpp>

Link link;
link.connect("path_to_serial_port", "serial_number");

File file(link.driver());

if( file.open("/home/hello.txt", File::READ_ONLY) < 0 ){
  printf("Failed to open file on target device\n");
} else {
  file.close();
}

const arg::SourceDirectoryPath directory
)

Opens a directory such that it’s contents can be read with readdir().


The path of the currently connected (or last connected) device


Gets the current progress of an operation. This allows multi-threaded applications to update a progress bar while copying files.


Gets the maximum progress value of the current operation.


const arg::FileDescriptor fd,
const arg::DestinationBuffer buf,
const arg::Size nbyte
)

Reads an open file descriptor.

Parameters

  • fd File descriptor (returned from open)

  • buf Pointer to the destination buffer for the read

  • nbyte Number of bytes to read from the file

Returns

Number of bytes read or less than zero on failure


int addr,
void * buf,
int nbyte
)


const arg::LinkDirp dirp,
struct link_dirent * entry,
struct link_dirent ** result
)

Reads an entry from an open directory.

Returns

The name of the next entry in the directory.


const arg::RetryCount retries,
const arg::RetryDelay delay
)


Reconnects to the last known path and serial number.


const arg::SourceFilePath old_path,
const arg::DestinationFilePath new_path
)

Renames a file.

Parameters

  • old_path Path to the old file (current path) \parm new_path New path where old_path will be

Returns

Zero on success


Resets the device (connection will be terminated).

Returns

Zero on success or less than zero on error


Resets the device and invokes the bootloader.

Returns

Zero on success or less than zero on error

The connection to the device is terminated with this call.


const arg::SourceDirectoryPath directory
)

Removes a directory on the target device.


const arg::SourceFilePath path
)

Funs an application on the target device.

Returns

The PID of the new process or less than zero for an error



Returns the serial number of the last device that was connected (including the currently connected device)

Returns

A string containing the serial number of the last connected (or currently connected) device


Sets the object to a disconnected state without interacting with the hardware.

This can be called if the device was removed without being properly disconnected in software.


arg::ImplicitLinkDriver driver
)

Sets the driver used by this object.

If no driver is set, the default driver (serial port) is used.


const void * options
)

Assigns the driver options to the link driver.


int p
)


int p
)


struct tm * gt
)

This function sets the time on the device.

Returns

Zero on success


const arg::SourceFilePath path,
struct link_stat & st
)

Reads the file statistics on the specified target device file.

Returns

Zero on success with st populated or less than zero on failure


const arg::SourceFilePath old_path,
const arg::DestinationFilePath new_path
)

Creates a symbolic link on the device. Stratify OS does not currently support symbolic links. This function will always return an error.

Symbolic links are not supported on all filesystems.

Returns

Zero on sucess.


Returns a copy of the system info for the connected device.

Each time a device is connected, the system information is loaded. This object keeps a copy.


const arg::SourceFilePath filename
)

Deletes a file on the target device.


arg::DestinationFile destination,
const AppfsFileAttributes & attributes
)

details Updates a binary app with the specified settings.

Parameters

  • file The binary image to modify

  • attributes The attributes to apply

Returns

Zero on success or -1 with error() set to an appropriate message


const arg::SourceFile image,
const arg::IsVerify is_verify,
const ProgressCallback * progress_callback,
const arg::BootloaderRetryCount bootloader_retry_total
)

Updates the operating system.

Parameters

  • path Path to the new binary image on the host.

  • verify true to read back the installation

  • update Callback to execute as update is in progress

  • context Argument to pass to the update callback

Returns

Zero on success

The host must be connected to the target bootloader before calling this method.


const arg::SourceFile image,
const arg::IsVerify is_verify,
arg::ProgressPrinter progress_printer,
const arg::BootloaderRetryCount bootloader_retry_total
)


const arg::FileDescriptor fd,
const arg::SourceBuffer buf,
const arg::Size nbyte
)

Writes an open file descriptor.

Parameters

  • fd File descriptor (returned from open)

  • buf Pointer to the source buffer for the write

  • nbyte Number of bytes to read from the file

Returns

Number of bytes written or less than zero on failure


int addr,
const void * buf,
int nbyte
)


link_mode_t mode
)

Converts the permissions to a string of the format:

-rwxrwxrwx

The first character indicates:

  • - File
  • d Directory
  • c Character file
  • b Block file

The order is other, group, user. If the permission is not available, the character is replace by a “-”.


  • SET Whence value for lseek
  • CURRENT Whence value for lseek
  • END Whence value for lseek

X

Thanks for Coming!

Subscribe to news and updates