[RFC obexd 00/10] Major API changes in obex-client

[RFC obexd 00/10] Major API changes in obex-client

[Mikel Astiz]

This patch series splits the perviously proposed obex-client API into incremental changes. The goal is to agree on the desired API before starting with the implementation.

There are some differences with respect to the previous proposal, mainly:

- The representation of devices has been dropped for now and considered of lower priority.

- Progress-reporting signals are not defined as unicast signals, assuming that the perfomance overhead might not be significant.

- Some operations such as PhonebookAccess.List have not been changed either, although it would be possible (as included in the previous proposal) to also use a file-based transfer here.

Also note that the Transfer interface has been left inside the client-specific API, but would ideally be shared with the server. This is something to be kept in mind now in the design of the API.

Mikel Astiz (10):
  client-doc: reformatted to fit in 80 columns
  client-doc: copyright statement added
  client-doc: minor formatting changes
  client-doc: wrap OPP into specific session type
  client-doc: replace parameter dict with conventional ones
  client-doc: remove agent in favour of transfer signals
  client-doc: ObjectPush sessions return transports
  client-doc: FileTransfer sessions return transports
  client-doc: PhonebookAccess sessions return transports
  client-doc: Synchronization sessions return transports

 doc/client-api.txt |  265 +++++++++++++++++++++++++++++-----------------------
 1 files changed, 148 insertions(+), 117 deletions(-)

-- 
1.7.6.4

[RFC obexd 01/10] client-doc: reformatted to fit in 80 columns

[Mikel Astiz]

---
 doc/client-api.txt |   56 +++++++++++++++++++++++++++++++--------------------
 1 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index 3e61cf7..476ebfd 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -22,7 +22,8 @@ Methods		void SendFiles(dict device, array{string} files, object agent)
 			Request the business card from a remote device and
 			store it in the local file.
 
-		void ExchangeBusinessCards(dict device, string clientfile, string file)
+		void ExchangeBusinessCards(dict device, string clientfile,
+								string file)
 
 			Push the client's business card to the remote device
 			and then retrieve the remote business card and store
@@ -101,8 +102,10 @@ Methods		void ChangeFolder(string folder)
 
 				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 Size : Object size or number of items in
+						folder
+				string Permission : Group, owner and other
+							permission
 				guint64 Modified : Last change
 				guint64 Accessed : Last access
 				guint64 Created : Creation date
@@ -150,7 +153,8 @@ 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 :
+			location : Where the phonebook is stored, possible
+			inputs :
 				"INT" ( "INTERNAL" which is default )
 				"SIM" ( "SIM1" )
 				"SIM2"
@@ -171,7 +175,8 @@ Methods		void Select(string location, string phonebook)
 		array{string vcard, string name} List()
 
 			Return an array of vcard-listing data which contains the
-			vcard : name paired string, for example "1.vcf" : "John".
+			vcard : name paired string, for example "1.vcf" :
+				"John".
 
 		string Pull(string vcard)
 
@@ -190,36 +195,40 @@ Methods		void Select(string location, string phonebook)
 
 		uint16 GetSize()
 
-			Return the number of the non-null entries in the selected
-			phonebook object.
+			Return the number of the non-null entries in the
+			selected phonebook object.
 
 		void SetFormat(string format)
 
-			Indicate the format of the vcard that should be return by
-			related methods.
+			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.
+			Indicate the sorting method of the vcard-listing data
+			returned by List and Search methods.
 
-			order : { "indexed" (default) | "alphanumeric" | "phonetic" }
+			order : { "indexed" (default) | "alphanumeric" |
+					"phonetic" }
 
 		void SetFilter(array{string})
 
-			Indicate fields that should be contained in vcards return by
-			related methods.
+			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.
+			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]"
+			Possible filter fields : "VERSION", "FN", ..., "ALL",
+			"bit[0-63]"
 
 		array{string} ListFilterFields()
 
-			Return All Available fields that can be used in SefFilter method.
+			Return All Available fields that can be used in
+			SefFilter method.
 
 		array{string} GetFilter()
 
@@ -234,10 +243,12 @@ 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.
+			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:
+			location: Where the phonebook is stored, possible
+			values:
 				"INT" ( "INTERNAL" which is default )
 				"SIM1"
 				"SIM2"
@@ -245,7 +256,8 @@ Methods		void SetLocation(string location)
 
 		string GetPhonebook()
 
-			Retrieve an entire Phonebook Object store from remote device
+			Retrieve an entire Phonebook Object store from remote
+			device
 
 		void PutPhonebook(string obj)
 
-- 
1.7.6.4

[RFC obexd 02/10] client-doc: copyright statement added

[Mikel Astiz]

---
 doc/client-api.txt |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index 476ebfd..e6f8270 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -2,6 +2,7 @@ OBEX client API description
 ***************************
 
 Copyright (C) 2007-2010  Marcel Holtmann <marcel@holtmann.org>
+Copyright (C) 2011  BMW Car IT GmbH. All rights reserved.
 
 
 Client hierarchy
-- 
1.7.6.4

[RFC obexd 03/10] client-doc: minor formatting changes

[Mikel Astiz]

---
 doc/client-api.txt |   22 +++++++++-------------
 1 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index e6f8270..304e489 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -51,7 +51,6 @@ Properties	string Target
 
 		byte Channel
 
-
 Session hierarchy
 =================
 
@@ -72,12 +71,11 @@ Methods		dict GetProperties()
 
 			Release a previously assigned OBEX agent.
 
-Properties	string Source [read-only]
-
-		string Destination [read-only]
+Properties	string Source [readonly]
 
-		byte Channel [read-only]
+		string Destination [readonly]
 
+		byte Channel [readonly]
 
 File Transfer hierarchy
 =======================
@@ -107,9 +105,9 @@ Methods		void ChangeFolder(string folder)
 						folder
 				string Permission : Group, owner and other
 							permission
-				guint64 Modified : Last change
-				guint64 Accessed : Last access
-				guint64 Created : Creation date
+				uint64 Modified : Last change
+				uint64 Accessed : Last access
+				uint64 Created : Creation date
 
 		void GetFile(string targetfile, string sourcefile)
 
@@ -141,7 +139,6 @@ Methods		void ChangeFolder(string folder)
 
 			Deletes the specified file/folder.
 
-
 Phonebook Access hierarchy
 =======================
 
@@ -280,20 +277,19 @@ Methods		dict GetProperties()
 
 			Cancels this transfer.
 
-Properties	string Name [read-only]
+Properties	string Name [readonly]
 
 			Name of the transferred object.
 
-		uint64 Size [read-only]
+		uint64 Size [readonly]
 
 			Size of the transferred object. If the size is
 			unknown, then this property will not be present.
 
-		string Filename [read-only]
+		string Filename [readonly]
 
 			Complete name of the file being received or sent.
 
-
 Agent hierarchy
 ===============
 
-- 
1.7.6.4

[RFC obexd 04/10] client-doc: wrap OPP into specific session type

[Mikel Astiz]

This modification makes the OPP API more consistent with the rest of the
supported target types, and also it allows to perform several operations
on the same session.
---
 doc/client-api.txt |   44 +++++++++++++++++++++++++-------------------
 1 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index 304e489..a6f30af 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -12,25 +12,7 @@ Service		org.openobex.client
 Interface	org.openobex.Client
 Object path	/
 
-Methods		void SendFiles(dict device, array{string} files, object agent)
-
-			Send one or multiple local files to the specified
-			device. The device is configured via properties. At
-			least the Destination property should be specified.
-
-		void PullBusinessCard(dict device, string file)
-
-			Request the business card from a remote device and
-			store it in the local file.
-
-		void ExchangeBusinessCards(dict device, string clientfile,
-								string file)
-
-			Push the client's business card to the remote device
-			and then retrieve the remote business card and store
-			it in a local file.
-
-		object CreateSession(dict device)
+Methods		object CreateSession(dict device)
 
 			Create a new OBEX session. The device is configured
 			via properties like in SendFiles.
@@ -77,6 +59,30 @@ Properties	string Source [readonly]
 
 		byte Channel [readonly]
 
+Object Push hierarchy
+=====================
+
+Service		org.openobex.client
+Interface	org.openobex.ObjectPush
+Object path	[variable prefix]/{session0,session1,...}
+
+Methods		void SendFiles(array{string} files, string destination,
+								object agent)
+
+			Send one or multiple local files to the remote device,
+			and the given destination.
+
+		void PullBusinessCard(string targetfile)
+
+			Request the business card from a remote device and
+			store it in the local file.
+
+		void 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.
+
 File Transfer hierarchy
 =======================
 
-- 
1.7.6.4

[RFC obexd 05/10] client-doc: replace parameter dict with conventional ones

[Mikel Astiz]

The usage of a dictionary as a parameter passing mechanism seems not to
be necessary any more.
---
 doc/client-api.txt |   22 ++++++++++------------
 1 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index a6f30af..67355c6 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -12,27 +12,25 @@ Service		org.openobex.client
 Interface	org.openobex.Client
 Object path	/
 
-Methods		object CreateSession(dict device)
+Methods		object CreateSession(string source, string destination,
+					string target)
 
-			Create a new OBEX session. The device is configured
-			via properties like in SendFiles.
+			Create a new OBEX session for the given source (local)
+			address, destination (remote) address and target. The
+			supported target values are:
+				- "OPP"
+				- "FTP"
+				- "SYNC"
+				- "PBAP"
 
 		void RemoveSession(object session)
 
 			Unregister session and abort pending transfers.
 
-		string GetCapabilities(dict device)
+		string GetCapabilities(string source, string destination)
 
 			Get remote device capabilities.
 
-Properties	string Target
-
-		string Source
-
-		string Destination
-
-		byte Channel
-
 Session hierarchy
 =================
 
-- 
1.7.6.4

Re: [RFC obexd 05/10] client-doc: replace parameter dict with conventional ones

[Vinicius Costa Gomes]

Hi Mikel,

On 15:08 Thu 24 Nov, Mikel Astiz wrote:
> The usage of a dictionary as a parameter passing mechanism seems not to
> be necessary any more.
> ---
>  doc/client-api.txt |   22 ++++++++++------------
>  1 files changed, 10 insertions(+), 12 deletions(-)
> 
> diff --git a/doc/client-api.txt b/doc/client-api.txt
> index a6f30af..67355c6 100644
> --- a/doc/client-api.txt
> +++ b/doc/client-api.txt
> @@ -12,27 +12,25 @@ Service		org.openobex.client
>  Interface	org.openobex.Client
>  Object path	/
>  
> -Methods		object CreateSession(dict device)
> +Methods		object CreateSession(string source, string destination,
> +					string target)
>  
> -			Create a new OBEX session. The device is configured
> -			via properties like in SendFiles.
> +			Create a new OBEX session for the given source (local)
> +			address, destination (remote) address and target. The
> +			supported target values are:
> +				- "OPP"
> +				- "FTP"
> +				- "SYNC"
> +				- "PBAP"
>  
>  		void RemoveSession(object session)
>  
>  			Unregister session and abort pending transfers.
>  
> -		string GetCapabilities(dict device)
> +		string GetCapabilities(string source, string destination)
>  
>  			Get remote device capabilities.
>  
> -Properties	string Target
> -
> -		string Source
> -
> -		string Destination
> -
> -		byte Channel

I just wanted to say that for most of the cases doing the SDP seach 
always is the right thing to do, but sometimes you want to avoid it.

I agree that for now we can leave it, but it would be nice if there
was a way to add it later if we ever need it.

> -
>  Session hierarchy
>  =================
>  
> -- 
> 1.7.6.4
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Cheers,
-- 
Vinicius

Re: [RFC obexd 05/10] client-doc: replace parameter dict with conventional ones

[Luiz Augusto von Dentz]

Hi Mikel, Vinicius,

On Thu, Nov 24, 2011 at 8:24 PM, Vinicius Costa Gomes
<vinicius.gomes@openbossa.org> wrote:
> Hi Mikel,
>
> On 15:08 Thu 24 Nov, Mikel Astiz wrote:
>> The usage of a dictionary as a parameter passing mechanism seems not to
>> be necessary any more.
>> ---
>>  doc/client-api.txt |   22 ++++++++++------------
>>  1 files changed, 10 insertions(+), 12 deletions(-)
>>
>> diff --git a/doc/client-api.txt b/doc/client-api.txt
>> index a6f30af..67355c6 100644
>> --- a/doc/client-api.txt
>> +++ b/doc/client-api.txt
>> @@ -12,27 +12,25 @@ Service           org.openobex.client
>>  Interface    org.openobex.Client
>>  Object path  /
>>
>> -Methods              object CreateSession(dict device)
>> +Methods              object CreateSession(string source, string destination,
>> +                                     string target)
>>
>> -                     Create a new OBEX session. The device is configured
>> -                     via properties like in SendFiles.
>> +                     Create a new OBEX session for the given source (local)
>> +                     address, destination (remote) address and target. The
>> +                     supported target values are:
>> +                             - "OPP"
>> +                             - "FTP"
>> +                             - "SYNC"
>> +                             - "PBAP"
>>
>>               void RemoveSession(object session)
>>
>>                       Unregister session and abort pending transfers.
>>
>> -             string GetCapabilities(dict device)
>> +             string GetCapabilities(string source, string destination)
>>
>>                       Get remote device capabilities.
>>
>> -Properties   string Target
>> -
>> -             string Source
>> -
>> -             string Destination
>> -
>> -             byte Channel
>
> I just wanted to say that for most of the cases doing the SDP seach
> always is the right thing to do, but sometimes you want to avoid it.
>
> I agree that for now we can leave it, but it would be nice if there
> was a way to add it later if we ever need it.

IMO it is better to leave as it is because then some parameters can be
omitted such as adapter and target, and it also easier to extend if we
need other parameters e.g. WHO header without breaking the signature.


-- 
Luiz Augusto von Dentz

Re: [RFC obexd 05/10] client-doc: replace parameter dict with conventional ones

[Mikel Astiz]

Hi Luiz, Vinicius,

> IMO it is better to leave as it is because then some parameters can be 
> omitted such as adapter and target, and it also easier to extend if we 
> need other parameters e.g. WHO header without breaking the signature. 

This might be a matter of personal preference, but IMO using a 
dictionary to make an API more flexible is just hiding the problem. I 
don't see why this method has more reasons than any other method to use 
a dictionary instead of well-defined formal parameters.

If the point is that some of the input parameters are optional, I would 
rather propose using empty strings. Again, it's a matter of personal taste.

Besides, I don't understand how the target could be omitted. Could you 
further elaborate on this?

Cheers,
Mikel

[RFC obexd 06/10] client-doc: remove agent in favour of transfer signals

[Mikel Astiz]

Assuming that the request confirmation from the agent is not necessary,
the rest of the reports can be achieved using signals in the transfer
object itself.

The main benefit of this is that the API is simpler and the client apps
do not have to register the agent, and can simply listen to the relevant
signals.
---
 doc/client-api.txt |   67 ++++++++++++---------------------------------------
 1 files changed, 16 insertions(+), 51 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index 67355c6..eb06d6b 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -42,15 +42,6 @@ Methods		dict GetProperties()
 
 			Returns all properties for the session.
 
-		void AssignAgent(object agent)
-
-			Assign an OBEX agent to this session. This allows
-			detailed progress reports about the transactions.
-
-		void ReleaseAgent(object agent)
-
-			Release a previously assigned OBEX agent.
-
 Properties	string Source [readonly]
 
 		string Destination [readonly]
@@ -64,8 +55,7 @@ Service		org.openobex.client
 Interface	org.openobex.ObjectPush
 Object path	[variable prefix]/{session0,session1,...}
 
-Methods		void SendFiles(array{string} files, string destination,
-								object agent)
+Methods		void SendFiles(array{string} files, string destination)
 
 			Send one or multiple local files to the remote device,
 			and the given destination.
@@ -281,58 +271,33 @@ Methods		dict GetProperties()
 
 			Cancels this transfer.
 
-Properties	string Name [readonly]
-
-			Name of the transferred object.
-
-		uint64 Size [readonly]
+Properties	uint64 Size [readonly, optional]
 
-			Size of the transferred object. If the size is
+			Size of the transferred object(s). If the size is
 			unknown, then this property will not be present.
 
-		string Filename [readonly]
-
-			Complete name of the file being received or sent.
-
-Agent hierarchy
-===============
-
-Service		unique name
-Interface	org.openobex.Agent
-Object path	freely definable
-
-Methods		void Release()
-
-			This method gets called when the service daemon
-			unregisters the agent. An agent can use it to do
-			cleanup tasks. There is no need to unregister the
-			agent, because when this method gets called it has
-			already been unregistered.
-
-		string Request(object transfer)
+		string LocalFile [readonly]
 
-			Accept or reject a new transfer (client and server)
-			and provide the filename for it.
+			Complete name of the local file being received or sent.
+			For operations involving several files, this property
+			might change.
 
-			In case of incoming transfers it is the filename
-			where to store the file and for outgoing transfers
-			it is the filename to show the remote device. If left
-			empty it will be calculated automatically.
+Signals		PropertyChanged(string name, variant value)
 
-			Possible errors: org.openobex.Error.Rejected
-			                 org.openobex.Error.Canceled
+			This signal indicates a changed value of the given
+			property.
 
-		void Progress(object transfer, uint64 transferred)
+		void Progress(uint64 transferred)
 
-			Progress within the transfer has been made. The
-			number of transferred bytes is given as second
-			argument for convenience.
+			Progress within the transfer has been made. For
+			operations involving several files, The number of
+			transferred bytes represents the total number of bytes.
 
-		void Complete(object transfer)
+		void Complete()
 
 			Informs that the transfer has completed successfully.
 
-		void Error(object transfer, string message)
+		void Error(string message)
 
 			Informs that the transfer has been terminated because
 			of some error.
-- 
1.7.6.4

Re: [RFC obexd 06/10] client-doc: remove agent in favour of transfer signals

[Luiz Augusto von Dentz]

Hi Mikel,

On Thu, Nov 24, 2011 at 4:08 PM, Mikel Astiz <mikel.astiz@bmw-carit.de> wrote:
> Assuming that the request confirmation from the agent is not necessary,
> the rest of the reports can be achieved using signals in the transfer
> object itself.
>
> The main benefit of this is that the API is simpler and the client apps
> do not have to register the agent, and can simply listen to the relevant
> signals.
> ---
>  doc/client-api.txt |   67 ++++++++++++---------------------------------------
>  1 files changed, 16 insertions(+), 51 deletions(-)
>
> diff --git a/doc/client-api.txt b/doc/client-api.txt
> index 67355c6..eb06d6b 100644
> --- a/doc/client-api.txt
> +++ b/doc/client-api.txt
> @@ -42,15 +42,6 @@ Methods              dict GetProperties()
>
>                        Returns all properties for the session.
>
> -               void AssignAgent(object agent)
> -
> -                       Assign an OBEX agent to this session. This allows
> -                       detailed progress reports about the transactions.
> -
> -               void ReleaseAgent(object agent)
> -
> -                       Release a previously assigned OBEX agent.
> -
>  Properties     string Source [readonly]
>
>                string Destination [readonly]
> @@ -64,8 +55,7 @@ Service               org.openobex.client
>  Interface      org.openobex.ObjectPush
>  Object path    [variable prefix]/{session0,session1,...}
>
> -Methods                void SendFiles(array{string} files, string destination,
> -                                                               object agent)
> +Methods                void SendFiles(array{string} files, string destination)
>
>                        Send one or multiple local files to the remote device,
>                        and the given destination.
> @@ -281,58 +271,33 @@ Methods           dict GetProperties()
>
>                        Cancels this transfer.
>
> -Properties     string Name [readonly]
> -
> -                       Name of the transferred object.
> -
> -               uint64 Size [readonly]
> +Properties     uint64 Size [readonly, optional]
>
> -                       Size of the transferred object. If the size is
> +                       Size of the transferred object(s). If the size is
>                        unknown, then this property will not be present.
>
> -               string Filename [readonly]
> -
> -                       Complete name of the file being received or sent.
> -
> -Agent hierarchy
> -===============
> -
> -Service                unique name
> -Interface      org.openobex.Agent
> -Object path    freely definable
> -
> -Methods                void Release()
> -
> -                       This method gets called when the service daemon
> -                       unregisters the agent. An agent can use it to do
> -                       cleanup tasks. There is no need to unregister the
> -                       agent, because when this method gets called it has
> -                       already been unregistered.
> -
> -               string Request(object transfer)
> +               string LocalFile [readonly]

Im not sure why you think LocalFile would suite better here, IMO
Filename is fine, also don't remove the Name as it may not match the
Filename.

-- 
Luiz Augusto von Dentz

[RFC obexd 07/10] client-doc: ObjectPush sessions return transports

[Mikel Astiz]

---
 doc/client-api.txt |   28 +++++++++++++++++++++++++---
 1 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index eb06d6b..5a23c6e 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -55,22 +55,44 @@ Service		org.openobex.client
 Interface	org.openobex.ObjectPush
 Object path	[variable prefix]/{session0,session1,...}
 
-Methods		void SendFiles(array{string} files, string destination)
+Methods		object SendFiles(array{string} files, string destination)
 
 			Send one or multiple local files to the remote device,
 			and the given destination.
 
-		void PullBusinessCard(string targetfile)
+			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.
+
+		object PullBusinessCard(string targetfile)
 
 			Request the business card from a remote device and
 			store it in the local file.
 
-		void ExchangeBusinessCards(string clientfile, string targetfile)
+			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.
+
+			This object will represent the whole list of files in a
+			single transfer.
+
+		object 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.
+
 File Transfer hierarchy
 =======================
 
-- 
1.7.6.4

[RFC obexd 08/10] client-doc: FileTransfer sessions return transports

[Mikel Astiz]

---
 doc/client-api.txt |   17 +++++++++++------
 1 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index 5a23c6e..c6f19ea 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -125,21 +125,26 @@ Methods		void ChangeFolder(string folder)
 				uint64 Accessed : Last access
 				uint64 Created : Creation date
 
-		void GetFile(string targetfile, string sourcefile)
+		object GetFile(string targetfile, string sourcefile)
 
 			Copy the source file (from remote device) to the
 			target file (on local filesystem).
 
-			A new Transfer object is created to represent this
-			transaction.
+			If an empty target file is given, a name will be
+			automatically calculated for the temporary file.
 
-		void PutFile(string sourcefile, string targetfile)
+			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.
+
+		object PutFile(string sourcefile, string targetfile)
 
 			Copy the source file (from local filesystem) to the
 			target file (on remote device).
 
-			A new Transfer object is created to represent this
-			transaction.
+			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.
 
 		void CopyFile(string sourcefile, string targetfile)
 
-- 
1.7.6.4

[RFC obexd 09/10] client-doc: PhonebookAccess sessions return transports

[Mikel Astiz]

---
 doc/client-api.txt |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index c6f19ea..d631cff 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -186,10 +186,18 @@ Methods		void Select(string location, string phonebook)
 				"mch":	missing call history
 				"cch":	combination of ich och mch
 
-		string PullAll()
+		object PullAll(string targetfile)
 
 			Return the entire phonebook object from the PSE server
-			in plain string with vcard format.
+			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.
 
 		array{string vcard, string name} List()
 
@@ -197,10 +205,17 @@ Methods		void Select(string location, string phonebook)
 			vcard : name paired string, for example "1.vcf" :
 				"John".
 
-		string Pull(string vcard)
+		object Pull(string vcard, string targetfile)
 
 			Retrieve the vcard in the current phonebook object
-			for example : Pull("0.vcf")
+			for example : Pull("0.vcf", "pull-result.vcf")
+
+			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.
 
 		array{string vcard, string name}
 		Search(string field, string value)
-- 
1.7.6.4

[RFC obexd 10/10] client-doc: Synchronization sessions return transports

[Mikel Astiz]

---
 doc/client-api.txt |   19 +++++++++++++++----
 1 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/doc/client-api.txt b/doc/client-api.txt
index d631cff..fa9e0cd 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -288,14 +288,25 @@ Methods		void SetLocation(string location)
 				"SIM2"
 				......
 
-		string GetPhonebook()
+		object GetPhonebook(string targetfile)
 
 			Retrieve an entire Phonebook Object store from remote
-			device
+			device, and stores it in a local file.
 
-		void PutPhonebook(string obj)
+			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.
 
-			Send an entire Phonebook Object store to remote device
+		object PutPhonebook(string obj)
+
+			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.
 
 Transfer hierarchy
 ==================
-- 
1.7.6.4

Re: [RFC obexd 00/10] Major API changes in obex-client

[Vinicius Costa Gomes]

Hi Mikel,

On 15:08 Thu 24 Nov, Mikel Astiz wrote:
> This patch series splits the perviously proposed obex-client API into incremental changes. The goal is to agree on the desired API before starting with the implementation.
> 
> There are some differences with respect to the previous proposal, mainly:
> 
> - The representation of devices has been dropped for now and considered of lower priority.
> 
> - Progress-reporting signals are not defined as unicast signals, assuming that the perfomance overhead might not be significant.

I am not so much worried about performance, I am more worried about
waking processes listening in the session bus unecessarily.

The suggested API looks good, I just have some small comments about some
changes.

> 
> - Some operations such as PhonebookAccess.List have not been changed either, although it would be possible (as included in the previous proposal) to also use a file-based transfer here.
> 
> Also note that the Transfer interface has been left inside the client-specific API, but would ideally be shared with the server. This is something to be kept in mind now in the design of the API.
> 
> Mikel Astiz (10):
>   client-doc: reformatted to fit in 80 columns
>   client-doc: copyright statement added
>   client-doc: minor formatting changes
>   client-doc: wrap OPP into specific session type
>   client-doc: replace parameter dict with conventional ones
>   client-doc: remove agent in favour of transfer signals
>   client-doc: ObjectPush sessions return transports
>   client-doc: FileTransfer sessions return transports
>   client-doc: PhonebookAccess sessions return transports
>   client-doc: Synchronization sessions return transports
> 
>  doc/client-api.txt |  265 +++++++++++++++++++++++++++++-----------------------
>  1 files changed, 148 insertions(+), 117 deletions(-)
> 
> -- 
> 1.7.6.4
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Cheers,
-- 
Vinicius

Re: [RFC obexd 00/10] Major API changes in obex-client

[Luiz Augusto von Dentz]

Hi Mikel,

On Thu, Nov 24, 2011 at 4:08 PM, Mikel Astiz <mikel.astiz@bmw-carit.de> wrote:
> This patch series splits the perviously proposed obex-client API into incremental changes. The goal is to agree on the desired API before starting with the implementation.
>
> There are some differences with respect to the previous proposal, mainly:
>
> - The representation of devices has been dropped for now and considered of lower priority.
>
> - Progress-reporting signals are not defined as unicast signals, assuming that the perfomance overhead might not be significant.
>
> - Some operations such as PhonebookAccess.List have not been changed either, although it would be possible (as included in the previous proposal) to also use a file-based transfer here.
>
> Also note that the Transfer interface has been left inside the client-specific API, but would ideally be shared with the server. This is something to be kept in mind now in the design of the API.
>
> Mikel Astiz (10):
>  client-doc: reformatted to fit in 80 columns
>  client-doc: copyright statement added
>  client-doc: minor formatting changes
>  client-doc: wrap OPP into specific session type
>  client-doc: replace parameter dict with conventional ones
>  client-doc: remove agent in favour of transfer signals
>  client-doc: ObjectPush sessions return transports
>  client-doc: FileTransfer sessions return transports
>  client-doc: PhonebookAccess sessions return transports
>  client-doc: Synchronization sessions return transports
>
>  doc/client-api.txt |  265 +++++++++++++++++++++++++++++-----------------------
>  1 files changed, 148 insertions(+), 117 deletions(-)
>

I will be doing some cleanups before we integrate this code, some are
based on your mega patch that  you have sent (actually it never made
to the list due to its size), but I would like to separate the
transport code to modules e.g. bluetooth like we did for obexd so the
session just call e.g. .connect/.disconnect and the driver takes care
of the transport details such as requesting a session and discovering
records, this should simplify quite a lot session.c

The only problem is how we gonna interpret the address, by default it
should be Bluetooth but perhaps we should support urls for other
transport e.g. usb://, how about that?

-- 
Luiz Augusto von Dentz

Re: [RFC obexd 00/10] Major API changes in obex-client

[Mikel Astiz]

Hi Luiz,

> I will be doing some cleanups before we integrate this code, some are
> based on your mega patch that  you have sent (actually it never made
> to the list due to its size), but I would like to separate the
> transport code to modules e.g. bluetooth like we did for obexd so the
> session just call e.g. .connect/.disconnect and the driver takes care
> of the transport details such as requesting a session and discovering
> records, this should simplify quite a lot session.c

I agree it would be convenient to have a simplified session.c. Right now 
there is definitely too much in there.

I am about to finish a split of the mega-patch you mention, trying to 
separate the internal changes from the dbus-related changes, as we 
discussed. You may want to wait until I send this new proposal.

> The only problem is how we gonna interpret the address, by default it
> should be Bluetooth but perhaps we should support urls for other
> transport e.g. usb://, how about that?

Sounds fine to me.

Cheers,
Mikel