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
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
Hi Mikel,
On Thu, Nov 24, 2011 at 4:08 PM, Mikel Astiz <[email protected]> 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
Hi Mikel, Vinicius,
On Thu, Nov 24, 2011 at 8:24 PM, Vinicius Costa Gomes
<[email protected]> 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
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 [email protected]
> More majordomo info at http://vger.kernel.org/majordomo-info.html
Cheers,
--
Vinicius
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 [email protected]
> More majordomo info at http://vger.kernel.org/majordomo-info.html
Cheers,
--
Vinicius
---
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
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
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
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
---
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
---
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
---
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
---
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
---
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
---
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 <[email protected]>
+Copyright (C) 2011 BMW Car IT GmbH. All rights reserved.
Client hierarchy
--
1.7.6.4
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
Hi Mikel,
On Thu, Nov 24, 2011 at 4:08 PM, Mikel Astiz <[email protected]> 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