Table of Contents

Name

ULLA (Unified Link Layer API) - access link layer information

Synopsis

#include <ulla/lu.h>

ullaResultCode_t ullaRequestNotification(ullaNotificationRequestId_t *rnId, const ullaString_t uqlQuery, const ullaTime_t validity, const unsigned int count);

ullaResultCode_t ullaReceiveNotification(const ullaNotificationRequestId_t rnId, ullaResultId_t *urId);

ullaResultCode_t ullaCancelNotification(const ullaNotificationRequestId_t rnId);

ullaResultCode_t ullaNotificationRequestStatus(const ullaNotificationRequestId_t rnId);

Description

ullaRequestNotification is used to ask ULLA for a notification upon fulfillment of a condition on link layer data. It can be cancled later by using the ullaCancelNotification method. The condition of the notification is specified with the query using an UQL statement according to uql(2) .

The validity constraint is specified in milliseconds. If it is set to zero, the ULLA Core will refresh any attribute value in the full UQL statement from the LLA (Link Layer Adapter), alias driver, every time it evaluates the condition. If it is non-zero the cached attribute values from the ULLA Storage might be utilized for the ULLA result or the condition. This way, the user of the function can trade the time to get all attributes for the evaluation versus the freshness of the data.

The evaluation of the condition is done upon incoming attribute updates from the LLA to the ULLA Core. The user of this function has nothing to do for that. It might be that the LLA implementation chooses to update an attribute periodically or event based. For instance, the bandwidth of a Link might be updated periodically with some update period whereas the state of a Link is updated only if there is a link state change.

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) .

Parameters

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.
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.

Return Vallue

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_NOTIFICATION_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.

Examples

Some examples for valid UQL-statements are given below:

How-to get a notification when the SNIR drops very low?

In order to register a notification for the event that the Signal-to-Noise and Interference Ratio (SNIR) drops below a threshold the following statement can be used. It is a so-called "joined query" because multiple tables are utilized:
"SELECT ullaLink.signalStrength FROM ullaLink, p80211Link WHERE p80211Link.SNIR < -70;"

See Also

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)

Conforming to

RWTH contribution to the GOLLUM project (http://www.ist-gollum.org). Compliant with ULLA C-API Version 1.0 (http://ulla.sourceforge.net).

Author

This man page was written by Marten Bandholz (mba@mobnets.rwth-aachen.de).

Table of Contents