Hi All,
I have updated the proposed dbus API for accessing the Linux WiMax
stack. This update incorporates the comments I have received to date.
Overview of changes:
Added proposed methods to the credential agent API
Removed Get/SetProperty methods from adapter and network objects in
favor of using standard dbus properties API with the addition of the
PropertyChanged signal that Dan Williams will be proposing on the dbus
list.
Updated files to have BSD copyright notice.
Added version number to interface names
Many typo fix-ups
Removed ScanWide() method from adapter and added argument to Scan()
method
to control scanning behaviour.
Moved credential agent related method from adapter to network object.
The updated files are attached and are also available via git at
git://linuxwimax.org/dbus_wimaxapi.git
Thanks to everyone for their comments and suggestions. Please have a
look at the updated API and let me know what you think.
--Dirk
WiMax D-Bus Adapter API description
***********************************
Copyright (C) 2008 Intel Corporation
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Adapter hierarchy
=================
Service org.wimax
Interface org.wimax1.Adapter
Object path [variable prefix]/{wmx0,wmx1,...}
Methods void Scan(boolean wide_scan)
Instruct the adapter to search for available
networks.
wide_scan = FALSE: The signal space searched is
constrained by adapter specific configuration
options.
wide_scan = TRUE: 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 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
Signals NetworkFound(string address)
This signal will be send every time an scan result
has been found by the adapter.
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 RadioOn [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.
Wimax D-Bus Credential Agent API description
**********************************
Copyright (C) 2008 Intel Corporation
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
The agent API provides an interface for the wimax network object to
obtain credential/login information from the user.
Agent hierarchy
===============
Service org.wimax
Interface org.wimax1.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.
void SetCredentials( string username,
string password,
uint32 context_value)
This method sets the user credential that the
agent will provide to the stack via the
GetCredentials() method call. The context
value must be the same value passed to the
RegisterCredentialAgent() method of the
network object. The context should be chosen
so that it is not easily guessable and should
be different each time the credentials agent
is registered with the network object.
Possible Errors: TBD
void GetCredentials( uint32 context_value,
string username,
string password)
Return the username and password to the stack
if the context value matches the value passed
to SetCredentials() otherwise null strings are
returned.
Possible Errors: TBD
WiMax D-Bus network API description
**********************************
Copyright (C) 2008 Intel Corporation
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Device hierarchy
================
Service org.wimax
Interface org.wimax1.Network
Object path [variable prefix]/{wmx0,wmx1,...}/network_XX_XX_XX_XX_XX_XX
Methods 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
void RegisterCredentialAgent(object agent, uint32 context)
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.
The context value to be passed to the
agent GetCredentials() method.
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
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 TxPower [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.
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:
#3. Should NspContactInfoText and NspContactInfoURI properties in the
network object remain strings or be some type of structured
information.
#5. The complete set of error signals needs definition.
#7. What should the behavior of the credential agent be if the
GetCredentials() method is called with a context value that does
not match the value used in the call to the SetCredentials()
method?
#8. Documentation files need open source copyright notice.
Closed 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. CLOSED Scan()
method now takes a argument to control scanning behavior.
#2. Should the idea of configured "profiles" be part of the standard
D-Bus API or left to be vendor specific. CLOSED Configuration
interface will be vendor specific.
#6. The credential agent API needs to be defined the current
agent-api.txt is just a place holder. CLOSED credential agent API
proposal published.
#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. CLOSED Use new PropertyChanged signal per
object.
_______________________________________________
wimax mailing list
[email protected]
http://www.linuxwimax.org/mailman/listinfo/wimax
