doc: Make session methods as experimental for now
[platform/upstream/connman.git] / doc / manager-api.txt
1 Manager hierarchy
2 =================
3
4 Service         net.connman
5 Interface       net.connman.Manager
6 Object path     /
7
8 Methods         dict GetProperties()
9
10                         Returns all global system properties. See the
11                         properties section for available properties.
12
13                         Possible Errors: [service].Error.InvalidArguments
14
15                 void SetProperty(string name, variant value)
16
17                         Changes the value of the specified property. Only
18                         properties that are listed as read-write are
19                         changeable. On success a PropertyChanged signal
20                         will be emitted.
21
22                         Possible Errors: [service].Error.InvalidArguments
23                                          [service].Error.InvalidProperty
24
25                 void RequestScan(string type)
26
27                         Request to trigger a scan for the specified
28                         technology. The empty string "" triggers scanning
29                         on all technologies.
30
31                         Possible Errors: [service].Error.InvalidArguments
32
33                 void EnableTechnology(string type)
34
35                         Enable specified type of technologies.
36
37                         Possible Errors: [service].Error.InvalidArguments
38
39                 void DisableTechnology(string type)
40
41                         Disable specified type of technologies.
42
43                         Possible Errors: [service].Error.InvalidArguments
44
45                 array{object,dict} GetServices()
46
47                         Returns a sorted list of tuples with service
48                         object path and dictionary of service properties.
49
50                         This list will not contain sensitive information
51                         like passphrases etc.
52
53                         Possible Errors: [service].Error.InvalidArguments
54
55                 object ConnectProvider(dict provider)
56
57                         Connect to a VPN specified by the given provider
58                         properties.
59
60                         When successful this method will return the object
61                         path of the VPN service object.
62
63                         This method can also be used to connect to an
64                         already existing VPN.
65
66                         This method call will only return in case of an
67                         error or when the service is fully connected. So
68                         setting a longer D-Bus timeout might be a really
69                         good idea.
70
71                         When 'SessionMode' property is enabled, this method
72                         call is disallowed.
73
74                         Possible Errors: [service].Error.InvalidArguments
75
76                 void RegisterAgent(object path)
77
78                         Register new agent for handling user requests.
79
80                         Possible Errors: [service].Error.InvalidArguments
81
82                 void UnregisterAgent(object path)
83
84                         Unregister an existing agent.
85
86                         Possible Errors: [service].Error.InvalidArguments
87
88                 void RegisterCounter(object path, uint32 accuracy, uint32 period)  [experimental]
89
90                         Register a new counter for user notifications.
91
92                         The accuracy is specified in kilo-bytes and defines
93                         a threshold for counter updates. Together with the
94                         period value it defines how often user space needs
95                         to be updated. The period value is in seconds.
96
97                         This interface is not meant for time tracking. If
98                         the time needs to be tracked down to the second, it
99                         is better to have a real timer running inside the
100                         application than using this interface.
101
102                         Also getting notified for every kilo-byte is a bad
103                         choice (even if the interface supports it). Something
104                         like 10 kilo-byte units or better 1 mega-byte seems
105                         to be a lot more reasonable and better for the user.
106
107                         Possible Errors: [service].Error.InvalidArguments
108
109                 void UnregisterCounter(object path)  [experimental]
110
111                         Unregister an existing counter.
112
113                         Possible Errors: [service].Error.InvalidArguments
114
115                 object CreateSession(dict settings, object notifier)  [experimental]
116
117                         Create a new session for the application. Every
118                         application can create multiple session with
119                         different settings. The settings are described
120                         as part of the session interface.
121
122                         The notifier allows asynchronous notification about
123                         session specific changes. These changes can be
124                         for online/offline state or IP address changes or
125                         similar things the application is required to
126                         handle.
127
128                         Every application should at least create one session
129                         to inform about its requirements and it purpose.
130
131                 void DestroySession(object session)  [experimental]
132
133                         Remove the previously created session.
134
135                         If an application exits unexpectatly the session
136                         will be automatically destroyed.
137
138                 object path, dict, fd RequestPrivateNetwork(dict options)
139                                                                 [experimental]
140
141                         Request a new Private Network, which includes the
142                         creation of a tun/tap interface, and IP
143                         configuration, NAT and IP forwarding on that
144                         interface.
145                         An object path, a dictionnary and a file descriptor
146                         with IP settings are returned.
147
148                         Possible Errors: [service].Error.InvalidArguments
149                                          [service].Error.NotSupported
150
151                 void ReleasePrivateNetwork(object path) [experimental]
152
153                         Releases a private network.
154
155                         Possible Errors: [service].Error.InvalidArguments
156
157 Signals         PropertyChanged(string name, variant value)
158
159                         This signal indicates a changed value of the given
160                         property.
161
162 Properties      string State [readonly]
163
164                         The global connection state of a system. Possible
165                         values are "online" if at least one connection exists
166                         and "offline" if no device is connected.
167
168                         In certain situations the state might change to
169                         the value "connected". This can only be seen if
170                         previously no connection was present.
171
172                 array{string} AvailableTechnologies [readonly]
173
174                         The list of available technologies. The strings
175                         are the same as the ones from the service types.
176
177                 array{string} EnabledTechnologies [readonly]
178
179                         The list of enabled technologies. The strings
180                         are the same as the ones from the service types.
181
182                 array{string} ConnectedTechnologies [readonly]
183
184                         The list of connected technologies. The strings
185                         are the same as the ones from the service type.
186
187                 string DefaultTechnology [readonly]
188
189                         The current connected technology which holds the
190                         default route.
191
192                 boolean OfflineMode [readwrite]
193
194                         The offline mode indicates the global setting for
195                         switching all radios on or off. Changing offline mode
196                         to true results in powering down all devices. When
197                         leaving offline mode the individual policy of each
198                         device decides to switch the radio back on or not.
199
200                         During offline mode, it is still possible to switch
201                         certain technologies manually back on. For example
202                         the limited usage of WiFi or Bluetooth devices might
203                         be allowed in some situations.
204
205                 array{object} Technologies [readonly]
206
207                         List of technology object paths.
208
209                 array{object} Services [readonly]
210
211                         List of service object paths. The list is sorted
212                         internally to have the service with the default
213                         route always first and then the favorite services
214                         followed by scan results.
215
216                         This list represents the available services for the
217                         current selected profile. If the profile gets changed
218                         then this list will be updated.
219
220                         The same list is available via the profile object
221                         itself. It is just provided here for convenience of
222                         applications only dealing with the current active
223                         profile.
224
225                 boolean SessionMode [readwrite]  [experminental]
226
227                         This disables the auto connect feature. It should be
228                         enabled when the Session API is used. When SessionMode
229                         is enabled, 'ConnectService' and 'ConnectProvider'
230                         method calls are disallowed.
231
232                         The default value is false.