doc/client-api.txt

   1 OBEX client API description
   2 ***************************
   3
   4 Copyright (C) 2007-2010  Marcel Holtmann <marcel@holtmann.org>
   5
   6
   7 Client hierarchy
   8 ================
   9
  10 Service         org.openobex.client
  11 Interface       org.openobex.Client
  12 Object path     /
  13
  14 Methods         void SendFiles(dict device, array{string} files, object agent)
  15
  16                         Send one or multiple local files to the specified
  17                         device. The device is configured via properties. At
  18                         least the Destination property should be specified.
  19
  20                 void PullBusinessCard(dict device, string file)
  21
  22                         Request the business card from a remote device and
  23                         store it in the local file.
  24
  25                 void ExchangeBusinessCards(dict device, string clientfile, string file)
  26
  27                         Push the client's business card to the remote device
  28                         and then retrieve the remote business card and store
  29                         it in a local file.
  30
  31                 object CreateSession(dict device)
  32
  33                         Create a new OBEX session. The device is configured
  34                         via properties like in SendFiles.
  35
  36                 void RemoveSession(object session)
  37
  38                         Unregister session and abort pending transfers.
  39
  40                 string GetCapabilities(dict device)
  41
  42                         Get remote device capabilities.
  43
  44 Properties      string Target
  45
  46                 string Source
  47
  48                 string Destination
  49
  50                 byte Channel
  51
  52
  53 Session hierarchy
  54 =================
  55
  56 Service         org.openobex.client
  57 Interface       org.openobex.Session
  58 Object path     [variable prefix]/{session0,session1,...}
  59
  60 Methods         dict GetProperties()
  61
  62                         Returns all properties for the session.
  63
  64                 void AssignAgent(object agent)
  65
  66                         Assign an OBEX agent to this session. This allows
  67                         detailed progress reports about the transactions.
  68
  69                 void ReleaseAgent(object agent)
  70
  71                         Release a previously assigned OBEX agent.
  72
  73 Properties      string Source [read-only]
  74
  75                 string Destination [read-only]
  76
  77                 byte Channel [read-only]
  78
  79
  80 File Transfer hierarchy
  81 =======================
  82
  83 Service         org.openobex.client
  84 Interface       org.openobex.FileTransfer
  85 Object path     [variable prefix]/{session0,session1,...}
  86
  87 Methods         void ChangeFolder(string folder)
  88
  89                         Change the current folder of the remote device.
  90
  91                 void CreateFolder(string folder)
  92
  93                         Create a new folder in the remote device.
  94
  95                 array{dict} ListFolder()
  96
  97                         Returns a dictionary containing information about
  98                         the current folder content.
  99
 100                         The following keys are defined:
 101
 102                                 string Name : Object name in UTF-8 format
 103                                 string Type : Either "folder" or "file"
 104                                 uint64 Size : Object size or number of items in folder
 105                                 string Permission : Group, owner and other permission
 106                                 guint64 Modified : Last change
 107                                 guint64 Accessed : Last access
 108                                 guint64 Created : Creation date
 109
 110                 void GetFile(string targetfile, string sourcefile)
 111
 112                         Copy the source file (from remote device) to the
 113                         target file (on local filesystem).
 114
 115                         A new Transfer object is created to represent this
 116                         transaction.
 117
 118                 void PutFile(string sourcefile, string targetfile)
 119
 120                         Copy the source file (from local filesystem) to the
 121                         target file (on remote device).
 122
 123                         A new Transfer object is created to represent this
 124                         transaction.
 125
 126                 void CopyFile(string sourcefile, string targetfile)
 127
 128                         Copy a file within the remote device from source file
 129                         to target file.
 130
 131                 void MoveFile(string sourcefile, string targetfile)
 132
 133                         Move a file within the remote device from source file
 134                         to the target file.
 135
 136                 void Delete(string file)
 137
 138                         Deletes the specified file/folder.
 139
 140
 141 Phonebook Access hierarchy
 142 =======================
 143
 144 Service         org.openobex.client
 145 Interface       org.openobex.PhonebookAccess
 146 Object path     [variable prefix]/{session0,session1,...}
 147
 148 Methods         void Select(string location, string phonebook)
 149
 150                         Select the phonebook object for other operations. Should
 151                         be call before all the other operations.
 152
 153                         location : Where the phonebook is stored, possible inputs :
 154                                 "INT" ( "INTERNAL" which is default )
 155                                 "SIM" ( "SIM1" )
 156                                 "SIM2"
 157                                 ...
 158
 159                         phonebook : Possible inputs :
 160                                 "pb" :  phonebook for the saved contacts
 161                                 "ich":  incoming call history
 162                                 "och":  outgoing call history
 163                                 "mch":  missing call history
 164                                 "cch":  combination of ich och mch
 165
 166                 string PullAll()
 167
 168                         Return the entire phonebook object from the PSE server
 169                         in plain string with vcard format.
 170
 171                 array{string vcard, string name} List()
 172
 173                         Return an array of vcard-listing data which contains the
 174                         vcard : name paired string, for example "1.vcf" : "John".
 175
 176                 string Pull(string vcard)
 177
 178                         Retrieve the vcard in the current phonebook object
 179                         for example : Pull("0.vcf")
 180
 181                 array{string vcard, string name}
 182                 Search(string field, string value)
 183
 184                         Return an array of vcard-listing data which contains the
 185                         vcard : name paired string match the search condition.
 186
 187                         field : the field in the vcard to search with
 188                                 { "name" (default) | "number" | "sound" }
 189                         value : the string value to search for
 190
 191                 uint16 GetSize()
 192
 193                         Return the number of the non-null entries in the selected
 194                         phonebook object.
 195
 196                 void SetFormat(string format)
 197
 198                         Indicate the format of the vcard that should be return by
 199                         related methods.
 200
 201                         format : { "vcard21" (default) | "vcard30" }
 202
 203                 void SetOrder(string order)
 204
 205                         Indicate the sorting method of the vcard-listing data returned
 206                         by List and Search methods.
 207
 208                         order : { "indexed" (default) | "alphanumeric" | "phonetic" }
 209
 210                 void SetFilter(array{string})
 211
 212                         Indicate fields that should be contained in vcards return by
 213                         related methods.
 214
 215                         Give an empty array will clear the filter and return all fields
 216                         available in vcards. And this is the default behavior.
 217
 218                         Possible filter fields : "VERSION", "FN", ..., "ALL", "bit[0-63]"
 219
 220                 array{string} ListFilterFields()
 221
 222                         Return All Available fields that can be used in SefFilter method.
 223
 224                 array{string} GetFilter()
 225
 226                         Return the current filter setting
 227
 228 Synchronization hierarchy
 229 =======================
 230
 231 Service         org.openobex.client
 232 Interface       org.openobex.Synchronization
 233 Object path     [variable prefix]/{session0,session1,...}
 234
 235 Methods         void SetLocation(string location)
 236
 237                         Set the phonebook object store location for other operations. Should
 238                         be called before all the other operations.
 239
 240                         location: Where the phonebook is stored, possible values:
 241                                 "INT" ( "INTERNAL" which is default )
 242                                 "SIM1"
 243                                 "SIM2"
 244                                 ......
 245
 246                 string GetPhonebook()
 247
 248                         Retrieve an entire Phonebook Object store from remote device
 249
 250                 void PutPhonebook(string obj)
 251
 252                         Send an entire Phonebook Object store to remote device
 253
 254 Message Access hierarchy
 255 =========================
 256
 257 Service         org.openobex.client
 258 Interface       org.openobex.MessageAccess
 259 Object path     [variable prefix]/{session0,session1,...}
 260
 261 Methods         void SetFolder(string name)
 262
 263                         Set working directory for current session, *name* may
 264                         be the directory name or '..[/dir]'.
 265
 266 Transfer hierarchy
 267 ==================
 268
 269 Service         org.openobex.client
 270 Interface       org.openobex.Transfer
 271 Object path     [variable prefix]/{transfer0,transfer1,...}
 272
 273 Methods         dict GetProperties()
 274
 275                         Returns all properties for the transfer. See the
 276                         properties section for available properties.
 277
 278                 void Cancel()
 279
 280                         Cancels this transfer.
 281
 282 Properties      string Name [read-only]
 283
 284                         Name of the transferred object.
 285
 286                 uint64 Size [read-only]
 287
 288                         Size of the transferred object. If the size is
 289                         unknown, then this property will not be present.
 290
 291                 string Filename [read-only]
 292
 293                         Complete name of the file being received or sent.
 294
 295
 296 Agent hierarchy
 297 ===============
 298
 299 Service         unique name
 300 Interface       org.openobex.Agent
 301 Object path     freely definable
 302
 303 Methods         void Release()
 304
 305                         This method gets called when the service daemon
 306                         unregisters the agent. An agent can use it to do
 307                         cleanup tasks. There is no need to unregister the
 308                         agent, because when this method gets called it has
 309                         already been unregistered.
 310
 311                 string Request(object transfer)
 312
 313                         Accept or reject a new transfer (client and server)
 314                         and provide the filename for it.
 315
 316                         In case of incoming transfers it is the filename
 317                         where to store the file and for outgoing transfers
 318                         it is the filename to show the remote device. If left
 319                         empty it will be calculated automatically.
 320
 321                         Possible errors: org.openobex.Error.Rejected
 322                                          org.openobex.Error.Canceled
 323
 324                 void Progress(object transfer, uint64 transferred)
 325
 326                         Progress within the transfer has been made. The
 327                         number of transferred bytes is given as second
 328                         argument for convenience.
 329
 330                 void Complete(object transfer)
 331
 332                         Informs that the transfer has completed successfully.
 333
 334                 void Error(object transfer, string message)
 335
 336                         Informs that the transfer has been terminated because
 337                         of some error.