Skip to contentSkip to conversation

doc/obex-api: Update documentation

PATCH In review Ajay Kishore 2 participants 4 messages Dec 16, 2019 – Dec 24, 2019 Bluetooth drivers

lore
Share & tools
lore
#0 lore raw

PATCH 6/6 doc/obex-api: Update documentation

This adds documentation with the conversation listing feature

---
 doc/obex-api.txt | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
doc/obex-api.txt +65 -0
index f39355a..9a76159 100644
@@ -712,6 +712,71 @@ Methods		void SetFolder(string name)
 			Possible errors: org.bluez.obex.Error.InvalidArguments
 					 org.bluez.obex.Error.Failed
 
+
+
+		array{object, dict} listconversations(string folder, dict filter)
+			Returns an array containing the conversations found in the
+			given subfolder of the current folder, or in the current
+			folder if folder is empty.
+
+			Possible Filters: LastActivityBegin, LastActivityEnd,
+			ReadStatus, Recipient
+
+
+			Properties:
+
+				string id:
+
+					Conversation unique identification
+
+				string name:
+
+					Conversation name
+
+				string last_activity:
+
+					Conversation timestamp for the last activity
+
+				boolean read_status:
+
+					Conversation read flag
+
+				string version_counter:
+
+					128 bits version counter.
+					The ‘Conversation-Listing Version Counter’,
+					‘Conversation Version Counter’, and ‘Folder
+					Version Counter’ are used to detect if something
+					has changed
+
+				string summary:
+
+					Conversation summary
+
+				string display:
+
+					Conversation participants name
+
+				string chat_state:
+
+					Conversation current chat state of the participants
+
+				string presence_availability:
+
+					Conversation  participants availability
+
+				string presence_text:
+
+					User defined status of the conversation
+
+				uint16 priority:
+
+					Conversation participant priority
+
+			Possible errors: org.bluez.obex.Error.InvalidArguments
+					 org.bluez.obex.Error.Failed
+
+
 		void UpdateInbox(void)
 
 			Request remote to update its inbox.
Signature · 1 line
2.7.4
#1 lore raw

PATCH v2 5/5 obexd: Handle MAP Event Report v1.1 and v1.2

Changes made to add handler function for the corresponding events mentioned in extended event reports 1.1 and 1.2.

---
 obexd/client/map-event.h |  8 +++++++-
 obexd/client/map.c       | 19 +++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)
obexd/client/map-event.h +7 -1
index 5414b26..c41bb67 100644
@@ -32,7 +32,13 @@ enum map_event_type {
 	MAP_ET_MEMORY_FULL,
 	MAP_ET_MEMORY_AVAILABLE,
 	MAP_ET_MESSAGE_DELETED,
-	MAP_ET_MESSAGE_SHIFT
+	MAP_ET_MESSAGE_SHIFT,
+	MAP_ET_READ_STATUS_CHANGED,
+	MAP_ET_MESSAGE_REMOVED,
+	MAP_ET_MESSAGE_EXTENDED_DATA_CHANGED,
+	MAP_ET_PARTICIPANT_PRESENCE_CHANGED,
+	MAP_ET_PARTICIPANT_CHAT_STATE_CHANGED,
+	MAP_ET_CONVERSATION_CHANGED
 };
 
 struct map_event {
obexd/client/map.c +19 -0
index b65131a..846794f 100644
@@ -2550,6 +2550,12 @@ static void map_handle_folder_changed(struct map_data *map,
 								"Folder");
 }
 
+static void map_handle_remove_message(struct map_data *map,
+						struct map_event *event)
+{
+	g_hash_table_remove(map->messages, &event->handle);
+}
+
 static void map_handle_notification(struct map_event *event, void *user_data)
 {
 	struct map_data *map = user_data;
@@ -2582,6 +2588,19 @@ static void map_handle_notification(struct map_event *event, void *user_data)
 	case MAP_ET_MESSAGE_SHIFT:
 		map_handle_folder_changed(map, event, event->folder);
 		break;
+	case MAP_ET_READ_STATUS_CHANGED:
+		map_handle_status_changed(map, event, "read");
+		break;
+	case MAP_ET_MESSAGE_REMOVED:
+		map_handle_remove_message(map, event);
+		break;
+	case MAP_ET_MESSAGE_EXTENDED_DATA_CHANGED:
+		map_handle_status_changed(map, event,
+					"message-extended-data-changed");
+		break;
+	case MAP_ET_PARTICIPANT_PRESENCE_CHANGED:
+	case MAP_ET_PARTICIPANT_CHAT_STATE_CHANGED:
+	case MAP_ET_CONVERSATION_CHANGED:
 	case MAP_ET_MEMORY_FULL:
 	case MAP_ET_MEMORY_AVAILABLE:
 	default:
Signature · 1 line
2.7.4
#2 lore raw
In reply to Ajay Kishore

Hi Ajay,

Quoted 13 lines · Ajay Kishore

This adds documentation with the conversation listing feature

---
 doc/obex-api.txt | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
doc/obex-api.txt +0 -0
index f39355a..9a76159 100644

doc/obex-api.txt Methods void SetFolder(string name) · line 717

Quoted 6 lines
doc/obex-api.txt +3 -0
@@ -712,6 +712,71 @@ Methods            void SetFolder(string name)
                        Possible errors: org.bluez.obex.Error.InvalidArguments
                                         org.bluez.obex.Error.Failed
 
+
+
+               array{object, dict} listconversations(string folder, dict filter)

It should have been ListConversations to adhere with our D-Bus APIs, but read bellow.

doc/obex-api.txt Methods void SetFolder(string name) · line 723

Quoted 6 lines
doc/obex-api.txt +6 -0
+                       Returns an array containing the conversations found in the
+                       given subfolder of the current folder, or in the current
+                       folder if folder is empty.
+
+                       Possible Filters: LastActivityBegin, LastActivityEnd,
+                       ReadStatus, Recipient

So here is the big design question, why hasn't this been done as a filter to ListMessages? We could just have a couple of different properties to indicate it is a conversation rather than a single message, in any case we would need something like org.bluez.obex.Conversation1 to enumerate these objects, something that is not documented here.

Quoted 61 lines
doc/obex-api.txt +55 -1
+
+                       Properties:
+
+                               string id:
+
+                                       Conversation unique identification
+
+                               string name:
+
+                                       Conversation name
+
+                               string last_activity:
+
+                                       Conversation timestamp for the last activity
+
+                               boolean read_status:
+
+                                       Conversation read flag
+
+                               string version_counter:
+
+                                       128 bits version counter.
+                                       The ‘Conversation-Listing Version Counter’,
+                                       ‘Conversation Version Counter’, and ‘Folder
+                                       Version Counter’ are used to detect if something
+                                       has changed
+
+                               string summary:
+
+                                       Conversation summary
+
+                               string display:
+
+                                       Conversation participants name
+
+                               string chat_state:
+
+                                       Conversation current chat state of the participants
+
+                               string presence_availability:
+
+                                       Conversation  participants availability
+
+                               string presence_text:
+
+                                       User defined status of the conversation
+
+                               uint16 priority:
+
+                                       Conversation participant priority
+
+                       Possible errors: org.bluez.obex.Error.InvalidArguments
+                                        org.bluez.obex.Error.Failed
+
+
                void UpdateInbox(void)
 
                        Request remote to update its inbox.
--

2.7.4

Signature · 1 line
Luiz Augusto von Dentz
#3 lore raw

Hi Luiz,

Quoted 29 lines

-----Original Message-----
From: [email protected] <linux-bluetooth- [email protected]> On Behalf Of Luiz Augusto von Dentz
Sent: Wednesday, December 18, 2019 5:44 AM
To: Kishore, Ajay <[email protected]>
Cc: [email protected]
Subject: Re: [PATCH 6/6] doc/obex-api: Update documentation

Hi Ajay,

Quoted 17 lines · Ajay Kishore

This adds documentation with the conversation listing feature

---
 doc/obex-api.txt | 65
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
doc/obex-api.txt index renamed from doc/obex-api.txt +0 -0

f39355a..9a76159 100644

doc/obex-api.txt +0 -0
@@ -712,6 +712,71 @@ Methods            void SetFolder(string name)
                        Possible errors: org.bluez.obex.Error.InvalidArguments
                                         org.bluez.obex.Error.Failed
 
Quoted 7 lines

doc/obex-api.txt Methods void SetFolder(string name)

Quoted 4 lines
doc/obex-api.txt +4 -0
+
+
+               array{object, dict} listconversations(string folder,
+ dict filter)

It should have been ListConversations to adhere with our D-Bus APIs, but read bellow.

Fixed and pushed in the new patch ([PATCH v2 6/6] doc/obex-api: Update documentation).

Quoted 8 lines

doc/obex-api.txt Methods void SetFolder(string name) · line 723

Quoted 7 lines
doc/obex-api.txt +6 -0
+                       Returns an array containing the conversations found in the
+                       given subfolder of the current folder, or in the current
+                       folder if folder is empty.
+
+                       Possible Filters: LastActivityBegin, LastActivityEnd,
+                       ReadStatus, Recipient
Quoted 6 lines

So here is the big design question, why hasn't this been done as a filter to ListMessages? We could just have a couple of different properties to indicate it is a conversation rather than a single message, in any case we would need something like
org.bluez.obex.Conversation1 to enumerate these objects, something that is not documented here.

I Agree that the few properties are similar in ListMessages and ListConversations functions and can be implemented to just add few new properties.
But we thought to implement both these functions separately as in MAP specification also it is separated.
Also with this implementation it will easier to develop separate application for both the feature.
In the current implementation we are using org.bluez.obex.Conversation1 interface to enumerate and it is updated in the new patch ([PATCH v2 6/6] doc/obex-api: Update documentation).

Quoted 65 lines
Quoted 65 lines
doc/obex-api.txt +61 -0
+
+                       Properties:
+
+                               string id:
+
+                                       Conversation unique
+ identification
+
+                               string name:
+
+                                       Conversation name
+
+                               string last_activity:
+
+                                       Conversation timestamp for the
+ last activity
+
+                               boolean read_status:
+
+                                       Conversation read flag
+
+                               string version_counter:
+
+                                       128 bits version counter.
+                                       The ‘Conversation-Listing Version Counter’,
+                                       ‘Conversation Version Counter’, and ‘Folder
+                                       Version Counter’ are used to detect if something
+                                       has changed
+
+                               string summary:
+
+                                       Conversation summary
+
+                               string display:
+
+                                       Conversation participants name
+
+                               string chat_state:
+
+                                       Conversation current chat
+ state of the participants
+
+                               string presence_availability:
+
+                                       Conversation  participants
+ availability
+
+                               string presence_text:
+
+                                       User defined status of the
+ conversation
+
+                               uint16 priority:
+
+                                       Conversation participant
+ priority
+
+                       Possible errors: org.bluez.obex.Error.InvalidArguments
+                                        org.bluez.obex.Error.Failed
+
+
                void UpdateInbox(void)
Quoted 8 lines
Quoted 4 lines

Request remote to update its inbox.
--
2.7.4

--
Luiz Augusto von Dentz

Thanks.
Ajay Kishore