mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-26 05:34:23 +08:00
652 lines
15 KiB
Plaintext
652 lines
15 KiB
Plaintext
OBEX client API description
|
|
***************************
|
|
|
|
Copyright (C) 2007-2010 Marcel Holtmann <marcel@holtmann.org>
|
|
Copyright (C) 2011-2012 BMW Car IT GmbH. All rights reserved.
|
|
|
|
|
|
Client hierarchy
|
|
================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.Client
|
|
Object path /org/bluez/obex
|
|
|
|
Methods object CreateSession(string destination, dict args)
|
|
|
|
Create a new OBEX session for the given remote address.
|
|
|
|
The last parameter is a dictionary to hold optional or
|
|
type-specific parameters. Typical parameters that can
|
|
be set in this dictionary include the following:
|
|
|
|
string "Target" : type of session to be created
|
|
string "Source" : local address to be used
|
|
byte "Channel"
|
|
|
|
The currently supported targets are the following:
|
|
|
|
"FTP"
|
|
"MAP"
|
|
"OPP"
|
|
"PBAP"
|
|
"SYNC"
|
|
|
|
void RemoveSession(object session)
|
|
|
|
Unregister session and abort pending transfers.
|
|
|
|
Session hierarchy
|
|
=================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.Session
|
|
Object path [variable prefix]/{session0,session1,...}
|
|
|
|
Methods string GetCapabilities()
|
|
|
|
Get remote device capabilities.
|
|
|
|
Properties string Source [readonly]
|
|
|
|
string Destination [readonly]
|
|
|
|
byte Channel [readonly]
|
|
|
|
Object Push hierarchy
|
|
=====================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.ObjectPush
|
|
Object path [variable prefix]/{session0,session1,...}
|
|
|
|
Methods object, dict SendFile(string sourcefile)
|
|
|
|
Send one local file to the remote device.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
object, dict PullBusinessCard(string targetfile)
|
|
|
|
Request the business card from a remote device and
|
|
store it in the local file.
|
|
|
|
If an empty target file is given, a name will be
|
|
automatically calculated for the temporary file.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
object, dict ExchangeBusinessCards(string clientfile,
|
|
string targetfile)
|
|
|
|
Push the client's business card to the remote device
|
|
and then retrieve the remote business card and store
|
|
it in a local file.
|
|
|
|
If an empty target file is given, a name will be
|
|
automatically calculated for the temporary file.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
File Transfer hierarchy
|
|
=======================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.FileTransfer
|
|
Object path [variable prefix]/{session0,session1,...}
|
|
|
|
Methods void ChangeFolder(string folder)
|
|
|
|
Change the current folder of the remote device.
|
|
|
|
void CreateFolder(string folder)
|
|
|
|
Create a new folder in the remote device.
|
|
|
|
array{dict} ListFolder()
|
|
|
|
Returns a dictionary containing information about
|
|
the current folder content.
|
|
|
|
The following keys are defined:
|
|
|
|
string Name : Object name in UTF-8 format
|
|
string Type : Either "folder" or "file"
|
|
uint64 Size : Object size or number of items in
|
|
folder
|
|
string Permission : Group, owner and other
|
|
permission
|
|
uint64 Modified : Last change
|
|
uint64 Accessed : Last access
|
|
uint64 Created : Creation date
|
|
|
|
object, dict GetFile(string targetfile, string sourcefile)
|
|
|
|
Copy the source file (from remote device) to the
|
|
target file (on local filesystem).
|
|
|
|
If an empty target file is given, a name will be
|
|
automatically calculated for the temporary file.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
object, dict PutFile(string sourcefile, string targetfile)
|
|
|
|
Copy the source file (from local filesystem) to the
|
|
target file (on remote device).
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
void CopyFile(string sourcefile, string targetfile)
|
|
|
|
Copy a file within the remote device from source file
|
|
to target file.
|
|
|
|
void MoveFile(string sourcefile, string targetfile)
|
|
|
|
Move a file within the remote device from source file
|
|
to the target file.
|
|
|
|
void Delete(string file)
|
|
|
|
Deletes the specified file/folder.
|
|
|
|
Phonebook Access hierarchy
|
|
=======================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.PhonebookAccess
|
|
Object path [variable prefix]/{session0,session1,...}
|
|
|
|
Methods void Select(string location, string phonebook)
|
|
|
|
Select the phonebook object for other operations. Should
|
|
be call before all the other operations.
|
|
|
|
location : Where the phonebook is stored, possible
|
|
inputs :
|
|
"INT" ( "INTERNAL" which is default )
|
|
"SIM" ( "SIM1" )
|
|
"SIM2"
|
|
...
|
|
|
|
phonebook : Possible inputs :
|
|
"pb" : phonebook for the saved contacts
|
|
"ich": incoming call history
|
|
"och": outgoing call history
|
|
"mch": missing call history
|
|
"cch": combination of ich och mch
|
|
|
|
object, dict PullAll(string targetfile, dict filters)
|
|
|
|
Return the entire phonebook object from the PSE server
|
|
in plain string with vcard format, and store it in
|
|
a local file.
|
|
|
|
If an empty target file is given, a name will be
|
|
automatically calculated for the temporary file.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
Possible filters: Format, Order, Offset, MaxCount and
|
|
Fields
|
|
|
|
array{string vcard, string name} List(dict filters)
|
|
|
|
Return an array of vcard-listing data where every entry
|
|
consists of a pair of strings containing the vcard
|
|
handle and the contact name. For example:
|
|
"1.vcf" : "John"
|
|
|
|
Possible filters: Order, Offset and MaxCount
|
|
|
|
|
|
object, dict
|
|
Pull(string vcard, string targetfile, dict filters)
|
|
|
|
Given a vcard handle, retrieve the vcard in the current
|
|
phonebook object and store it in a local file.
|
|
|
|
If an empty target file is given, a name will be
|
|
automatically calculated for the temporary file.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
Possbile filters: Format and Fields
|
|
|
|
|
|
array{string vcard, string name}
|
|
Search(string field, string value, dict filters)
|
|
|
|
Search for entries matching the given condition and
|
|
return an array of vcard-listing data where every entry
|
|
consists of a pair of strings containing the vcard
|
|
handle and the contact name.
|
|
|
|
vcard : name paired string match the search condition.
|
|
|
|
field : the field in the vcard to search with
|
|
{ "name" (default) | "number" | "sound" }
|
|
value : the string value to search for
|
|
|
|
|
|
Possible filters: Order, Offset and MaxCount
|
|
|
|
uint16 GetSize()
|
|
|
|
Return the number of entries in the selected phonebook
|
|
object that are actually used (i.e. indexes that
|
|
correspond to non-NULL entries).
|
|
|
|
array{string} ListFilterFields()
|
|
|
|
Return All Available fields that can be used in Fields
|
|
filter.
|
|
|
|
Filter: string Format:
|
|
|
|
Items vcard format
|
|
|
|
Possible values: "vcard21" (default) or "vcard30"
|
|
|
|
string Order:
|
|
|
|
Items order
|
|
|
|
Possible values: "indexed" (default), "alphanumeric" or
|
|
"phonetic"
|
|
|
|
uint16 Offset:
|
|
|
|
Offset of the first item, default is 0
|
|
|
|
uint16 MaxCount:
|
|
|
|
Maximum number of items, default is unlimited (65535)
|
|
|
|
array{string} Fields:
|
|
|
|
Item vcard fields, default is all values.
|
|
|
|
Possible values can be query with ListFilterFields.
|
|
|
|
|
|
Synchronization hierarchy
|
|
=======================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.Synchronization
|
|
Object path [variable prefix]/{session0,session1,...}
|
|
|
|
Methods void SetLocation(string location)
|
|
|
|
Set the phonebook object store location for other
|
|
operations. Should be called before all the other
|
|
operations.
|
|
|
|
location: Where the phonebook is stored, possible
|
|
values:
|
|
"INT" ( "INTERNAL" which is default )
|
|
"SIM1"
|
|
"SIM2"
|
|
......
|
|
|
|
object, dict GetPhonebook(string targetfile)
|
|
|
|
Retrieve an entire Phonebook Object store from remote
|
|
device, and stores it in a local file.
|
|
|
|
If an empty target file is given, a name will be
|
|
automatically calculated for the temporary file.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
object, dict PutPhonebook(string sourcefile)
|
|
|
|
Send an entire Phonebook Object store to remote device.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
Message Access hierarchy
|
|
=========================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.MessageAccess
|
|
Object path [variable prefix]/{session0,session1,...}
|
|
|
|
Methods void SetFolder(string name)
|
|
|
|
Set working directory for current session, *name* may
|
|
be the directory name or '..[/dir]'.
|
|
|
|
array{dict} ListFolders(dict filter)
|
|
|
|
Returns a dictionary containing information about
|
|
the current folder content.
|
|
|
|
The following keys are defined:
|
|
|
|
string Name : Folder name
|
|
|
|
Possible filters: Offset and MaxCount
|
|
|
|
array{string} ListFilterFields()
|
|
|
|
Return all available fields that can be used in Fields
|
|
filter.
|
|
|
|
array{object, dict} ListMessages(string folder, dict filter)
|
|
|
|
Returns an array containing the messages found in the
|
|
given folder.
|
|
|
|
Possible Filters: Offset, MaxCount, Fields, Type,
|
|
PeriodStart, PeriodEnd, Status, Recipient, Sender,
|
|
Priority
|
|
|
|
Each message is represented by an object path followed
|
|
by a dictionary of the properties.
|
|
|
|
Properties:
|
|
|
|
string Subject:
|
|
|
|
Message subject
|
|
|
|
string Timestamp:
|
|
|
|
Message timestamp
|
|
|
|
string Sender:
|
|
|
|
Message sender name
|
|
|
|
string SenderAddress:
|
|
|
|
Message sender address
|
|
|
|
string ReplyTo:
|
|
|
|
Message Reply-To address
|
|
|
|
string Recipient:
|
|
|
|
Message recipient name
|
|
|
|
string RecipientAddress:
|
|
|
|
Message recipient address
|
|
|
|
string Type:
|
|
|
|
Message type
|
|
|
|
Possible values: "EMAIL", "SMS_GSM",
|
|
"SMS_CDMA" and "MMS"
|
|
|
|
uint64 Size:
|
|
|
|
Message size in bytes
|
|
|
|
string Status:
|
|
|
|
Message reception status
|
|
|
|
Possible values: "complete",
|
|
"fractioned" and "notification"
|
|
|
|
boolean Priority:
|
|
|
|
Message priority flag
|
|
|
|
boolean Read:
|
|
|
|
Message read flag
|
|
|
|
boolean Sent:
|
|
|
|
Message sent flag
|
|
|
|
boolean Protected:
|
|
|
|
Message protected flag
|
|
|
|
void UpdateInbox(void)
|
|
|
|
Request remote to update its inbox.
|
|
|
|
|
|
Filter: uint16 Offset:
|
|
|
|
Offset of the first item, default is 0
|
|
|
|
uint16 MaxCount:
|
|
|
|
Maximum number of items, default is 1024
|
|
|
|
array{string} Fields:
|
|
|
|
Message fields, default is all values.
|
|
|
|
Possible values can be query with ListFilterFields.
|
|
|
|
array{string} Types:
|
|
|
|
Filter messages by type.
|
|
|
|
Possible values: "sms", "email", "mms".
|
|
|
|
string PeriodBegin:
|
|
|
|
Filter messages by starting period.
|
|
|
|
Possible values: Date in "YYYYMMDDTHHMMSS" format.
|
|
|
|
string PeriodEnd:
|
|
|
|
Filter messages by ending period.
|
|
|
|
Possible values: Date in "YYYYMMDDTHHMMSS" format.
|
|
|
|
boolean Read:
|
|
|
|
Filter messages by read flag.
|
|
|
|
Possible values: True for read or False for unread
|
|
|
|
string Recipient:
|
|
|
|
Filter messages by recipient address.
|
|
|
|
string Sender:
|
|
|
|
Filter messages by sender address.
|
|
|
|
gboolean Priority:
|
|
|
|
Filter messages by priority flag.
|
|
|
|
Possible values: True for high priority or False for
|
|
non-high priority
|
|
|
|
Message hierarchy
|
|
=================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.Message
|
|
Object path [variable prefix]/{session0,session1,...}/{message0,...}
|
|
|
|
Methods object, dict Get(string targetfile, boolean attachment)
|
|
|
|
Download message and store it in the target file.
|
|
|
|
If an empty target file is given, a temporary file
|
|
will be automatically generated.
|
|
|
|
The returned path represents the newly created transfer,
|
|
which should be used to find out if the content has been
|
|
successfully transferred or if the operation fails.
|
|
|
|
The properties of this transfer are also returned along
|
|
with the object path, to avoid a call to GetProperties.
|
|
|
|
Properties string Subject [readonly]
|
|
|
|
Message subject
|
|
|
|
string Timestamp [readonly]
|
|
|
|
Message timestamp
|
|
|
|
string Sender [readonly]
|
|
|
|
Message sender name
|
|
|
|
string SenderAddress [readonly]
|
|
|
|
Message sender address
|
|
|
|
string ReplyTo [readonly]
|
|
|
|
Message Reply-To address
|
|
|
|
string Recipient [readonly]
|
|
|
|
Message recipient name
|
|
|
|
string RecipientAddress [readonly]
|
|
|
|
Message recipient address
|
|
|
|
string Type [readonly]
|
|
|
|
Message type
|
|
|
|
Possible values: "EMAIL", "SMS_GSM",
|
|
"SMS_CDMA" and "MMS"
|
|
|
|
uint64 Size [readonly]
|
|
|
|
Message size in bytes
|
|
|
|
string Status [readonly]
|
|
|
|
Message reception status
|
|
|
|
Possible values: "complete",
|
|
"fractioned" and "notification"
|
|
|
|
boolean Priority [readonly]
|
|
|
|
Message priority flag
|
|
|
|
boolean Read [read/write]
|
|
|
|
Message read flag
|
|
|
|
boolean Deleted [writeonly]
|
|
|
|
Message read flag
|
|
|
|
boolean Sent [readonly]
|
|
|
|
Message sent flag
|
|
|
|
boolean Protected [readonly]
|
|
|
|
Message protected flag
|
|
|
|
|
|
Transfer hierarchy
|
|
==================
|
|
|
|
Service org.bluez.obex
|
|
Interface org.bluez.obex.Transfer
|
|
Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
|
|
|
|
Methods dict GetProperties()
|
|
|
|
Returns all properties for the transfer. See the
|
|
properties section for available properties.
|
|
|
|
void Cancel()
|
|
|
|
Cancels this transfer.
|
|
|
|
Properties string Name [readonly]
|
|
|
|
Name of the transferred object.
|
|
|
|
uint64 Size [readonly]
|
|
|
|
Size of the transferred object. If the size is
|
|
unknown, then this property will not be present.
|
|
|
|
string Filename [readonly, optional]
|
|
|
|
Complete name of the file being received or sent.
|
|
|
|
uint64 Progress [readonly, optional]
|
|
|
|
Number of bytes transferred. For queued transfers, this
|
|
value will not be present.
|
|
|
|
Signals PropertyChanged(string name, variant value)
|
|
|
|
This signal indicates a changed value of the given
|
|
property.
|
|
|
|
void Complete()
|
|
|
|
Informs that the transfer has completed successfully.
|
|
|
|
void Error(string code, string message)
|
|
|
|
Informs that the transfer has been terminated because
|
|
of some error.
|