New DBus API for wpa_supplicant

[Witold Sowa]

Hi,

I've almost finished implementing new DBus API for wpa_supplcant. You
can fetch it from my git:

git://repo.or.cz/hostap-gosc2009.git    master

We discussed the API proposal few weeks age on this list. Actual API
differs a bit from what we have established, because of some issues
which came out during implementation. Differences apply mainly blobs
debug params and some errors are not thrown as it was originally
designed. API supports introspection and is much more signal-property
orientated the the old one. wpa_supplicant can use both old and new API
at once, but each may be separately turned on or off in .config.

Most methods (including properties Set and Get(All)) may throw
org.freedesktop.DBus.Error.NoMemory in addition to errors specific to
audio. PropertyChanged signal is emited when some property changes, but
it is not emited when there is separated signal informing about property
change. E.g. when new Network is added, the NetworkAdded signal is
emited, but PropertyChanged is not, though Networks property changes.
It's a bit inconsistent but I hope it will make client's life easier.

Here is its description:

O: /fi/w1/wpa_supplicant1
I : fi.w1.wpa_supplicant1

M: CreateInterface(args a{sv}) -> path o
   args: Ifname -> s
         Driver -> s
         Bridge-ifname -> s

E: fi.w1.wpa_supplicant1.InterfaceExists
   fi.w1.wpa_supplicant1.InterfaceUnknown
   fi.w1.wpa_supplicant1.UnknownError

M: RemoveInterface(path o)
E: fi.w1.wpa_supplicant1.InterfaceUnknown
   fi.w1.wpa_supplicant1.UnknownError

M: GetInterface(ifname s) -> path o
E: fi.w1.wpa_supplicant1.InterfaceUnknown
   fi.w1.wpa_supplicant1.UnknownError

P: Interfaces (read-only) -> ao
   EapMethods (read-only) -> as
   DebugParams (read/write) -> (ubb)
     u - debug_level, b - timestamps, b - show_keys

S: InterfaceAdded -> path o
S: InterfaceRemoved -> path o
S: PropertiesChanged -> properties a{sv}

****************************************

O: /fi/w1.wpa_supplicant1/Interfaces/<unique_number>
I: fi.w1.wpa_supplicant1.Interface

P: Capabilities (read-only) -> a{sv}
     Pairwise -> as          [ccmp, tkip, none]
     Group -> as             [ccmp, tkip, wep104, wep40]
     Keymgmt -> as           [wpa-psk, wpa-eap, ieee8021x, wpa-none,
wps, none]
     Protocol -> as          [rsn, wpa]
     AuthAlg -> as           [open, shared, leap]
     Scan -> as              [active, passive, ssid, bssid, ies, channel]
                             At this time Scan is always equal to
["active", "passive", "ssid"]
P: State (read-only) -> s    [disconnected, inactive, scanning,
authenticating, associating, associated, way_handshake, group_handshake,
completed, unknown]
P: Scanning (read-only) -> b
P: ApScan (read/write) -> u  [0, 1, 2]
P: Ifname (read-only) -> s
P: Driver (read-only) -> s
P: Bridge-ifname (read-only) -> s
P: Blobs (read-only) ->as
P: BSSs (read-only) -> ao
P: Networks (read-only) -> ao

M: Scan (args a{sv})
     args: Type -> s          [active, passive]
           SSIDs -> aay       array of (SSID)
           IEs -> aay         array of (IE)
           Channels -> a(uu)  array of (center freq in KHz, width)
E: fi.w1.wpa_supplicant1.InvalidArgs

M: Disconnect
E: fi.w1.wpa_supplicant1.Interface.NotConnected

M: AddNetwork (args a{sv}) -> o
     args: <dict of network properties i.e. properties form network
block from wpa_supplicant config file
E: fi.w1.wpa_supplicant1.UnknownError

M: RemoveNetwork (path o)
E: fi.w1.wpa_supplicant1.InvalidArgs
   fi.w1.wpa_supplicant1.UnknownError
   fi.w1.wpa_supplicant1.Interface.NetworkUnknown

M: SelectNetwork (path o)
E: fi.w1.wpa_supplicant1.InvalidArgs
E: fi.w1.wpa_supplicant1.Interface.NetworkUnknown

M: AddBlob (name s, data ay)
E: fi.w1.wpa_supplicant1.Interface.BlobExists

M: GetBlob (name s) -> data ay
E: fi.w1.wpa_supplicant1.Interface.BlobUnknown

M: RemoveBlob (name s)
E: fi.w1.wpa_supplicant1.Interface.BlobUnknown

S: PropertiesChanged -> properties a{sv}
S: ScanDone -> success b
S: StateChanged -> new_state s, old_state s
S: BSSAdded -> path o
S: BSSRemoved -> path o
S: BlobAdded -> name s
S: BlobRemoved ->name s
S: NetworkAdded, -> path o
S: NetworkRemoved -> path o
S: NetworkSelected -> path o

****************************************

O: /fi/w1.wpa_supplicant1/Interfaces/<unique_number>
I: fi.w1.wpa_supplicant1.Interface.WPS

M: Start (args a{sv}) -> a{sv}
     args: Role -> s         [enrollee, registrar]
           Type -> a         [pin, pbc]
           Bssid -> ay       (optional)
           Pin -> s          (optional)
     Returns:
           Pin -> s          (autogenerated PIN if not specified in args)

//TODO: Credetials property is not yet implemented so it may slightly change
P: Credentials (read-only) -> a{sv}
     BSSID -> ay
     SSID -> ay
     AuthType -> as                       [open, shared, wpa-psk,
wpa-eap, wpa2-eap, wpa2-psk]
     EncrType -> as                       [none, wep, tkip, aes]
     Key -> ay                            byte-array of key data
     KeyIndex -> u

P: ProcessCredentials (read/write) -> b
S: PropertiesChanged -> a{sv}
S: Event -> name s, args a{sv}
     name is one of "success", "fail" or "m2d"

****************************************

O:
/fi/w1.wpa_supplicant1/Interfaces/<unique_number>/Networks/<unique_number>
I: fi.w1.wpa_supplicant1.Interface.Network

P: Enabled (read/write) -> b
P: <wpa_supplicant network block properties> (read/write) -> a{sv}
     - Most properties can be set as strings, but can also be set
       as a byte array if necessary (SSID, BSSID, PSK, etc).  Supplicant
       can autoconvert like it does right now.

S: PropertiesChanged -> a{sv}

****************************************

O: /fi/w1.wpa_supplicant1/Interfaces/<interface_number>/BSSs/<BSSID>
I: fi.w1.wpa_supplicant1.Interface.BSS

P: <BSS properties - identical to old API BSSID properties> (read-only)

****************************************


I will implement WPS's Credentials property within few days, so the API
implementation will be completed,  but you may start testing in right now.

Regards,
Witek.