Line data Source code
1 : /*
2 : * Copyright (C) 2004-2026 Savoir-faire Linux Inc.
3 : *
4 : * This program is free software: you can redistribute it and/or modify
5 : * it under the terms of the GNU General Public License as published by
6 : * the Free Software Foundation, either version 3 of the License, or
7 : * (at your option) any later version.
8 : *
9 : * This program is distributed in the hope that it will be useful,
10 : * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 : * GNU General Public License for more details.
13 : *
14 : * You should have received a copy of the GNU General Public License
15 : * along with this program. If not, see <https://www.gnu.org/licenses/>.
16 : */
17 :
18 : #ifndef LIBJAMI_CONVERSATIONI_H
19 : #define LIBJAMI_CONVERSATIONI_H
20 :
21 : #include "def.h"
22 :
23 : #include <vector>
24 : #include <map>
25 : #include <string>
26 : #include <cstdint>
27 :
28 : namespace libjami {
29 :
30 : struct SwarmMessage
31 : {
32 : std::string id;
33 : std::string type;
34 : std::string linearizedParent;
35 : std::map<std::string, std::string> body;
36 : std::vector<std::map<std::string, std::string>> reactions;
37 : std::vector<std::map<std::string, std::string>> editions;
38 : std::map<std::string, int32_t> status;
39 : // Extra attributes written by plugins (e.g. {"bodyOverwrite": "..."}).
40 : // Never stored to git — local display only.
41 : std::map<std::string, std::string> pluginData;
42 : // Id of the edition commit that last set the current body (empty = no editions yet).
43 : // Used to correctly tag superseded bodies when new editions arrive.
44 : std::string latestEditionId;
45 :
46 18482 : void fromMapStringString(const std::map<std::string, std::string>& commit)
47 : {
48 36951 : id = commit.at("id");
49 18469 : type = commit.at("type");
50 18467 : body = commit; // TODO erase type/id?
51 18469 : }
52 : };
53 :
54 : // Conversation management
55 : LIBJAMI_PUBLIC std::string startConversation(const std::string& accountId);
56 : LIBJAMI_PUBLIC void acceptConversationRequest(const std::string& accountId, const std::string& conversationId);
57 : LIBJAMI_PUBLIC void declineConversationRequest(const std::string& accountId, const std::string& conversationId);
58 : LIBJAMI_PUBLIC bool removeConversation(const std::string& accountId, const std::string& conversationId);
59 : LIBJAMI_PUBLIC std::vector<std::string> getConversations(const std::string& accountId);
60 : LIBJAMI_PUBLIC std::vector<std::map<std::string, std::string>> getConversationRequests(const std::string& accountId);
61 :
62 : // Calls
63 : LIBJAMI_PUBLIC std::vector<std::map<std::string, std::string>> getActiveCalls(const std::string& accountId,
64 : const std::string& conversationId);
65 :
66 : // Conversation's infos management
67 : LIBJAMI_PUBLIC void updateConversationInfos(const std::string& accountId,
68 : const std::string& conversationId,
69 : const std::map<std::string, std::string>& infos);
70 : LIBJAMI_PUBLIC std::map<std::string, std::string> conversationInfos(const std::string& accountId,
71 : const std::string& conversationId);
72 : LIBJAMI_PUBLIC void setConversationPreferences(const std::string& accountId,
73 : const std::string& conversationId,
74 : const std::map<std::string, std::string>& prefs);
75 : LIBJAMI_PUBLIC std::map<std::string, std::string> getConversationPreferences(const std::string& accountId,
76 : const std::string& conversationId);
77 :
78 : // Member management
79 : LIBJAMI_PUBLIC void addConversationMember(const std::string& accountId,
80 : const std::string& conversationId,
81 : const std::string& contactUri);
82 : LIBJAMI_PUBLIC void removeConversationMember(const std::string& accountId,
83 : const std::string& conversationId,
84 : const std::string& contactUri);
85 : LIBJAMI_PUBLIC std::vector<std::map<std::string, std::string>> getConversationMembers(const std::string& accountId,
86 : const std::string& conversationId);
87 :
88 : // Message send/load
89 : LIBJAMI_PUBLIC void sendMessage(const std::string& accountId,
90 : const std::string& conversationId,
91 : const std::string& message,
92 : const std::string& replyTo,
93 : const int32_t& flag = 0);
94 : LIBJAMI_PUBLIC uint32_t loadConversation(const std::string& accountId,
95 : const std::string& conversationId,
96 : const std::string& fromMessage,
97 : size_t n);
98 : LIBJAMI_PUBLIC uint32_t loadSwarmUntil(const std::string& accountId,
99 : const std::string& conversationId,
100 : const std::string& fromMessage,
101 : const std::string& toMessage);
102 : LIBJAMI_PUBLIC uint32_t countInteractions(const std::string& accountId,
103 : const std::string& conversationId,
104 : const std::string& toId,
105 : const std::string& fromId,
106 : const std::string& authorUri);
107 : LIBJAMI_PUBLIC void clearCache(const std::string& accountId, const std::string& conversationId);
108 : LIBJAMI_PUBLIC uint32_t searchConversation(const std::string& accountId,
109 : const std::string& conversationId,
110 : const std::string& author,
111 : const std::string& lastId,
112 : const std::string& regexSearch,
113 : const std::string& type,
114 : const int64_t& after,
115 : const int64_t& before,
116 : const uint32_t& maxResult,
117 : const int32_t& flag);
118 : LIBJAMI_PUBLIC void reloadConversationsAndRequests(const std::string& accountId);
119 :
120 : /**
121 : * Real-time collaborative editing of a shared document inside a conversation.
122 : *
123 : * The daemon is a transport for Y-CRDT updates, not an editor: it moves opaque
124 : * updates between the clients and the conversation members and stores them, but
125 : * it never interprets what a document contains. A client keeps its own yrs
126 : * replica, produces updates from it and merges the ones it receives through
127 : * ConversationSignal::CollaborativeDocumentUpdate.
128 : *
129 : * Because nothing here is tied to a document type, a client is free to implement
130 : * an editor for any type yrs supports -- text, rich text, maps, arrays, XML
131 : * fragments -- without a change to this API. A document carries the media type
132 : * of what it holds, so a client can tell an unsupported document apart from one
133 : * it should open.
134 : *
135 : * Updates cross this API as the bytes the engine produced. They are binary and
136 : * they are handed over as such: encoding them would inflate every keystroke by a
137 : * third and cost a conversion at each end, for nothing the transports need.
138 : */
139 : LIBJAMI_PUBLIC std::string createCollaborativeDocument(const std::string& accountId,
140 : const std::string& conversationId,
141 : const std::string& name,
142 : const std::string& mimeType);
143 : /**
144 : * Open a document and get its whole state as a single Y-CRDT update. Apply it to
145 : * a fresh replica to obtain the current document.
146 : *
147 : * @return the state, never empty: a document that holds nothing still encodes as
148 : * a short, valid update, and applying it is a harmless no-op. Empty means
149 : * the account is gone.
150 : */
151 : LIBJAMI_PUBLIC std::vector<uint8_t> openCollaborativeDocument(const std::string& accountId,
152 : const std::string& conversationId,
153 : const std::string& documentId);
154 : /**
155 : * Remove a document from the conversation. It is retired for every member and
156 : * erased from every device, so this is not a way to stop holding a document
157 : * locally.
158 : *
159 : * Only the member who created the document can: the removal is an edition of the
160 : * announcement, and the swarm accepts an edition only from the author of what it
161 : * edits.
162 : *
163 : * @return false if no announcement for that document is known here. True means
164 : * the removal was committed, not that the members already applied it;
165 : * ConversationSignal::CollaborativeDocumentRemoved reports that.
166 : */
167 : LIBJAMI_PUBLIC bool removeCollaborativeDocument(const std::string& accountId,
168 : const std::string& conversationId,
169 : const std::string& documentId);
170 : /**
171 : * Remove a document from this device only, leaving the other members untouched.
172 : *
173 : * Any member may, on any document: nothing is said to the conversation, this
174 : * only reclaims what this device chose to store. The document stays listed --
175 : * with "storedLocally" false -- and openCollaborativeDocument() fetches it back.
176 : *
177 : * This cancels the pending checkpoint and discards the in-memory replica. Edits
178 : * produced here since the last checkpoint therefore go with it, even when
179 : * another member received them live: receivers merge remote updates in memory
180 : * but do not checkpoint them. An update is durably held elsewhere only after a
181 : * member has fetched and merged the producer's checkpoint into its repository.
182 : *
183 : * @return false if the conversation never announced that document. True means it
184 : * is gone from here; ConversationSignal::CollaborativeDocumentRemoved
185 : * reports it with @c everywhere false.
186 : */
187 : LIBJAMI_PUBLIC bool removeCollaborativeDocumentLocally(const std::string& accountId,
188 : const std::string& conversationId,
189 : const std::string& documentId);
190 : LIBJAMI_PUBLIC void closeCollaborativeDocument(const std::string& accountId,
191 : const std::string& conversationId,
192 : const std::string& documentId);
193 : /**
194 : * Hand the daemon an update produced by the client's own replica: it is merged,
195 : * broadcast to the members and persisted.
196 : *
197 : * It is not signalled back to the local clients, since the replica that produced
198 : * it already holds it.
199 : *
200 : * An update the engine cannot read, or one over 8 MiB once decoded, is dropped:
201 : * the call has no way to fail, so a client must not treat it as an acknowledgement.
202 : * Calling collaborativeDocumentState() tells the client what the daemon actually
203 : * holds.
204 : */
205 : LIBJAMI_PUBLIC void applyCollaborativeUpdate(const std::string& accountId,
206 : const std::string& conversationId,
207 : const std::string& documentId,
208 : const std::vector<uint8_t>& update);
209 : /// The document's whole current state as a Y-CRDT update.
210 : LIBJAMI_PUBLIC std::vector<uint8_t> collaborativeDocumentState(const std::string& accountId,
211 : const std::string& conversationId,
212 : const std::string& documentId);
213 : /**
214 : * Share ephemeral state with the other members while editing: presence, cursor,
215 : * selection. The payload is opaque, never merged and never stored, so its shape
216 : * is the clients' own agreement. Delivered as
217 : * ConversationSignal::CollaborativeAwarenessChanged.
218 : *
219 : * It is meant to stay small: a state over 8 KiB is dropped, in both directions.
220 : */
221 : LIBJAMI_PUBLIC void setCollaborativeAwareness(const std::string& accountId,
222 : const std::string& conversationId,
223 : const std::string& documentId,
224 : const std::string& state);
225 : LIBJAMI_PUBLIC void setCollaborativeDocumentName(const std::string& accountId,
226 : const std::string& conversationId,
227 : const std::string& documentId,
228 : const std::string& name);
229 : LIBJAMI_PUBLIC std::string collaborativeDocumentName(const std::string& accountId,
230 : const std::string& conversationId,
231 : const std::string& documentId);
232 : /**
233 : * Every collaborative document announced in a conversation. Each entry carries
234 : * "id", the document's own id -- the one every other document call takes --
235 : * plus "displayName", "mimeType", "author" and "timestamp", read from the
236 : * commit that announced it, and "announcement", that commit's id, so a client
237 : * can tie the document to its timeline interaction. One more key is added by
238 : * the daemon rather than read from the commit: "storedLocally", "true" unless
239 : * this device removed the document from itself, in which case opening it
240 : * fetches it back.
241 : */
242 : LIBJAMI_PUBLIC std::vector<std::map<std::string, std::string>> getCollaborativeDocuments(
243 : const std::string& accountId, const std::string& conversationId);
244 :
245 : /**
246 : * Checkpoints of a collaborative document, newest first. Each entry describes one
247 : * batch of edits with the keys "id", "author", "device", "timestamp" and "deltas".
248 : * @param accountId the local account id
249 : * @param conversationId the conversation hosting the document
250 : * @param documentId the document id
251 : * @param max maximum number of entries, 0 for no limit
252 : */
253 : LIBJAMI_PUBLIC std::vector<std::map<std::string, std::string>> getCollaborativeDocumentHistory(
254 : const std::string& accountId, const std::string& conversationId, const std::string& documentId, uint32_t max);
255 :
256 : /**
257 : * The document's state as it was at checkpoint @c commitId, as a Y-CRDT update.
258 : * The live document is left untouched.
259 : *
260 : * Reviewing that state, or restoring the document to it, is the client's
261 : * business: both need to know what the document is, which is precisely what the
262 : * daemon does not.
263 : * @return empty if that checkpoint is unknown here
264 : */
265 : LIBJAMI_PUBLIC std::vector<uint8_t> collaborativeDocumentStateAt(const std::string& accountId,
266 : const std::string& conversationId,
267 : const std::string& documentId,
268 : const std::string& commitId);
269 :
270 : /**
271 : * Store a binary payload the document refers to -- an image, a sound, any blob --
272 : * and return the id to embed in the document.
273 : *
274 : * The content is opaque to the daemon, like an update: this does not know about
275 : * images any more than the rest of this API knows about text. It is kept out of
276 : * the CRDT deliberately, because a CRDT never forgets: a deleted payload would
277 : * still weigh on every replica for good. Stored here it is a plain git blob,
278 : * written once whatever the number of references to it, and carried to the other
279 : * members by the document's own repository.
280 : *
281 : * @return the attachment id, or empty when the payload is empty, over 16 MiB, or
282 : * could not be stored.
283 : */
284 : LIBJAMI_PUBLIC std::string addCollaborativeAttachment(const std::string& accountId,
285 : const std::string& conversationId,
286 : const std::string& documentId,
287 : const std::vector<uint8_t>& data);
288 : /**
289 : * Read back an attachment.
290 : *
291 : * @return empty when this replica does not hold it @b yet, which is the normal
292 : * state right after a peer referenced it: the reference travels on the
293 : * real-time path and the payload with the repository. A client should
294 : * show a placeholder and wait for
295 : * ConversationSignal::CollaborativeAttachmentAdded rather than treat
296 : * this as an error.
297 : */
298 : LIBJAMI_PUBLIC std::vector<uint8_t> collaborativeAttachment(const std::string& accountId,
299 : const std::string& conversationId,
300 : const std::string& documentId,
301 : const std::string& attachmentId);
302 :
303 : struct LIBJAMI_PUBLIC ConversationSignal
304 : {
305 : /**
306 : * A Y-CRDT update to merge into the client's own replica of the document.
307 : *
308 : * The payload is opaque: the daemon neither produces nor reads the
309 : * document's content, so this one signal carries every change of every
310 : * document type. An update the replica already has is a no-op, so applying
311 : * it unconditionally is always correct.
312 : *
313 : * An empty payload is a notification, not an update: the document changed
314 : * -- a synchronization brought edits while no client here had it open --
315 : * but the content is withheld until the document is opened. There is
316 : * nothing to apply; it exists so a client can mark the document unread.
317 : */
318 : struct LIBJAMI_PUBLIC CollaborativeDocumentUpdate
319 : {
320 : constexpr static const char* name = "CollaborativeDocumentUpdate";
321 : using cb_type = void(const std::string& /*account_id*/,
322 : const std::string& /*convId*/,
323 : const std::string& /*documentId*/,
324 : const std::vector<uint8_t>& /*update*/);
325 : };
326 : /**
327 : * Ephemeral state a peer shares while editing: presence, cursor, selection.
328 : * Never merged and never stored; its shape is agreed between clients, not
329 : * imposed by the daemon.
330 : *
331 : * A peer is identified by @c clientId, not by @c peerId: one account can
332 : * have several devices in the same document, and each of them has its own
333 : * cursor. @c peerId says which person that client belongs to.
334 : */
335 : struct LIBJAMI_PUBLIC CollaborativeAwarenessChanged
336 : {
337 : constexpr static const char* name = "CollaborativeAwarenessChanged";
338 : using cb_type = void(const std::string& /*account_id*/,
339 : const std::string& /*convId*/,
340 : const std::string& /*documentId*/,
341 : const std::string& /*peerId*/,
342 : uint64_t /*clientId*/,
343 : const std::string& /*state*/);
344 : };
345 : /// A client withdrew its state, or stopped announcing it for long enough to
346 : /// be considered gone. Anything shown for @c clientId can be dropped.
347 : struct LIBJAMI_PUBLIC CollaborativeParticipantLeft
348 : {
349 : constexpr static const char* name = "CollaborativeParticipantLeft";
350 : using cb_type = void(const std::string& /*account_id*/,
351 : const std::string& /*convId*/,
352 : const std::string& /*documentId*/,
353 : const std::string& /*peerId*/,
354 : uint64_t /*clientId*/);
355 : };
356 : struct LIBJAMI_PUBLIC CollaborativeDocumentRenamed
357 : {
358 : constexpr static const char* name = "CollaborativeDocumentRenamed";
359 : using cb_type = void(const std::string& /*account_id*/,
360 : const std::string& /*convId*/,
361 : const std::string& /*documentId*/,
362 : const std::string& /*name*/);
363 : };
364 : /// A document is no longer held by this device. @c everywhere tells the two
365 : /// apart: true when its author retired it and it is gone for every member,
366 : /// false when this device alone removed it and the others still have it.
367 : struct LIBJAMI_PUBLIC CollaborativeDocumentRemoved
368 : {
369 : constexpr static const char* name = "CollaborativeDocumentRemoved";
370 : using cb_type = void(const std::string& /*account_id*/,
371 : const std::string& /*convId*/,
372 : const std::string& /*documentId*/,
373 : bool /*everywhere*/);
374 : };
375 : /// A synchronization brought in a binary payload the document refers to.
376 : /// Clients showing a placeholder for it can now read it with
377 : /// collaborativeAttachment().
378 : struct LIBJAMI_PUBLIC CollaborativeAttachmentAdded
379 : {
380 : constexpr static const char* name = "CollaborativeAttachmentAdded";
381 : using cb_type = void(const std::string& /*account_id*/,
382 : const std::string& /*convId*/,
383 : const std::string& /*documentId*/,
384 : const std::string& /*attachmentId*/);
385 : };
386 : struct LIBJAMI_PUBLIC SwarmLoaded
387 : {
388 : constexpr static const char* name = "SwarmLoaded";
389 : using cb_type = void(uint32_t /* id */,
390 : const std::string& /*accountId*/,
391 : const std::string& /* conversationId */,
392 : std::vector<SwarmMessage> /*messages*/);
393 : };
394 : struct LIBJAMI_PUBLIC MessagesFound
395 : {
396 : constexpr static const char* name = "MessagesFound";
397 : using cb_type = void(uint32_t /* id */,
398 : const std::string& /*accountId*/,
399 : const std::string& /* conversationId */,
400 : std::vector<std::map<std::string, std::string>> /*messages*/);
401 : };
402 : struct LIBJAMI_PUBLIC SwarmMessageReceived
403 : {
404 : constexpr static const char* name = "SwarmMessageReceived";
405 : using cb_type = void(const std::string& /*accountId*/,
406 : const std::string& /* conversationId */,
407 : const SwarmMessage& /*message*/);
408 : };
409 : struct LIBJAMI_PUBLIC SwarmMessageUpdated
410 : {
411 : constexpr static const char* name = "SwarmMessageUpdated";
412 : using cb_type = void(const std::string& /*accountId*/,
413 : const std::string& /* conversationId */,
414 : const SwarmMessage& /*message*/);
415 : };
416 : struct LIBJAMI_PUBLIC ReactionAdded
417 : {
418 : constexpr static const char* name = "ReactionAdded";
419 : using cb_type = void(const std::string& /*accountId*/,
420 : const std::string& /* conversationId */,
421 : const std::string& /* messageId */,
422 : std::map<std::string, std::string> /*reaction*/);
423 : };
424 : struct LIBJAMI_PUBLIC ReactionRemoved
425 : {
426 : constexpr static const char* name = "ReactionRemoved";
427 : using cb_type = void(const std::string& /*accountId*/,
428 : const std::string& /* conversationId */,
429 : const std::string& /* messageId */,
430 : const std::string& /* reactionId */);
431 : };
432 : struct LIBJAMI_PUBLIC ConversationProfileUpdated
433 : {
434 : constexpr static const char* name = "ConversationProfileUpdated";
435 : using cb_type = void(const std::string& /*accountId*/,
436 : const std::string& /* conversationId */,
437 : std::map<std::string, std::string> /*profile*/);
438 : };
439 : struct LIBJAMI_PUBLIC ConversationRequestReceived
440 : {
441 : constexpr static const char* name = "ConversationRequestReceived";
442 : using cb_type = void(const std::string& /*accountId*/,
443 : const std::string& /* conversationId */,
444 : std::map<std::string, std::string> /*metadatas*/);
445 : };
446 : struct LIBJAMI_PUBLIC ConversationRequestDeclined
447 : {
448 : constexpr static const char* name = "ConversationRequestDeclined";
449 : using cb_type = void(const std::string& /*accountId*/, const std::string& /* conversationId */);
450 : };
451 : struct LIBJAMI_PUBLIC ConversationReady
452 : {
453 : constexpr static const char* name = "ConversationReady";
454 : using cb_type = void(const std::string& /*accountId*/, const std::string& /* conversationId */);
455 : };
456 : struct LIBJAMI_PUBLIC ConversationRemoved
457 : {
458 : constexpr static const char* name = "ConversationRemoved";
459 : using cb_type = void(const std::string& /*accountId*/, const std::string& /* conversationId */);
460 : };
461 : struct LIBJAMI_PUBLIC ConversationMemberEvent
462 : {
463 : constexpr static const char* name = "ConversationMemberEvent";
464 : using cb_type = void(const std::string& /*accountId*/,
465 : const std::string& /* conversationId */,
466 : const std::string& /* memberUri */,
467 : int /* event 0 = add, 1 = joins, 2 = leave, 3 = banned */);
468 : };
469 :
470 : struct LIBJAMI_PUBLIC ConversationSyncFinished
471 : {
472 : constexpr static const char* name = "ConversationSyncFinished";
473 : using cb_type = void(const std::string& /*accountId*/);
474 : };
475 :
476 : struct LIBJAMI_PUBLIC ConversationCloned
477 : {
478 : constexpr static const char* name = "ConversationCloned";
479 : using cb_type = void(const std::string& /*accountId*/);
480 : };
481 :
482 : struct LIBJAMI_PUBLIC CallConnectionRequest
483 : {
484 : constexpr static const char* name = "CallConnectionRequest";
485 : using cb_type = void(const std::string& /*accountId*/, const std::string& /*peerId*/, bool hasVideo);
486 : };
487 :
488 : struct LIBJAMI_PUBLIC OnConversationError
489 : {
490 : constexpr static const char* name = "OnConversationError";
491 : using cb_type = void(const std::string& /*accountId*/,
492 : const std::string& /* conversationId */,
493 : int code,
494 : const std::string& what);
495 : };
496 :
497 : // Preferences
498 : struct LIBJAMI_PUBLIC ConversationPreferencesUpdated
499 : {
500 : constexpr static const char* name = "ConversationPreferencesUpdated";
501 : using cb_type = void(const std::string& /*accountId*/,
502 : const std::string& /*conversationId*/,
503 : std::map<std::string, std::string> /*preferences*/);
504 : };
505 : };
506 :
507 : } // namespace libjami
508 :
509 : #endif // LIBJAMI_CONVERSATIONI_H
|
