Hi Everyone,
The attached files represent a proposed dbus based API to access the
Linux WiMax stack. This proposal is the result of a number of
discussions over the last few months at OLS and the plumbers
conference.
Overview:
There are two object types used to access the WiMax stack the adapter
and network object.
The adapter (adapter-api.txt) object is created when the hardware
device is discovered in the system. This object is used to control the
state of the adapter and the process of scanning for available
networks.
The network (network-api.txt) object is created when a network is
discovered via the adapter.Scan() method. This object is used to
control the state and report information about available network
connections.
There is one helper agent (agent-api.txt) that is meant to call out to
gather user credentials i.e.(username, password). The current file is
just a placeholder.
Comments and suggestions gratefully accepted.
TIA
--Dirk
Dirk Brandewie
dirk.j.brandewie@xxxxxxxxx
-------------- next part --------------
WiMax D-Bus Adapter API description
***********************************
Copyright (C) 2008 Intel Corporation
Adapter hierarchy
=================
Service org.wimax
Interface org.wimax.Adapter
Object path [variable prefix]/{wmx0,wmx1,...}
Methods dict GetProperties()
Returns all properties for the adapter. See the
properties section for available properties.
Possible Errors: org.wimax.Error.DoesNotExist
org.wimax.Error.InvalidArguments
void SetProperty(string name, variant value)
Changes the value of the specified property. Only
properties that are listed a read-write are changeable.
On success this will emit a PropertyChanged signal.
Possible Errors: org.wimax.Error.DoesNotExist
org.wimax.Error.InvalidArguments
void Scan()
Instruct the adapter to search for available
networks. The signal space searched is
contrained by adapter specific configuration
options.
Possible Errors: TBD
void ScanWide()
Instruct the adapter to search for available
networks. All bands and channels the adapter
is capable of recieving are searched.
Possible Errors: TBD
void ScanCancel()
Cancel any in progress scan operations.
Possible Errors: TBD
void RadioOn()
Enable adapter radio. Convienence method for
SetProperty(Powered, "on")
Possible Errors: TBD
void RadioOff()
Enable adapter radio. Convienence method for
SetProperty(Powered, "off")
Possible Errors: TBD
void Reset()
Reset the adapter.
Possible Errors: TBD
void Unlock(string unlock_code)
Unlock the adapter from binding to a service
providers network.
Possible Errors: TBD
array{object} ListNetworks()
Returns list of discoverd network object paths.
Possible errors: org.wimax.Error.InvalidArguments
org.wimax.Error.Failed
org.wimax.Error.OutOfMemory
void RegisterCredentialAgent(object agent)
This registers the adapter wide agent.
The object path defines the path the of the agent
that will be called to collect user login credentials.
If an application disconnects from the bus all
of its registered agents will be removed.
Possible errors: org.wimax.Error.InvalidArguments
org.wimax.Error.AlreadyExists
void UnregisterCredentialAgent(object agent)
This unregisters the agent that has been previously
registered. The object path parameter must match the
same value that has been used on registration.
Possible errors: org.wimax.Error.DoesNotExist
Signals PropertyChanged(string name, variant value)
This signal indicates a changed value of the given
property.
NetworkFound(string address, dict values)
This signal will be send every time an scan result
has been found by the adapter.
The dictionary can contain bascially the same values
that we be returned by the GetProperties method
from the org.wimax.Network interface.
NetworkDisappeared(string address)
This signal will be sent when a scan operation
completes and a previously discovered network
is no longer available.
Properties string Name [readwrite]
The WiMax friendly name. This value can be
changed and a PropertyChanged signal will be emitted.
boolean Powered [readwrite]
Switch an adapter radio on or off.
array{object} Networks [readonly]
List of network object paths.
string HardwareVersion [readonly]
Version string for the adapter hardware
string SoftwareVersion [readonly]
Version string for the adapter software
string FirmwareVersion [readonly]
Version string for the adapter firmware
string MacAddress [readonly]
The MAC address of the adapter. This string
use colon separated fields to represent the
MAC address i.e. xx:xx:xx:xx:xx:xx
boolean SoftwareRfKillState [readonly]
boolean HardwareRfKillState [readonly]
string LockedNSPInfo [readonly]
String containing the contact information for
the NSP to which the adapter is locked. Only
updated via the Unlock() method or the adapter
configuration interface.
-------------- next part --------------
Wimax D-Bus Credential Agent API description
**********************************
Copyright (C) 2008 Intel Corporation
The agent API provides an interface for the wimax adapter object to
obtain credential/login information from the user.
NOTE This file is a placeholder and will be fleshed out with the
methods required as the usage model of the adapter and network objects
are finalized.
Agent hierarchy
===============
Service org.wimax
Interface org.wimax.Agent
Object path freely definable
Methods void Release()
This method gets called when the service daemon
unregisters the agent. An agent can use it to do
cleanup tasks. There is no need to unregister the
agent, because when this method gets called it has
already been unregistered.
void Cancel()
This method gets called to indicate that the agent
request failed before a reply was returned.
-------------- next part --------------
WiMax D-Bus network API description
**********************************
Copyright (C) 2008 Intel Corporation
Device hierarchy
================
Service org.wimax
Interface org.wimax.Device
Object path [variable prefix]/{wmx0,wmx1,...}/network_XX_XX_XX_XX_XX_XX
Methods dict GetProperties()
Returns all properties for the adapter. See the
properties section for available properties.
Possible Errors: org.wimax.Error.DoesNotExist
org.wimax.Error.InvalidArguments
void SetProperty(string name, variant value)
Changes the value of the specified property. Only
properties that are listed a read-write are changeable.
On success this will emit a PropertyChanged signal.
Possible Errors: org.wimax.Error.DoesNotExist
org.wimax.Error.InvalidArguments
void Connect()
Connect to the network represented by this object
Possible Errors:
void Disconnect()
This method disconnects the network from the NSP
Possible errors: org.wimax.Error.NotConnected
Signals PropertyChanged(string name, variant value)
This signal indicates a changed value of the given
property.
Properties string NspName [readonly]
The Bluetooth remote name. This value can not be
changed. Use the Alias property instead.
string NspRealm [readonly]
uint32 NspId [readonly]
string RoamingMode [readwrite]
string NetworkType [readonly]
The network type represented by this object
available values are home, partner, roaming
partner and unknown.
uint32 CenterFrequency [readonly]
Center frequency of link in KHz
uint32 RSSI
Mean RSSI measured by device. As according to
IEEE 802.16 standard, values are ranging from
0x00 to 0x53, where -123dBm is encoded as 0x00
and -40dBm encoded as 0x53 with 1dB increments.
uint32 CINR [readonly]
Mean CINR measured by device. As according to
IEEE 802.16 standard, values are ranging from
0x00 to 0x3F, where -10dB is encoded as 0x00
and 53dB encoded as 0x3F with 1dB increments.
uint32 txPwr [readonly]
Average transmit power for the last burst
transmitted by the device. Based on IEEE802.16
standard, the values are ranging from 0xxx to
0xFF, where -84dBm is encoded as 0x00 and
43.5dBm is encoded as 0xFF with 0.5dB
increment.
string bsId [readonly]
The base station address of the associated
network. This string use colon separated
fields to represent the base station address
i.e. xx:xx:xx:xx:xx:xx. valid only wile the
adapter is associated with a network.
bool provisioned [readonly]
string NspContactInfoText [readonly]
string NspContactInfoURI [readonly]
boolean Reconnect [readwrite]
Should the network object automatically
attempt to reconnect to the network after
the loss of connection
string ConnectionStatus [readonly]
String describing the current connection state.
boolean Connected [readonly]
Is this device connected to the NSP network.
uint32 ConnectTime [readonly]
object Adapter [readonly]
The object path of the adpater this object is
associated with.
-------------- next part --------------
This file will be used to track open issues for the Linux WiMax DBUS
API. Once an issue is resolved the issue will be moved to the
"Closed" seciton.
Open Issues:
#1. Should the Scan and ScanWide adapter method calls be collapsed
into a single method accepting a single boolean argument
controlling the type of scan proceedure performed.
#2. Should the idea of configured "profiles" be part of the standard
D-Bus API or left to be vendor specific.
#3. Should NspContactInfoText and NspContactInfoURI properties in the
network object remain strings or be some type of structured
information.
#4. Should all state transitions for the adapter and network objects
be signalled from a single object or be split across network and
adapter implementations.
#5. The complete set of error signals needs definition.
#6. The credential agent API needs to be defined the current
agent-api.txt is just a place holder.
#7.
Closed Issues:
