libcwtch/
lib.rs

1#![doc = include_str!( "../README.md" )]
2#![doc(html_logo_url = "https://git.openprivacy.ca/cwtch.im/cwtch-ui/media/branch/trunk/cwtch.png")]
3#![doc(html_root_url = "https://git.openprivacy.ca/cwtch.im/libcwtch-rs")]
4#![deny(missing_docs)]
5
6use crate::event::{ConversationID, Event, FileKey, ProfileIdentity, ServerIdentity};
7use crate::structs::{ACL, MessageWrapper, Settings, SharedFile};
8
9mod bindings_go;
10mod cwtchlib_go;
11
12/// Basic structs using data from Cwtch and for deserializing JSON and serializing to JSON to communicate with Cwtch
13pub mod structs;
14/// Additional structs for advnaced event handling and converstion helpers
15pub mod event;
16
17/// Error type for Cwtch lib related errors, intended for use with Result
18pub type CwtchError = String;
19
20/// Interface to a Cwtch app with API matching libcwtch
21pub trait CwtchLib {
22    /// Start a cwtch application using app_dir to store all user profile data and looking to tor_path to find tor to run
23    fn start_cwtch(&self, app_dir: &str, tor_path: &str) -> i32;
24
25    /// Return 1 if cwtch has been started and 0 if not
26    fn started(&self) -> i32;
27
28    /// Like StartCwtch, but StartCwtch has already been called so we don't need to restart Tor etc (probably)
29    /// Do need to re-send initial state tho, eg profiles that are already loaded (used by android when ui state is lost)
30    fn reconnect_cwtch_foreground(&self);
31
32    /// Save and update the settings based on this settings
33    fn update_settings(&self, settings: &Settings);
34
35    /// Activate the networking engine of a profile so it can send and listen to/for messages
36    fn activate_peer_engine(&self, profile: &ProfileIdentity);
37
38    /// Deactivate the networking engine of a profile so it cannot send and listen to/for messages
39    fn deactivate_peer_engine(&self, profile: &ProfileIdentity);
40
41    /// Pull json of a structs::CwtchEvent off the appbus for responding to
42    fn get_appbus_event(&self) -> Event;
43
44    /// configure a peer's connection settings, listen for incoming connections, connect to peers and connect to servers.
45    fn configure_connections(&self, profile: &ProfileIdentity, listen: bool, peers: bool, servers: bool);
46
47    /// Create a new profile encrypted with pass
48    fn create_profile(&self, nick: &str, pass: &str, autostart: bool);
49
50    /// Load any profiles encrypted by pass
51    fn load_profiles(&self, pass: &str);
52
53    /// Cause profile to accept conversation
54    fn accept_conversation(&self, profile: &ProfileIdentity, conversation_id: ConversationID);
55
56    /// Cause profile to block conversation
57    fn block_conversation(&self, profile: &ProfileIdentity, conversation_id: ConversationID);
58
59    /// Cause profile to unblock conversation
60    fn unblock_conversation(&self, profile: &ProfileIdentity, conversation_id: ConversationID);
61
62    /// Attempt to peer with a a new peer
63    fn peer_with(&self, profile: &ProfileIdentity, new_peer_address: &str);
64
65    /// manually disconnect from a conversation
66    fn disconnect_from_peer(&self, profile: &ProfileIdentity, peer_id: &str);
67
68    /// starts a search process on a profile for pattern. returns a searchID that resulting SearchResult messages will have
69    fn search_conversations(&self, profile: &ProfileIdentity, pattern: &str) -> String;
70    
71    /// Get an ACL for a conversation
72    fn get_conversation_access_control_list(&self, profile: &ProfileIdentity, conversation_id: ConversationID) -> Result<ACL, CwtchError>;
73    
74    /// Update a conversation's ACL
75    fn update_conversation_access_control_list(&self, profile: &ProfileIdentity, conversation_id: ConversationID, acl: ACL);
76
77    /// Get a specific message for a conversation by its id
78    fn get_message_by_id(&self, profile: &ProfileIdentity, conversation_id: ConversationID, message_id: i32) -> String;
79
80    /// Get a specific message for conversation of profile by hash
81    fn get_message_by_content_hash(
82        &self,
83        profile: &ProfileIdentity,
84        conversation_id: ConversationID,
85        hash: &str,
86    ) -> String;
87
88    /// Bulk get messages starting at message index and of count amoung
89    fn get_messages(&self, profile: &ProfileIdentity, conversation_id: ConversationID, message_index: i32, count: u32)  -> String;
90
91    /// Send json of a structs::Message from profile to contact. Returns computed sent message (including index and hash values)
92    fn send_message_raw(&self, profile: &ProfileIdentity, conversation_id: ConversationID, msg: &str) -> String;
93
94    /// Send structs::Message from profile to contact. Returns computed sent message (including index and hash values) or Error
95    fn send_message(&self, profile: &ProfileIdentity, conversation_id: ConversationID, message: &MessageWrapper) -> Result<String, CwtchError>;
96
97    /// Send profile's contact an invite for/to target. Returns computed sent message (including index and hash values)
98    fn send_invite_message(&self, profile: &ProfileIdentity, conversation_id: ConversationID, target_id: i32) -> String;
99
100    /// share a file file_path with a conersation. Returns computed sent message (including index and hash values)
101    fn share_file(&self, profile: &ProfileIdentity, conversation_id: ConversationID, file_path: &str) -> String;
102
103    /// get list of SharedFile for a conversation
104    fn get_shared_files(&self, profile: &ProfileIdentity, conversaion_id: ConversationID) -> Vec<SharedFile>;
105
106    /// download a file from a conversation to the file_path
107    fn download_file_default_limit(
108        &self,
109        profile: &ProfileIdentity,
110        conversation_id: ConversationID,
111        file_path: &str,
112        manifest_path: &str,
113        file_key: &FileKey,
114    );
115
116    /// Restart a fileshare (used when restarting app to reoffer a previously created fileshare)
117    fn restart_fileshare(&self, profile: &ProfileIdentity, file_key: &FileKey);
118
119    /// Stop offering a fileshare
120    fn stop_fileshare(&self, profile: &ProfileIdentity, file_key: &FileKey);
121
122    /// Query the status of a download
123    fn check_download_status(&self, profile: &ProfileIdentity, file_key: &FileKey);
124
125    /// Verufy a download is done, and if not, resume it
126    fn verify_or_resume_download(&self, profile: &ProfileIdentity, conversation_id: ConversationID, file_key: &FileKey);
127
128    /// Ask the ACN inside the Cwtch app to restart the tor connection
129    fn reset_tor(&self);
130
131    /// Cause profile to create a group on server with name
132    fn start_group(&self, profile: &ProfileIdentity, name: &str, server: &str);
133
134    /// Queue joining a server in the out going connections queue
135    fn queue_join_server(&self, profile: &ProfileIdentity, server: &ServerIdentity);
136
137    /// Disconnect from a specific server
138    fn disconnect_from_server(&self, profile: &ProfileIdentity, server: &ServerIdentity);
139
140    /// Publish server status updates for a profile
141    fn publish_server_update(&self, profile: &ProfileIdentity);
142
143    /// Get list of known servers for a profile
144    fn get_server_info_list(&self, profile: &ProfileIdentity);
145
146    /// Delete server information from a profile, preventing future connections for all groups hosted on it
147    fn delete_server_info(&self, profile: &ProfileIdentity, server: &ServerIdentity);
148
149    /// Delete profile with encryption/password check of pass
150    fn delete_profile(&self, profile: &ProfileIdentity, pass: &str);
151
152    /// Cause profile to archive conversation with contact
153    fn archive_conversation(&self, profile: &ProfileIdentity, conversation_id: ConversationID);
154
155    /// Cause profile to delete contact/group identified by handle
156    fn delete_conversation(&self, profile: &ProfileIdentity, conversation_id: ConversationID);
157
158    /// Cuase profile to attempt to import a contact/group/keybundle identified by bundle
159    fn import_bundle(&self, profile: &ProfileIdentity, bundle: &str);
160
161    /// Set a profile attribute key to val
162    fn set_profile_attribute(&self, profile: &ProfileIdentity, key: &str, val: &str);
163
164    /// Get a profile attribute
165    fn get_profile_attribute(&self, profile: &ProfileIdentity, key: &str) -> Result<Option<String>, CwtchError>;
166
167    /// Set a profile's contact's attribute of key to val
168    fn set_conversation_attribute(&self, profile: &ProfileIdentity, conversation_id: ConversationID, key: &str, val: &str);
169
170    /// Update an attribute on a message in a conversation
171    fn update_message_attribute(
172        &self,
173        profile: &ProfileIdentity,
174        conversation_id: ConversationID,
175        channel_id: i32,
176        message_id: i32,
177        attribute_key: &str,
178        attribute_value: &str,
179    );
180
181    /// Get an attribute for a conversation
182    fn get_conversation_attribute(&self, profile: &ProfileIdentity, conversation_id: ConversationID, key: &str) -> Result<Option<String>, CwtchError>;
183
184    /// Change a profile's password to new_pass if old_pass is correct
185    fn change_password(&self, profile: &ProfileIdentity, old_pass: &str, new_pass: &str, new_pass_again: &str);
186
187    /// Export a profile to filename
188    fn export_profile(&self, profile: &ProfileIdentity, filename: &str);
189
190    /// Import a profile from a file with supplied password. Json of a profile struct returned on success
191    fn import_profile(&self, filename: &str, password: &str) -> String;
192
193    /// Shutdown the cwtch app and associated ACN
194    fn shutdown_cwtch(&self);
195
196    /// Server functions require server experiment to be enabled
197
198    /// Load all servers encrypted by password
199    fn load_servers(&self, password: &str);
200
201    /// Create a new server, encrypted with password
202    fn create_server(&self, password: &str, description: &str, autostart: bool);
203
204    /// Delete the specified server (if password is correct)
205    fn delete_server(&self, server: ServerIdentity, current_password: &str);
206
207    /// Launch all loaded servers
208    fn launch_servers(&self);
209
210    /// Launch the specified server
211    fn launch_server(&self, server: ServerIdentity);
212
213    /// Stop the specified server
214    fn stop_server(&self, server: ServerIdentity);
215
216    /// Stop all running servers
217    fn stop_servers(&self);
218
219    /// Destroy all servers leaving htem un-re-runnable. call only on shutdown
220    fn destroy_servers(&self);
221
222    /// Set the specified server's attribute of key to val
223    fn set_server_attribute(&self, server: ServerIdentity, key: &str, val: &str);
224
225    /// Get debug info (mem, goroutine stats) from lcg in json
226    fn get_debug_info(&self) -> String;
227}
228
229/// Create a new CwtchLib that is backed by bindings to libcwtch-go
230pub fn new_cwtchlib_go() -> impl CwtchLib {
231    bindings_go::CwtchLibGo {}
232}
libcwtch/lib.rs

libcwtch/
lib.rs
