Table of Contents
ULLA (Unified Link Layer API) - access link layer information
#include
<ulla/lu.h>
ullaResultCode_t ullaRequestSample(ullaSampleRequestId_t *rnId,
const ullaString_t uqlQuery, const ullaTime_t validity, const unsigned
int count, const unsigned int period);
ullaResultCode_t ullaReceiveSample(const
ullaSampleRequestId_t rnId, ullaResultId_t *urId);
ullaResultCode_t ullaCancelSample(const
ullaSampleRequestId_t rnId);
ullaResultCode_t ullaSampleRequestStatus(const
ullaSampleRequestId_t rnId);
ullaRequestSample is used to
ask ULLA for a periodical evaluation of the uql_statement and return the
ullaResult on time. The sampling request can be cancled later by using the
ullaCancelSample method. The uql_statement is an UQL statement according
to uql(2)
.
In order to access the data from the ULLA result, the LU can
utilize the accessor functions. The ULLA result is structured using tuples
and fields ullaResult(2)
, ullaTuple(2)
.
The following parameters
have to be carefully considered:
- rnId
- Request Notification id, which is
a handle for the notification request.
- count
- Specifies how many times the
notification should be fired before it is auto-canceled by the ULLA Core.
- period
- Speficies the time between two consecutive evaluations of the uql_statement.
- urId
- A handle for the ullaResult, which is created when a notification
is fired.
- uqlQuery
- For the ullaRequestNotification method only the following
statement is valid:
select_statement this statement is used to display the attribute values
in the select_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.
- ULLA_ERROR_SAMPLE_REQUEST_CANCELED
- is the return code of the ullaReceiveNotification function if the notification
request was auto-canceled and is no longer valid.
- ULLA_ERROR_INTERRUPTED
- is the return code of the ullaReceiveNotification function if the blocking
call was interrupted due to a signal and can be resumed.
Some examples
for valid UQL-statements are given below:
- How-to trace the signal strength
and the transmission rate of
- a specific Link over time?
In order to receive samples from attributes values using the ullaRequestSample
the following UQL statement can be used: "SELECT signalStrength, rxBitrate
FROM ullaLink WHERE linkId = 2;"
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