iwd/doc/station-api.txt

Station hierarchy
=================

Service		net.connman.iwd
Interface	net.connman.iwd.Station
Object path	/net/connman/iwd/{phy0,phy1,...}/{1,2,...}

Methods		void Scan()

			Schedule a network scan.

			Possible errors: net.connman.iwd.Busy
					 net.connman.iwd.Failed

		void Disconnect()

			Disconnect from the network.  This also disables
			iwd from trying to autoconnect to any other network
			with this device.

			Possible errors: net.connman.iwd.Busy
					 net.connman.iwd.Failed
					 net.connman.iwd.NotConnected

		array(on) GetOrderedNetworks()

			Return the list of networks found in the most recent
			scan, sorted by their user interface importance
			score as calculated by iwd.  If the device is
			currently connected to a network, that network is
			always first on the list, followed by any known
			networks that have been used at least once before,
			followed by any other known networks and any other
			detected networks as the last group.  Within these
			groups the maximum relative signal-strength is the
			main sorting factor.

			Every record returned contains a tuple of the
			following values.

			object Object

				net.connman.iwd.Network object representing
				the network.

			int16 SignalStrength

				Network's maximum signal strength expressed
				in 100 * dBm.  The value is the range of 0
				(strongest signal) to -10000 (weakest signal)

		array(sns) GetHiddenAccessPoints() [experimental]

			Returns a list (possibly empty) of detected hidden
			access points.  The list is sorted according to the
			relative signal strength of each access point.

			Every record returned contains a 3-tuple of the
			following values.

			string Address

				Access Point's address

			int16 SignalStrength

				Access Point's signal strength expressed in
				100 * dBm.  The value is the range of 0
				(strongest signal) to -10000 (weakest signal)

			string Type

				The type of the hidden Access Point.  Same
				values as Network.Type.

		void ConnectHiddenNetwork(string ssid)

			Tries to find and connect to a hidden network for the
			first time.  Only hidden networks of type 'psk' and
			'open' are supported.  WPA-Enterprise hidden networks
			must be provisioned.

			The ssid parameter is used to find the hidden network.
			If no network with the given ssid is found, an
			net.connman.iwd.NotFound error is returned.

			In the unlikely case that both an open and pre-shared
			key hidden network with the given ssid is found an
			net.connman.iwd.ServiceSetOverlap error is returned.

			Once the hidden network is found, the connection will
			proceed as normal.  So the user agent will be asked
			for a passphrase, etc.

			This method should only be called once to provision
			a hidden network.  For all future connections the
			regular Network.Connect() API should be used.

			Possible errors: net.connman.iwd.Busy
					 net.connman.iwd.Failed
					 net.connman.iwd.InvalidArguments
					 net.connman.iwd.NotConfigured
					 net.connman.iwd.NotConnected
					 net.connman.iwd.NotFound
					 net.connman.iwd.ServiceSetOverlap
					 net.connman.iwd.AlreadyProvisioned
					 net.connman.iwd.NotHidden

		void RegisterSignalLevelAgent(object path,
						 array(int16) levels)

			Register the agent object to receive signal strength
			level change notifications on the
			net.connman.iwd.SignalLevelAgent interface, see
			below.  The "levels" parameters decides the
			thresholds in dBm that will generate a call to the
			agent's Changed method whenever current RSSI crosses
			any of the values.  The values must be passed in
			descending order.  The number and distance between
			requested threshold values is a compromise between
			resolution and the frequency of system wakeups and
			context-switches that are going to be occurring to
			update the client's signal meter.  Only one agent
			can be registered at any time.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.Failed
					 [service].Error.AlreadyExists
					 [service].Error.NotSupported

		void UnregisterSignalLevelAgent(object path)

			Unregister an existing agent.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.NotFound

Properties	string State [readonly]

			Reflects the general network connection state.  One of:

			"connected", "disconnected", "connecting",
			"disconnecting", "roaming"

		object ConnectedNetwork [readonly, optional]

			net.connman.iwd.Network object representing the
			network the device is currently connected to or to
			which a connection is in progress.  This property
			will be updated with the object path of the Network
			object as soon as the connection process is initiated,
			and will remain for as long as the connection is in
			progress, completed and the network has not been
			disconnected.

			On disconnection this property becomes invalid and
			disappears from the property list.  Refer to the
			State property documentation if you need to track
			the actual state of the connection.

		boolean Scanning [readonly]

			Reflects whether the station is currently scanning
			for networks.  net.connman.iwd.Network objects are
			updated when this property goes from true to false.

		object ConnectedAccessPoint [readonly, optional]

			net.connman.iwd.BasicServiceSet object represeting the
			BSS the device is currently connected to or to which
			a connection is in progress.

		ao Affinities [optional] [experimental]

			Array of net.connman.iwd.BasicServiceSet object paths
			that will be treated with higher affinity compared to
			other BSS's. Currently the only allowed value to be
			set in this array is the path to the currently connected
			BasicServiceSet object, i.e.
			Station.ConnectedAccessPoint.

			Setting the affinity will lower the roaming threshold,
			effectively locking IWD to the current BSS unless the
			RSSI drops below the critical threshold set by
			[General].CriticalRoamThreshold{5G} at which point
			IWD will proceed with normal roaming behavior.

			This property is cleared on roams/disconnections.

SignalLevelAgent hierarchy
==========================

Service		unique name
Interface	net.connman.iwd.SignalLevelAgent
Object path	freely definable

Methods		void Release(object device) [noreply]

			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 Changed(object device, uint8 level) [noreply]

			This method gets called when the signal strength
			measurement for the device's connected network changes
			enough to go from one level to another out of the N
			ranges defined by the array of (N-1) threshold values
			passed to RegisterSignalLevelAgent().  It also gets
			called immediately after the signal level agent is
			registered.  The level parameter is in the range from 0
			to N, 0 being the strongest signal or above the first
			threshold value in the array, and N being the weakest
			and below the last threshold value.  For example if
			RegisterSignalLevelAgent was called with the array [-40,
			-50, -60], the 'level' parameter of 0 would mean signal
			is received at -40 or more dBm and 3 would mean below
			-60 dBm and might correspond to 1 out of 4 bars on a UI
			signal meter.