X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fmanager-api.txt;h=6eaa0a38a432f695d2e48475ae4ce81e9ba86782;hb=d5dd12e13467f9761a27ff228ef45d3212b80884;hp=40dac019f4b7522c28866b79193d83164f2b1007;hpb=cd9553812a30cdbb7d30731d84cc90a8d4463156;p=platform%2Fupstream%2Fconnman.git diff --git a/doc/manager-api.txt b/doc/manager-api.txt old mode 100644 new mode 100755 index 40dac01..6eaa0a3 --- a/doc/manager-api.txt +++ b/doc/manager-api.txt @@ -1,8 +1,8 @@ Manager hierarchy ================= -Service org.moblin.connman -Interface org.moblin.connman.Manager +Service net.connman +Interface net.connman.Manager Object path / Methods dict GetProperties() @@ -22,191 +22,283 @@ Methods dict GetProperties() Possible Errors: [service].Error.InvalidArguments [service].Error.InvalidProperty - string GetState() + array{object,dict} GetTechnologies() - Return global connection state of a system. The - same value is return via the State property. + Returns a list of tuples with technology object + path and dictionary of technology properties. Possible Errors: [service].Error.InvalidArguments - object CreateProfile(string name) + array{object,dict} GetServices() - Create and add new profile with the specified - identifier name. + Returns a sorted list of tuples with service + object path and dictionary of service properties. + + This list will not contain sensitive information + like passphrases etc. Possible Errors: [service].Error.InvalidArguments - void RemoveProfile(object path) + array{object,dict} GetPeers() [experimental] - Remove profile with specified object path. + Returns a sorted list of tuples with peer object path + and dictionary of peer properties - It is not possible to remove the current active - profile. To remove the active profile a different - one must be selected via ActiveProfile property - first. + Possible Errors: [service].Error.InvalidArguments - At minimum one profile must be available all the time. + array{string} GetTetheringClients() [experimental] - Possible Errors: [service].Error.InvalidArguments + Returns a sorted list of MAC addresses of clients + connected to tethered technologies. + + object ConnectProvider(dict provider) [deprecated] + + Connect to a VPN specified by the given provider + properties. + + When successful this method will return the object + path of the VPN service object. + + This method can also be used to connect to an + already existing VPN. + + This method call will only return in case of an + error or when the service is fully connected. So + setting a longer D-Bus timeout might be a really + good idea. - void RequestScan(string type) + When 'SessionMode' property is enabled, this method + call is disallowed. - Request to trigger a scan for the specified - technology. The empty string "" triggers scanning - on all technologies. + This API is deprecated and should not be used. + The VPN configuration API is provided by ConnMan + VPN daemon and user should use that one instead. Possible Errors: [service].Error.InvalidArguments - void EnableTechnology(string type) + void RemoveProvider(object path) [deprecated] - Enable specified type of technologies. + Remove a VPN specified by the object path. + + void RegisterAgent(object path) + + Register new agent for handling user requests. Possible Errors: [service].Error.InvalidArguments - void DisableTechnology(string type) + void UnregisterAgent(object path) - Disable specified type of technologies. + Unregister an existing agent. Possible Errors: [service].Error.InvalidArguments - arracy{object,dict} GetServices() + void RegisterCounter(object path, uint32 accuracy, uint32 period) [experimental] - Returns a sorted list of tuples with service - object path and dictionary of service properties. + Register a new counter for user notifications. - This list will not contain sensitive information - like passphrases etc. + The accuracy is specified in kilo-bytes and defines + a threshold for counter updates. Together with the + period value it defines how often user space needs + to be updated. The period value is in seconds. - Possible Errors: [service].Error.InvalidArguments + This interface is not meant for time tracking. If + the time needs to be tracked down to the second, it + is better to have a real timer running inside the + application than using this interface. - object LookupService(string pattern) + Also getting notified for every kilo-byte is a bad + choice (even if the interface supports it). Something + like 10 kilo-byte units or better 1 mega-byte seems + to be a lot more reasonable and better for the user. - Lookup a service matching the specific pattern. + Possible Errors: [service].Error.InvalidArguments - Examples are interface names like "eth0", "wlan0" - etc. or service names like "hotspot" etc. + void UnregisterCounter(object path) [experimental] - In case of multiple services match the the pattern - an error is returned. + Unregister an existing counter. Possible Errors: [service].Error.InvalidArguments - [service].Error.NotUnique - [service].Error.NotFound - object ConnectService(dict network) + object CreateSession(dict settings, object notifier) [experimental] - Connect to a network specified by the given - properties. + Create a new session for the application. Every + application can create multiple session with + different settings. The settings are described + as part of the session interface. - For connecting to a hidden WiFi network for example - it is required that Type = "wifi" and the SSID - properties are provided. + The notifier allows asynchronous notification about + session specific changes. These changes can be + for online/offline state or IP address changes or + similar things the application is required to + handle. - When successful this method will return object - path of the service object. + Every application should at least create one session + to inform about its requirements and it purpose. - This method can also be used to connect to an - already existing service. It works exactly the - same as executing the Connect method from the - service interface. + void DestroySession(object session) [experimental] - This method call will only return in case of an - error or when the service is fully connected. So - setting a longer D-Bus timeout might be a really - good idea. + Remove the previously created session. - Possible Errors: [service].Error.InvalidArguments + If an application exits unexpectatly the session + will be automatically destroyed. - void RegisterAgent(object path) + object path, dict, fd RequestPrivateNetwork(dict options) + [experimental] - Register new agent for handling user requests. + Request a new Private Network, which includes the + creation of a tun/tap interface, and IP + configuration, NAT and IP forwarding on that + interface. + An object path, a dictionary and a file descriptor + with IP settings are returned. Possible Errors: [service].Error.InvalidArguments + [service].Error.NotSupported - void UnregisterAgent(object path) + void ReleasePrivateNetwork(object path) [experimental] - Unregister an existing agent. + Releases a private network. Possible Errors: [service].Error.InvalidArguments - void RegisterCounter(object path, uint32 interval) + void RegisterPeerService(dict specification, boolean master) + [experimental] - Register a new counter for user notifications. + Registers a local P2P Peer service + + Even if p2p techonology is not available, it will be + possible to register peer services, since a p2p + enabled WiFi device might appear at anytime. The + registered peer services will automatically be enabled + for the p2p WiFi device; the application does not need + to do any re-registration. + + A Peer service belongs to the process that registers + it, thus if that process dies, its Peer services will + be destroyed as well. - If the interval is zero then no timer for updates - will be started. Only kernel events can then - trigger updates. Otherwise the kernel will be - polled every n seconds for an update. + The specification dict follows the format described + in the Peer API document. + + ConnMan will be able to determine in most cases + whether to be the P2P Group Owner or not. If the + service for some reason must belong to a group that + this device manages, the "master" property can be + set. Do not enable the "master" property unless it + is absolutely sure that this is needed for the + provided peer service. Possible Errors: [service].Error.InvalidArguments + [service].Error.AlreadyExists + [service].Error.NotSupported - void UnregisterCounter(object path) + void UnregisterPeerService(dict specification) [experimental] - Unregister an existing counter. + Unregisters an existing local P2P Peer service Possible Errors: [service].Error.InvalidArguments + [service].Error.NotRegistered - object RequestSession(string bearer) +Signals TechnologyAdded(object path, dict properties) - Request a networking session. + Signal that is sent when a new technology is added. - If the bearer is an empty string the best available - service will be picked. + It contains the object path of the technology and + also its properties. - When successful this method will return the object - path of the corresponding service. + TechnologyRemoved(object path) - Possible Errors: [service].Error.InvalidArguments + Signal that is sent when a technology has been removed. - void ReleaseSession() + The object path is no longer accessible after this + signal and only emitted for reference. - Release a networking session. + ServicesChanged(array{object, dict}, array{object}) - Possible Errors: [service].Error.InvalidArguments + This signal indicates a change in the services. + List of all services currently registered is passed + via the first array. And a list of services that have + been removed via the second array. -Signals PropertyChanged(string name, variant value) + The list of all services is sorted. The dictionary + with the properties might be empty in case none of + the properties have changed. Or only contains the + properties that have changed. - This signal indicates a changed value of the given - property. + For newly added services the whole set of properties + will be present. - StateChanged(string state) + The list of removed services can be empty. - This signal is similar to the PropertyChanged signal - for the State property. + This signal will only be triggered when the sort + order of the service list or the number of services + changes. It will not be emitted if only a property + of the service object changes. For that it is + required to watch the PropertyChanged signal of + the service object. - It exists for application state only care about the - current state and so can avoid to be woken up when - other details changes. + PeersChanged(array{object, dict}, array{object}) [experimental] -Properties string State [readonly] + This signal indicates a change in the peers. List of + all peers currently registered is passed via the first + array. And a list of peers that have been removed via + the second array. - The global connection state of a system. Possible - values are "online" if at least one connection exists - and "offline" if no device is connected. + The list of all peers is sorted. The dictionary + with the properties might be empty in case none of the + properties have changed. Or only contains the + properties that have changed. - In certain situations the state might change to - the value "connected". This can only be seen if - previously no connection was present. + For newly added peers the whole set of properties will + be present. - array{string} AvailableTechnologies [readonly] + The list of removed peers can be empty. - The list of available technologies. The strings - are the same as the ones from the service types. + This signal will only be triggered when the sort order + of the peer list or the number of peers changes. It + will not be emitted if only a property of the peer + object changes. For that it is required to watch the + PropertyChanged signal of the peer object. - array{string} EnabledTechnologies [readonly] + TetheringClientsChanged(array{string}, array{string}) [experimental] - The list of enabled technologies. The strings - are the same as the ones from the service types. + This signal indicates a change in the tethering clients. + List of all tethering clients currently registered connman is + passed via the first array. And a list of tethering clients that + have been removed via the second array. - array{string} ConnectedTechnologies [readonly] + PropertyChanged(string name, variant value) - The list of connected technologies. The strings - are the same as the ones from the service type. + This signal indicates a changed value of the given + property. + +Properties string State [readonly] + + The global connection state of a system. Possible + values are "offline", "idle", "ready" and "online". + + If the device is in offline mode, the value "offline" + indicates this special global state. It can also be + retrieved via the OfflineMode property, but is kept + here for consistency and to differentiate from "idle". + + However when OfflineMode property is true, the State + property can still be "idle", "ready" or "online" + since it is possible by the end user to re-enable + individual technologies like WiFi and Bluetooth while + in offline mode. + + The states "idle", "ready" and "online" match to + states from the services. If no service is in + either "ready" or "online" state it will indicate + the "idle" state. - string DefaultTechnology [readonly] + If at least one service is in "ready" state and no + service is in "online" state, then it will indicate + the "ready" state. - The current connected technology which holds the - default route. + When at least one service is in "online" state, + this property will indicate "online" as well. boolean OfflineMode [readwrite] @@ -221,37 +313,9 @@ Properties string State [readonly] the limited usage of WiFi or Bluetooth devices might be allowed in some situations. - boolean Tethering [readwrite] - - This option allows to enable or disable the support - for tethering. When tethering is enabled then the - default service is bridged to all client where - connection sharing is supported. - - object ActiveProfile [readwrite] - - Object path of the current active profile. - - array{object} Profiles [readonly] - - List of profile object paths. - - array{object} Technologies [readonly] - - List of technology object paths. - - array{object} Services [readonly] - - List of service object paths. The list is sorted - internally to have the service with the default - route always first and then the favorite services - followed by scan results. + boolean SessionMode [readwrite] [experminental][deprecated] - This list represents the available services for the - current selected profile. If the profile gets changed - then this list will be updated. + This property exists only for compatibility reasons + and does not affect ConnMan in any way. - The same list is available via the profile object - itself. It is just provided here for convenience of - applications only dealing with the current active - profile. + The default value is false.