doc/client-api.txt

   1 OBEX client API description
   2 ***************************
   3
   4 Copyright (C) 2007-2010  Marcel Holtmann <marcel@holtmann.org>
   5 Copyright (C) 2011-2012  BMW Car IT GmbH. All rights reserved.
   6
   7
   8 Client hierarchy
   9 ================
  10
  11 Service         org.bluez.obex.client
  12 Interface       org.bluez.obex.Client
  13 Object path     /
  14
  15 Methods         object CreateSession(string destination, dict args)
  16
  17                         Create a new OBEX session for the given remote address.
  18
  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:
  22
  23                                 string "Target" : type of session to be created
  24                                 string "Source" : local address to be used
  25                                 byte "Channel"
  26
  27                         The currently supported targets are the following:
  28
  29                                 "FTP"
  30                                 "MAP"
  31                                 "OPP"
  32                                 "PBAP"
  33                                 "SYNC"
  34
  35                 void RemoveSession(object session)
  36
  37                         Unregister session and abort pending transfers.
  38
  39 Session hierarchy
  40 =================
  41
  42 Service         org.bluez.obex.client
  43 Interface       org.bluez.obex.Session
  44 Object path     [variable prefix]/{session0,session1,...}
  45
  46 Methods         dict GetProperties()
  47
  48                         Returns all properties for the session.
  49
  50                 string GetCapabilities()
  51
  52                         Get remote device capabilities.
  53
  54 Properties      string Source [readonly]
  55
  56                 string Destination [readonly]
  57
  58                 byte Channel [readonly]
  59
  60 Object Push hierarchy
  61 =====================
  62
  63 Service         org.bluez.obex.client
  64 Interface       org.bluez.obex.ObjectPush
  65 Object path     [variable prefix]/{session0,session1,...}
  66
  67 Methods         object, dict SendFile(string sourcefile)
  68
  69                         Send one local file to the remote device.
  70
  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.
  74
  75                         The properties of this transfer are also returned along
  76                         with the object path, to avoid a call to GetProperties.
  77
  78                 object, dict PullBusinessCard(string targetfile)
  79
  80                         Request the business card from a remote device and
  81                         store it in the local file.
  82
  83                         If an empty target file is given, a name will be
  84                         automatically calculated for the temporary file.
  85
  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.
  89
  90                         The properties of this transfer are also returned along
  91                         with the object path, to avoid a call to GetProperties.
  92
  93                 object, dict ExchangeBusinessCards(string clientfile,
  94                                                         string targetfile)
  95
  96                         Push the client's business card to the remote device
  97                         and then retrieve the remote business card and store
  98                         it in a local file.
  99
 100                         If an empty target file is given, a name will be
 101                         automatically calculated for the temporary file.
 102
 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.
 106
 107                         The properties of this transfer are also returned along
 108                         with the object path, to avoid a call to GetProperties.
 109
 110 File Transfer hierarchy
 111 =======================
 112
 113 Service         org.bluez.obex.client
 114 Interface       org.bluez.obex.FileTransfer
 115 Object path     [variable prefix]/{session0,session1,...}
 116
 117 Methods         void ChangeFolder(string folder)
 118
 119                         Change the current folder of the remote device.
 120
 121                 void CreateFolder(string folder)
 122
 123                         Create a new folder in the remote device.
 124
 125                 array{dict} ListFolder()
 126
 127                         Returns a dictionary containing information about
 128                         the current folder content.
 129
 130                         The following keys are defined:
 131
 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
 135                                                 folder
 136                                 string Permission : Group, owner and other
 137                                                         permission
 138                                 uint64 Modified : Last change
 139                                 uint64 Accessed : Last access
 140                                 uint64 Created : Creation date
 141
 142                 object, dict GetFile(string targetfile, string sourcefile)
 143
 144                         Copy the source file (from remote device) to the
 145                         target file (on local filesystem).
 146
 147                         If an empty target file is given, a name will be
 148                         automatically calculated for the temporary file.
 149
 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.
 153
 154                         The properties of this transfer are also returned along
 155                         with the object path, to avoid a call to GetProperties.
 156
 157                 object, dict PutFile(string sourcefile, string targetfile)
 158
 159                         Copy the source file (from local filesystem) to the
 160                         target file (on remote device).
 161
 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.
 165
 166                         The properties of this transfer are also returned along
 167                         with the object path, to avoid a call to GetProperties.
 168
 169                 void CopyFile(string sourcefile, string targetfile)
 170
 171                         Copy a file within the remote device from source file
 172                         to target file.
 173
 174                 void MoveFile(string sourcefile, string targetfile)
 175
 176                         Move a file within the remote device from source file
 177                         to the target file.
 178
 179                 void Delete(string file)
 180
 181                         Deletes the specified file/folder.
 182
 183 Phonebook Access hierarchy
 184 =======================
 185
 186 Service         org.bluez.obex.client
 187 Interface       org.bluez.obex.PhonebookAccess
 188 Object path     [variable prefix]/{session0,session1,...}
 189
 190 Methods         void Select(string location, string phonebook)
 191
 192                         Select the phonebook object for other operations. Should
 193                         be call before all the other operations.
 194
 195                         location : Where the phonebook is stored, possible
 196                         inputs :
 197                                 "INT" ( "INTERNAL" which is default )
 198                                 "SIM" ( "SIM1" )
 199                                 "SIM2"
 200                                 ...
 201
 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
 208
 209                 object, dict PullAll(string targetfile)
 210
 211                         Return the entire phonebook object from the PSE server
 212                         in plain string with vcard format, and store it in
 213                         a local file.
 214
 215                         If an empty target file is given, a name will be
 216                         automatically calculated for the temporary file.
 217
 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.
 221
 222                         The properties of this transfer are also returned along
 223                         with the object path, to avoid a call to GetProperties.
 224
 225                 array{string vcard, string name} List()
 226
 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:
 230                                 "1.vcf" : "John"
 231
 232                 object, dict Pull(string vcard, string targetfile)
 233
 234                         Given a vcard handle, retrieve the vcard in the current
 235                         phonebook object and store it in a local file.
 236
 237                         If an empty target file is given, a name will be
 238                         automatically calculated for the temporary file.
 239
 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.
 243
 244                         The properties of this transfer are also returned along
 245                         with the object path, to avoid a call to GetProperties.
 246
 247                 array{string vcard, string name}
 248                 Search(string field, string value)
 249
 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.
 254
 255                         vcard : name paired string match the search condition.
 256
 257                         field : the field in the vcard to search with
 258                                 { "name" (default) | "number" | "sound" }
 259                         value : the string value to search for
 260
 261                 uint16 GetSize()
 262
 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).
 266
 267                 void SetFormat(string format)
 268
 269                         Indicate the format of the vcard that should be return
 270                         by related methods.
 271
 272                         format : { "vcard21" (default) | "vcard30" }
 273
 274                 void SetOrder(string order)
 275
 276                         Indicate the sorting method of the vcard-listing data
 277                         returned by List and Search methods.
 278
 279                         order : { "indexed" (default) | "alphanumeric" |
 280                                         "phonetic" }
 281
 282                 void SetFilter(array{string})
 283
 284                         Indicate fields that should be contained in vcards
 285                         return by related methods.
 286
 287                         Give an empty array will clear the filter and return
 288                         all fields available in vcards. And this is the default
 289                         behavior.
 290
 291                         Possible filter fields : "VERSION", "FN", ..., "ALL",
 292                         "bit[0-63]"
 293
 294                 array{string} ListFilterFields()
 295
 296                         Return All Available fields that can be used in
 297                         SetFilter method.
 298
 299                 array{string} GetFilter()
 300
 301                         Return the current filter setting
 302
 303 Synchronization hierarchy
 304 =======================
 305
 306 Service         org.bluez.obex.client
 307 Interface       org.bluez.obex.Synchronization
 308 Object path     [variable prefix]/{session0,session1,...}
 309
 310 Methods         void SetLocation(string location)
 311
 312                         Set the phonebook object store location for other
 313                         operations. Should be called before all the other
 314                         operations.
 315
 316                         location: Where the phonebook is stored, possible
 317                         values:
 318                                 "INT" ( "INTERNAL" which is default )
 319                                 "SIM1"
 320                                 "SIM2"
 321                                 ......
 322
 323                 object, dict GetPhonebook(string targetfile)
 324
 325                         Retrieve an entire Phonebook Object store from remote
 326                         device, and stores it in a local file.
 327
 328                         If an empty target file is given, a name will be
 329                         automatically calculated for the temporary file.
 330
 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.
 334
 335                         The properties of this transfer are also returned along
 336                         with the object path, to avoid a call to GetProperties.
 337
 338                 object, dict PutPhonebook(string sourcefile)
 339
 340                         Send an entire Phonebook Object store to remote device.
 341
 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.
 345
 346                         The properties of this transfer are also returned along
 347                         with the object path, to avoid a call to GetProperties.
 348
 349 Message Access hierarchy
 350 =========================
 351
 352 Service         org.bluez.obex.client
 353 Interface       org.bluez.obex.MessageAccess
 354 Object path     [variable prefix]/{session0,session1,...}
 355
 356 Methods         void SetFolder(string name)
 357
 358                         Set working directory for current session, *name* may
 359                         be the directory name or '..[/dir]'.
 360
 361                 array{dict} GetFolderListing(dict filter)
 362
 363                         Returns a dictionary containing information about
 364                         the current folder content.
 365
 366                         The following keys are defined:
 367
 368                                 string Name : Folder name
 369
 370                 array{object, dict} GetMessageListing(string folder,
 371                                                                 dict filter)
 372
 373                         Returns an array containing the messages found in the
 374                         given folder.
 375
 376                         Each message is represented by an object path followed
 377                         by a dictionary of the properties.
 378
 379                         Properties:
 380
 381                                 string Subject:
 382
 383                                         Message subject
 384
 385                                 string Timestamp:
 386
 387                                         Message timestamp
 388
 389                                 string Sender:
 390
 391                                         Message sender name
 392
 393                                 string SenderAddress:
 394
 395                                         Message sender address
 396
 397                                 string ReplyTo:
 398
 399                                         Message Reply-To address
 400
 401                                 string Recipient:
 402
 403                                         Message recipient name
 404
 405                                 string RecipientAddress:
 406
 407                                         Message recipient address
 408
 409                                 string Type:
 410
 411                                         Message type
 412
 413                                         Possible values: "EMAIL", "SMS_GSM",
 414                                         "SMS_CDMA" and "MMS"
 415
 416                                 uint64 Size:
 417
 418                                         Message size in bytes
 419
 420                                 string Status:
 421
 422                                         Message reception status
 423
 424                                         Possible values: "complete",
 425                                         "fractioned" and "notification"
 426
 427                                 boolean Priority:
 428
 429                                         Message priority flag
 430
 431                                 boolean Read:
 432
 433                                         Message read flag
 434
 435                                 boolean Sent:
 436
 437                                         Message sent flag
 438
 439                                 boolean Protected:
 440
 441                                         Message protected flag
 442
 443 Message hierarchy
 444 =================
 445
 446 Service         org.bluez.obex.client
 447 Interface       org.bluez.obex.Message
 448 Object path     [variable prefix]/{session0,session1,...}/{message0,...}
 449
 450 Methods         object, dict Get(string targetfile)
 451
 452                         Download message and store it in the target file.
 453
 454                         If an empty target file is given, a temporary file
 455                         will be automatically generated.
 456
 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.
 460
 461                         The properties of this transfer are also returned along
 462                         with the object path, to avoid a call to GetProperties.
 463
 464 Transfer hierarchy
 465 ==================
 466
 467 Service         org.bluez.obex.client
 468 Interface       org.bluez.obex.Transfer
 469 Object path     [variable prefix]/{transfer0,transfer1,...}
 470
 471 Methods         dict GetProperties()
 472
 473                         Returns all properties for the transfer. See the
 474                         properties section for available properties.
 475
 476                 void Cancel()
 477
 478                         Cancels this transfer.
 479
 480 Properties      string Name [readonly]
 481
 482                         Name of the transferred object.
 483
 484                 uint64 Size [readonly]
 485
 486                         Size of the transferred object. If the size is
 487                         unknown, then this property will not be present.
 488
 489                 string Filename [readonly, optional]
 490
 491                         Complete name of the file being received or sent.
 492
 493                 uint64 Progress [readonly, optional]
 494
 495                         Number of bytes transferred. For queued transfers, this
 496                         value will not be present.
 497
 498 Signals         PropertyChanged(string name, variant value)
 499
 500                         This signal indicates a changed value of the given
 501                         property.
 502
 503                 void Complete()
 504
 505                         Informs that the transfer has completed successfully.
 506
 507                 void Error(string code, string message)
 508
 509                         Informs that the transfer has been terminated because
 510                         of some error.