Table of Contents
ULLA (Unified Link Layer API) - access link layer information
#include
<ulla/lu.h>
ullaResultCode_t ullaRequestAttribute(const ullaString_t uqlStatement,
ullaResultId_t *urId, const ullaTime_t validity);
ullaRequestAttribute
can be used to access link layer information in a synchronous way by retrieval
of attribute values. Also, it can be used for configuration purposes if
updating attribute vallues. The query is specified using the UQL (ULLA
Query Language), which full lexical and grammatical specification is described
in uql(2)
. The user of this function is responsible to free the ullaResult(2)
.
The following parameters have to be carefully considered:
- urId
- A handle for the ullaResult returned.
- uql_statement
- For the ullaRequestAttribute
method only the following statements are valid:
select_statement this statement is used to display the attribute values
in the select_clause of the statement.
update_statement this statement will assign new values to the specified
attributes in the set_clause of the statement.
Please find some examples below.
- validity
- The "freshness" of an attribute
value is specified in milliseconds. If it is set to zero, the ULLA Core
returns only fresh attribute values from the Link Layer Adapter (LLA),
or device driver supporting ULLA. If it is non-zero cached attribute values
from the ULLA Storage might be utilized for the ULLA result and the condition
evaluation. This way, the LU (Link User), or user of the function can trade
the time to get all attributes versus the freshness of the data.
On success, the function call returns a handle for the ULLA result
at pre-allocated urId. The return value is ULLA_OK.
On error, the return
value is negative. The list of error codes is
- ULLA_OK
- everything is fine.
- ULLA_NO_MEMORY
- ran out of user space or kernel space RAM memory.
- ULLA_INSUFICIENT_MEMORY
- ran out of user space RAM memory.
- ULLA_ERROR_IN_VALUE
- a parameter is syntactically
or semantically incorrect.
- ULLA_ERROR_FAULT
- general error.
- ULLA_SEGMENTATION_FAULT
- ULLA Core implementation error.
- ULLA_CORE_NOT_PRESENT
- the ULLA Core kernel
module cannot be loaded.
- ULLA_BUG
- ULLA Core implementation bug.
Some
examples for valid UQL-statements are given below:
- What's the maximum bitrate
I can expect from my network adapters?
In the query all Links have to be considered, which are in a connected
state. The ullaResult returned will just have a single attribute value,
which is the maximum of all available rxBandwidth values:
"SELECT MAX(rxBandwidth) FROM ullaLink WHERE state = 3;"
- What's the current
signal strength of all wireless adapters having
- a Signal to Noise and
Interference Ratio (SNIR) above -70dBm?
This query uses a technology specific attribute, the SNIR. It is meaningful
only the IEEE 802.11 Links (e.g. GSM Links might be characterized by the
Bit Error Rate (BER) rather than the SNIR). In order to access attributes
from two different tables, so-called "joined queries" are utilized.
"SELECT ullaLink.signalStrength FROM ullaLink, p80211Link WHERE p80211Link.SNIR
< -70;"
- Set's set a new RTS/CTS threshold for the Link to my Access Point!
The Ready-To-Send / Clear-to-Send (RTS/CTS) threshold is a technology specific
parameter for IEEE 802.11 Links. Links are uniquely identified by their
local L2 (Link Layer Adress). For IEEE 802.11 Links this maps to a Medium
Access Control (MAC) address. The update_statement can be used to specify
the new attribute values.
"UPDATE ullaLink, p80211Link SET p80211Link.rtsCtsThreshold = 512, ullaLink.localL2Address
= 00:11:22:33:44:55;"
ullaReflection(1)
, ullaAttribute(1)
, ullaCommand(1)
, ullaSample(1)
, ullaNotification(1)
, ullaTools(1)
ulla(2)
, uql(2)
, ullaResult(2)
,
ullaTuple(2)
, ullaRequestReflection(2)
, ullaRequestAttribute(2)
, ullaRequestCommand(2)
,
ullaRequestNotification(2)
, ullaRequestSample(2)
, ullaRequestLock(2)
,
ullaGetCoreDescriptor(2)
RWTH contribution to the GOLLUM
project (http://www.ist-gollum.org). Compliant with ULLA C-API Version 1.0 (http://ulla.sourceforge.net).
This man page was written by Marten Bandholz (mba@mobnets.rwth-aachen.de).
Table of Contents