Context Functions
-
struct iio_context *iio_create_context(const struct iio_context_params *params, const char *uri)
Create a context from a URI description.
NOTE: The following URIs are supported based on compile time backend support:
Local backend, “local:”
Does not have an address part. For example
”local:”XML backend, “xml:”
Requires a path to the XML file for the address part. For example
”xml:/home/user/file.xml”Network backend, “ip:”
Requires a hostname, IPv4, or IPv6 to connect to a specific running IIO Daemon or no address part for automatic discovery when library is compiled with ZeroConf support. For example
”ip:192.168.2.1”, or “ip:localhost”, or “ip:” or “ip:plutosdr.local”. To support alternative port numbers the standard ip:host:port format is used. A special format is required as defined in RFC2732 for IPv6 literal hostnames, (adding ‘[]’ around the host) to use a ip:[x:x:x:x:x:x:x:x]:port format. Valid examples would be:ip: Any host on default port
ip::40000 Any host on port 40000
ip:analog.local Default port
ip:brain.local:40000 Port 40000
ip:192.168.1.119 Default Port
ip:192.168.1.119:40000 Port 40000
ip:2601:190:400:da:47b3:55ab:3914:bff1 Default Port
ip:[2601:190:400:da:9a90:96ff:feb5:acaa]:40000 Port 40000
ip:fe80::f14d:3728:501e:1f94eth0 Link-local through eth0, default port
ip:[fe80::f14d:3728:501e:1f94eth0]:40000 Link-local through eth0, port 40000
USB backend, “usb:”
When more than one usb device is attached, requires bus, address, and interface parts separated with a dot. For example
”usb:3.32.5”. Where there is only one USB device attached, the shorthand “usb:” can be used.Serial backend, “serial:”
Requires:
a port (/dev/ttyUSB0),
baud_rate (default 115200)
serial port configuration
data bits (5 6 7 8 9)
parity (’n’ none, ‘o’ odd, ‘e’ even, ‘m’ mark, ‘s’ space)
stop bits (1 2)
flow control (’\0’ none, ‘x’ Xon Xoff, ‘r’ RTSCTS, ‘d’ DTRDSR)
For example “serial:/dev/ttyUSB0,115200” or “serial:/dev/ttyUSB0,115200,8n1”
- Parameters:
params – A pointer to a iio_context_params structure that contains context creation information; can be NULL
uri – a URI describing the context location. If NULL, the backend will be created using the URI string present in the IIOD_REMOTE environment variable, or if not set, a local backend is created.
- Returns:
On success, a pointer to a iio_context structure
- Returns:
On failure, a pointer-encoded error is returned
-
void iio_context_destroy(struct iio_context *ctx)
Destroy the given context.
NOTE: After that function, the iio_context pointer shall be invalid.
- Parameters:
ctx – A pointer to an iio_context structure
-
unsigned int iio_context_get_version_major(const struct iio_context *ctx)
Get the major number of the library version.
NOTE: If ctx is non-null, it will return the major version of the remote library, if running remotely.
- Parameters:
ctx – Optional pointer to an iio_context structure
- Returns:
The major number
-
unsigned int iio_context_get_version_minor(const struct iio_context *ctx)
Get the minor number of the library version.
NOTE: If ctx is non-null, it will return the minor version of the remote library, if running remotely.
- Parameters:
ctx – Optional pointer to an iio_context structure
- Returns:
The minor number
-
const char *iio_context_get_version_tag(const struct iio_context *ctx)
Get the git hash string of the library version.
NOTE: If ctx is non-null, it will return the git tag or hash of the remote library, if running remotely.
- Parameters:
ctx – Optional pointer to an iio_context structure
- Returns:
A NULL-terminated string that contains the git tag or hash
-
char *iio_context_get_xml(const struct iio_context *ctx)
Obtain a XML representation of the given context.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
On success, an allocated string. Must be deallocated with free().
- Returns:
On failure, a pointer-encoded error is returned
-
const char *iio_context_get_name(const struct iio_context *ctx)
Get the name of the given context.
NOTE:The returned string will be , or when the context has been created with the local, xml and network backends respectively.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
A pointer to a static NULL-terminated string
-
const char *iio_context_get_description(const struct iio_context *ctx)
Get a description of the given context.
NOTE:The returned string will contain human-readable information about the current context.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
A pointer to a static NULL-terminated string
-
unsigned int iio_context_get_attrs_count(const struct iio_context *ctx)
Get the number of context-specific attributes.
Introduced in version 0.9.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
The number of context-specific attributes
-
const struct iio_attr *iio_context_get_attr(const struct iio_context *ctx, unsigned int index)
Retrieve the context-specific attribute at the given index.
- Parameters:
ctx – A pointer to an iio_context structure
index – The index corresponding to the attribute
- Returns:
On success, a pointer to an iio_attr structure
- Returns:
If the index is out-of-range, NULL is returned
-
const struct iio_attr *iio_context_find_attr(const struct iio_context *ctx, const char *name)
Try to find a context-specific attribute by its name.
- Parameters:
ctx – A pointer to an iio_context structure
name – A NULL-terminated string corresponding to the name of the attribute
- Returns:
On success, a pointer to an iio_attr structure
- Returns:
If the name does not correspond to any known attribute of the given context, NULL is returned.
-
unsigned int iio_context_get_devices_count(const struct iio_context *ctx)
Enumerate the devices found in the given context.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
The number of devices found
-
struct iio_device *iio_context_get_device(const struct iio_context *ctx, unsigned int index)
Get the device present at the given index.
- Parameters:
ctx – A pointer to an iio_context structure
index – The index corresponding to the device
- Returns:
On success, a pointer to an iio_device structure
- Returns:
If the index is invalid, NULL is returned
-
struct iio_device *iio_context_find_device(const struct iio_context *ctx, const char *name)
Try to find a device structure by its ID, label or name.
- Parameters:
ctx – A pointer to an iio_context structure
name – A NULL-terminated string corresponding to the ID, label or name of the device to search for
- Returns:
On success, a pointer to an iio_device structure
- Returns:
If the parameter does not correspond to the ID, label or name of any known device, NULL is returned
-
int iio_context_set_timeout(struct iio_context *ctx, int timeout_ms)
Set a timeout for I/O operations.
- Parameters:
ctx – A pointer to an iio_context structure
timeout_ms – Timeout value in milliseconds:
IIO_TIMEOUT_BACKEND (0): use backend default timeout
IIO_TIMEOUT_INFINITE (-1): no timeout (wait indefinitely)
IIO_TIMEOUT_NONBLOCK (INT_MIN): non-blocking
Positive: timeout after specified milliseconds
Other negative values: returns -EINVAL
- Returns:
On success, 0 is returned
- Returns:
On error, a negative errno code is returned
-
const struct iio_context_params *iio_context_get_params(const struct iio_context *ctx)
Get a pointer to the params structure.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
A pointer to the context’s iio_context_params structure
-
void iio_context_set_data(struct iio_context *ctx, void *data)
Associate a pointer to an iio_context structure.
- Parameters:
ctx – A pointer to an iio_context structure
data – The pointer to be associated
-
void *iio_context_get_data(const struct iio_context *ctx)
Retrieve a previously associated pointer of an iio_context structure.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
The pointer previously associated if present, or NULL
-
int iio_context_ping(struct iio_context *ctx)
Ping the IIO context to check if it is still responsive.
NOTE: This performs a lightweight round-trip operation to verify the connection is still alive. It does not access hardware or change any device state. This operation is only meaningful for remote contexts (network, USB, serial). For local contexts, it always succeeds.
- Parameters:
ctx – A pointer to an iio_context structure
- Returns:
On success, 0 is returned
- Returns:
On error, a negative errno code is returned