Systems
=======

Systems are the abstractions for an operating system, or if you prefer,
an “external world” on which you can open streams, access filesystems,
and so on.

The system object is usable both by the library and the user. One global
object of this kind is the local system, which is the immediately
accessible system, e.g. the win32 interface for Windows, the Linux
system interface for Linux distributions, and so on.

.. type:: tio_system_t

	An object representing a system.

Managing serial connections on a system
---------------------------------------

To open a serial stream on a given system, you can use the following
function:

.. c:function:: int tio_open_serial_stream(tio_system_t *system, \
	tio_stream_t **streamp, char const *name, \
	tio_serial_attrs_t const *attrs)

	Open a serial stream on a system, using the given device name.

Device names can vary depending on the systems: on Microsoft Windows,
it might be simple names such as ``COM4``, where on UNIX-like systems,
it can be full paths to the serial device, e.g. ``/dev/ttyS0``.

For listing the available serial devices, you can use the following
functions:

.. c:function:: int tio_list_serial_ports(tio_system_t *system, \
	tio_iter_t **iterp)

	List serial devices, with just the name.

.. c:function:: int tio_next_serial_port(tio_iter_t *iter, \
	char const **namep)

	Get the next serial port name on the system.

Managing USB devices on a system
--------------------------------

To open a USB stream on a given system, you can use the following
function:

.. c:function:: int tio_open_usb_stream(tio_system_t *system, \
	tio_stream_t **streamp, int bus, int addr)

	Open a USB stream on a system, using the given bus and address numbers.

For listing the available USB devices, you can use the following
functions:

.. c:function:: int tio_list_usb_devices(tio_system_t **system, \
	tio_iter_t **iterp)

	List USB devices, with information represented as a
	:c:type:`tio_usb_device_t` entry. For getting an entry in the
	iterator, use :c:func:`tio_next_usb_device`.

.. c:function:: int tio_next_usb_device(tio_iter_t *iter, \
	tio_usb_device_t * const *devicep)

	Get the next entry of an iterator opened with
	:c:func:`tio_list_usb_devices`.

A USB device is represented by the following type:

.. c:type:: tio_usb_device_t

	A USB device entry, for iterating.

	.. c:member:: int tio_usb_device_bus

		The bus number for the given USB device.

	.. c:member:: int tio_usb_device_address

		The address number on the bus for the given USB device.

	.. c:member:: int tio_usb_device_class

		An integer corresponding to the ``bDeviceClass`` USB property.

	.. c:member:: int tio_usb_device_subclass

		An integer corresponding to the ``bDeviceSubClass`` USB property.

	.. c:member:: int tio_usb_device_protocol

		An integer corresponding to the ``bDeviceProtocol`` USB property.

	.. c:member:: unsigned int tio_usb_device_vendor_id

		An integer corresponding to the ``idVendor`` USB property.

	.. c:member:: unsigned int tio_usb_device_product_id

		An integer corresponding to the ``idProduct`` USB property.