path: root/doc/client-api.txt

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.client
Interface	org.bluez.obex.Client
Object path	/

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.client
Interface	org.bluez.obex.Session
Object path	[variable prefix]/{session0,session1,...}

Methods		dict GetProperties()

			Returns all properties for the session.

		string GetCapabilities()

			Get remote device capabilities.

Properties	string Source [readonly]

		string Destination [readonly]

		byte Channel [readonly]

Object Push hierarchy
=====================

Service		org.bluez.obex.client
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.client
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.client
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)

			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.

		array{string vcard, string name} List()

			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"

		object, dict Pull(string vcard, string targetfile)

			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.

		array{string vcard, string name}
		Search(string field, string value)

			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

		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).

		void SetFormat(string format)

			Indicate the format of the vcard that should be return
			by related methods.

			format : { "vcard21" (default) | "vcard30" }

		void SetOrder(string order)

			Indicate the sorting method of the vcard-listing data
			returned by List and Search methods.

			order : { "indexed" (default) | "alphanumeric" |
					"phonetic" }

		void SetFilter(array{string})

			Indicate fields that should be contained in vcards
			return by related methods.

			Give an empty array will clear the filter and return
			all fields available in vcards. And this is the default
			behavior.

			Possible filter fields : "VERSION", "FN", ..., "ALL",
			"bit[0-63]"

		array{string} ListFilterFields()

			Return All Available fields that can be used in
			SetFilter method.

		array{string} GetFilter()

			Return the current filter setting

Synchronization hierarchy
=======================

Service		org.bluez.obex.client
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.client
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} GetFolderListing(dict filter)

			Returns a dictionary containing information about
			the current folder content.

			The following keys are defined:

				string Name : Folder name

		array{object, dict} GetMessageListing(string folder,
								dict filter)

			Returns an array containing the messages found in the
			given folder.

			Each message is represented by an object path followed
			by a dictionary of the properties.

			Properties:

				string Handle:

					Message handle

				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

Message hierarchy
=================

Service		org.bluez.obex.client
Interface	org.bluez.obex.Message
Object path	[variable prefix]/{session0,session1,...}/{message0,...}

Methods		object, dict Get(string targetfile)

			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.

Transfer hierarchy
==================

Service		org.bluez.obex.client
Interface	org.bluez.obex.Transfer
Object path	[variable prefix]/{transfer0,transfer1,...}

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.