1 OBEX client API description
2 ***************************
4 Copyright (C) 2007-2010 Marcel Holtmann <marcel@holtmann.org>
5 Copyright (C) 2011-2012 BMW Car IT GmbH. All rights reserved.
11 Service org.bluez.obex.client
12 Interface org.bluez.obex.Client
15 Methods object CreateSession(string destination, dict args)
17 Create a new OBEX session for the given remote address.
19 The last parameter is a dictionary to hold optional or
20 type-specific parameters. Typical parameters that can
21 be set in this dictionary include the following:
23 string "Target" : type of session to be created
24 string "Source" : local address to be used
27 The currently supported targets are the following:
35 void RemoveSession(object session)
37 Unregister session and abort pending transfers.
42 Service org.bluez.obex.client
43 Interface org.bluez.obex.Session
44 Object path [variable prefix]/{session0,session1,...}
46 Methods dict GetProperties()
48 Returns all properties for the session.
50 string GetCapabilities()
52 Get remote device capabilities.
54 Properties string Source [readonly]
56 string Destination [readonly]
58 byte Channel [readonly]
63 Service org.bluez.obex.client
64 Interface org.bluez.obex.ObjectPush
65 Object path [variable prefix]/{session0,session1,...}
67 Methods object, dict SendFile(string sourcefile)
69 Send one local file to the remote device.
71 The returned path represents the newly created transfer,
72 which should be used to find out if the content has been
73 successfully transferred or if the operation fails.
75 The properties of this transfer are also returned along
76 with the object path, to avoid a call to GetProperties.
78 object, dict PullBusinessCard(string targetfile)
80 Request the business card from a remote device and
81 store it in the local file.
83 If an empty target file is given, a name will be
84 automatically calculated for the temporary file.
86 The returned path represents the newly created transfer,
87 which should be used to find out if the content has been
88 successfully transferred or if the operation fails.
90 The properties of this transfer are also returned along
91 with the object path, to avoid a call to GetProperties.
93 object, dict ExchangeBusinessCards(string clientfile,
96 Push the client's business card to the remote device
97 and then retrieve the remote business card and store
100 If an empty target file is given, a name will be
101 automatically calculated for the temporary file.
103 The returned path represents the newly created transfer,
104 which should be used to find out if the content has been
105 successfully transferred or if the operation fails.
107 The properties of this transfer are also returned along
108 with the object path, to avoid a call to GetProperties.
110 File Transfer hierarchy
111 =======================
113 Service org.bluez.obex.client
114 Interface org.bluez.obex.FileTransfer
115 Object path [variable prefix]/{session0,session1,...}
117 Methods void ChangeFolder(string folder)
119 Change the current folder of the remote device.
121 void CreateFolder(string folder)
123 Create a new folder in the remote device.
125 array{dict} ListFolder()
127 Returns a dictionary containing information about
128 the current folder content.
130 The following keys are defined:
132 string Name : Object name in UTF-8 format
133 string Type : Either "folder" or "file"
134 uint64 Size : Object size or number of items in
136 string Permission : Group, owner and other
138 uint64 Modified : Last change
139 uint64 Accessed : Last access
140 uint64 Created : Creation date
142 object, dict GetFile(string targetfile, string sourcefile)
144 Copy the source file (from remote device) to the
145 target file (on local filesystem).
147 If an empty target file is given, a name will be
148 automatically calculated for the temporary file.
150 The returned path represents the newly created transfer,
151 which should be used to find out if the content has been
152 successfully transferred or if the operation fails.
154 The properties of this transfer are also returned along
155 with the object path, to avoid a call to GetProperties.
157 object, dict PutFile(string sourcefile, string targetfile)
159 Copy the source file (from local filesystem) to the
160 target file (on remote device).
162 The returned path represents the newly created transfer,
163 which should be used to find out if the content has been
164 successfully transferred or if the operation fails.
166 The properties of this transfer are also returned along
167 with the object path, to avoid a call to GetProperties.
169 void CopyFile(string sourcefile, string targetfile)
171 Copy a file within the remote device from source file
174 void MoveFile(string sourcefile, string targetfile)
176 Move a file within the remote device from source file
179 void Delete(string file)
181 Deletes the specified file/folder.
183 Phonebook Access hierarchy
184 =======================
186 Service org.bluez.obex.client
187 Interface org.bluez.obex.PhonebookAccess
188 Object path [variable prefix]/{session0,session1,...}
190 Methods void Select(string location, string phonebook)
192 Select the phonebook object for other operations. Should
193 be call before all the other operations.
195 location : Where the phonebook is stored, possible
197 "INT" ( "INTERNAL" which is default )
202 phonebook : Possible inputs :
203 "pb" : phonebook for the saved contacts
204 "ich": incoming call history
205 "och": outgoing call history
206 "mch": missing call history
207 "cch": combination of ich och mch
209 object, dict PullAll(string targetfile)
211 Return the entire phonebook object from the PSE server
212 in plain string with vcard format, and store it in
215 If an empty target file is given, a name will be
216 automatically calculated for the temporary file.
218 The returned path represents the newly created transfer,
219 which should be used to find out if the content has been
220 successfully transferred or if the operation fails.
222 The properties of this transfer are also returned along
223 with the object path, to avoid a call to GetProperties.
225 array{string vcard, string name} List()
227 Return an array of vcard-listing data where every entry
228 consists of a pair of strings containing the vcard
229 handle and the contact name. For example:
232 object, dict Pull(string vcard, string targetfile)
234 Given a vcard handle, retrieve the vcard in the current
235 phonebook object and store it in a local file.
237 If an empty target file is given, a name will be
238 automatically calculated for the temporary file.
240 The returned path represents the newly created transfer,
241 which should be used to find out if the content has been
242 successfully transferred or if the operation fails.
244 The properties of this transfer are also returned along
245 with the object path, to avoid a call to GetProperties.
247 array{string vcard, string name}
248 Search(string field, string value)
250 Search for entries matching the given condition and
251 return an array of vcard-listing data where every entry
252 consists of a pair of strings containing the vcard
253 handle and the contact name.
255 vcard : name paired string match the search condition.
257 field : the field in the vcard to search with
258 { "name" (default) | "number" | "sound" }
259 value : the string value to search for
263 Return the number of entries in the selected phonebook
264 object that are actually used (i.e. indexes that
265 correspond to non-NULL entries).
267 void SetFormat(string format)
269 Indicate the format of the vcard that should be return
272 format : { "vcard21" (default) | "vcard30" }
274 void SetOrder(string order)
276 Indicate the sorting method of the vcard-listing data
277 returned by List and Search methods.
279 order : { "indexed" (default) | "alphanumeric" |
282 void SetFilter(array{string})
284 Indicate fields that should be contained in vcards
285 return by related methods.
287 Give an empty array will clear the filter and return
288 all fields available in vcards. And this is the default
291 Possible filter fields : "VERSION", "FN", ..., "ALL",
294 array{string} ListFilterFields()
296 Return All Available fields that can be used in
299 array{string} GetFilter()
301 Return the current filter setting
303 Synchronization hierarchy
304 =======================
306 Service org.bluez.obex.client
307 Interface org.bluez.obex.Synchronization
308 Object path [variable prefix]/{session0,session1,...}
310 Methods void SetLocation(string location)
312 Set the phonebook object store location for other
313 operations. Should be called before all the other
316 location: Where the phonebook is stored, possible
318 "INT" ( "INTERNAL" which is default )
323 object, dict GetPhonebook(string targetfile)
325 Retrieve an entire Phonebook Object store from remote
326 device, and stores it in a local file.
328 If an empty target file is given, a name will be
329 automatically calculated for the temporary file.
331 The returned path represents the newly created transfer,
332 which should be used to find out if the content has been
333 successfully transferred or if the operation fails.
335 The properties of this transfer are also returned along
336 with the object path, to avoid a call to GetProperties.
338 object, dict PutPhonebook(string sourcefile)
340 Send an entire Phonebook Object store to remote device.
342 The returned path represents the newly created transfer,
343 which should be used to find out if the content has been
344 successfully transferred or if the operation fails.
346 The properties of this transfer are also returned along
347 with the object path, to avoid a call to GetProperties.
349 Message Access hierarchy
350 =========================
352 Service org.bluez.obex.client
353 Interface org.bluez.obex.MessageAccess
354 Object path [variable prefix]/{session0,session1,...}
356 Methods void SetFolder(string name)
358 Set working directory for current session, *name* may
359 be the directory name or '..[/dir]'.
361 array{dict} GetFolderListing(dict filter)
363 Returns a dictionary containing information about
364 the current folder content.
366 The following keys are defined:
368 string Name : Folder name
370 array{object, dict} GetMessageListing(string folder,
373 Returns an array containing the messages found in the
376 Each message is represented by an object path followed
377 by a dictionary of the properties.
393 string SenderAddress:
395 Message sender address
399 Message Reply-To address
403 Message recipient name
405 string RecipientAddress:
407 Message recipient address
413 Possible values: "EMAIL", "SMS_GSM",
418 Message size in bytes
422 Message reception status
424 Possible values: "complete",
425 "fractioned" and "notification"
429 Message priority flag
441 Message protected flag
446 Service org.bluez.obex.client
447 Interface org.bluez.obex.Message
448 Object path [variable prefix]/{session0,session1,...}/{message0,...}
450 Methods object, dict Get(string targetfile)
452 Download message and store it in the target file.
454 If an empty target file is given, a temporary file
455 will be automatically generated.
457 The returned path represents the newly created transfer,
458 which should be used to find out if the content has been
459 successfully transferred or if the operation fails.
461 The properties of this transfer are also returned along
462 with the object path, to avoid a call to GetProperties.
467 Service org.bluez.obex.client
468 Interface org.bluez.obex.Transfer
469 Object path [variable prefix]/{transfer0,transfer1,...}
471 Methods dict GetProperties()
473 Returns all properties for the transfer. See the
474 properties section for available properties.
478 Cancels this transfer.
480 Properties string Name [readonly]
482 Name of the transferred object.
484 uint64 Size [readonly]
486 Size of the transferred object. If the size is
487 unknown, then this property will not be present.
489 string Filename [readonly, optional]
491 Complete name of the file being received or sent.
493 uint64 Progress [readonly, optional]
495 Number of bytes transferred. For queued transfers, this
496 value will not be present.
498 Signals PropertyChanged(string name, variant value)
500 This signal indicates a changed value of the given
505 Informs that the transfer has completed successfully.
507 void Error(string code, string message)
509 Informs that the transfer has been terminated because