First draft of the local files page

Cache%2C-config-local-files.md

@@ -0,0 +1,96 @@
+# Cache and config
+Just like any other program Squawk needs to have a config and cache files.
+
+## Cache
+Squawk stores users message history and avatars on the hard drive for it to persist across the launches. The folder is defined by following code
+```
+QStandardPaths::writableLocation(QStandardPaths::CacheLocation)
+```
+Whis is a standard Qt way to find a writable location for cache files. Nowadays on GNU+Linux systems it creates a folder in your `~/.cache` directory application name. So, on my machine it creates a folder under following path
+```
+~/.cache/squawk
+```
+There are going to be several subfolders there: one for each of your account and a folder for localPath/remoteURLs database used im my file upload caching method.
+
+Inside each of account folders there going to be your avatar and a folder for each of your contacts and MUCs. There are 2 complementary database files there `data.mdb` and `lock.mdb`, this is where Squawk stores message history with this contact. In contact folders there is going to be avatar, and in MUC folders there is going to be avatar for MUC (called the same way the MUC is called to prevent overlaping with some possible genius desiding that "avatar" is a darn good nick name) and many avatars for participants each under their nickname in that MUC. If participant didn't had an avatar Squawk creates one basing on the first letter of their Jabber id or on their nick.
+
+You can safely remove account or contact directories in cache, it's just goung to clear your local history, and if your server stores it - you're going to get it again with the avatars. It's not a good idea to remove 'fileURLStorage' storage and keeping account folders - this way you might break downloading files. You see, every time Squawk gets a new message via history or in a real time it checks if the message has a URL for the file you can download. Information of messages are stored in fileURLStorage, so when you try to download it Squawk checks which other messages use the same url and downloading it once assign the local path to all messages that are affilated with that file. When you remove your local file Squawk also detects which messages are going to be affected by this action and when if fails to paint the attachment you have already downloaded - it marks all messages with the same local file path as undownloaded. The best way to clear your cache is to remove the whole `~/.cache/squawk` folder. You can also remove each of `~/.cache/squawk/<accountName>` folders but please don't touch `~/.cache/squawk/fileURLStorage`.
+
+## Downloads
+Squawk stores detects where to store downloads using following code
+```
+QString path = QStandardPaths::writableLocation(QStandardPaths::DownloadLocation);
+path += "/" + QApplication::applicationName();
+```
+On my machine it creates a folder there
+```
+~/Downloads/squawk/
+```
+In this folder you will find many subfolders named after Jabber IDs of conversations you got this file from. I'm not quite sure yet if it's comfortable enought and probably going to modify this behaviour in future. It is safe to rename move or remove files from there - Squawk will detect that the file no longer exist under the previous name and will offer you to download it again in each message it happened to be used by. If by any chance the new downloading file name overlaps with existing one Squawk tries to add (n) to it, before suffix like `file.tar.gz` then `file(1).tar.gz` then `file(2).tar.gz` and so on.
+
+## Config
+### Where do I find config
+Squawk uses [QSettings](https://doc.qt.io/qt-5/qsettings.html) framework to store configuration files. Nowadays on GNU+Linux systems it creates a folder in your `~/.config` directory with the organization name and a file `<application_name>.conf` file in it. For now the name of application is squawk, and it has no organization, so, it's unset. By default Qt on my system creates a file under following path:
+```
+~/.config/Unknown\ Organization/squawk.conf
+```
+The backslash is there for you to copy paste it into your console, it shields the space.
+
+### What is written in the config
+Basically I never intended the user to manually edit the config. It is not used to configurate the app but to store there some persistent options user set up during the usage. Let's see what the config looks like
+```
+[core]
+accounts\1\login=blue
+accounts\1\name=Blue
+accounts\1\password=
+accounts\1\passwordType=3
+accounts\1\resource=Home
+accounts\1\server=macaw.me
+accounts\2\login=administrator
+accounts\2\name=Administrator
+accounts\2\password=
+accounts\2\passwordType=3
+accounts\2\resource=Home
+accounts\2\server=macaw.me
+accounts\size=2
+
+[ui]
+availability=0
+connectedAccounts\1\name=Administrator
+connectedAccounts\2\name=Blue
+connectedAccounts\size=1
+roster\Administrator\expanded=true
+roster\Blue\expanded=false
+splitter=@ByteArray(\0\0\0\xff\0\0\0\x1\0\0\0\x3\0\0\0\xee\0\0\x4\x10\0\0\x4\x10\0\0\0\0\x1\x1\0\0\0\x1\0)
+window\geometry=@ByteArray(\x1\xd9\xd0\xcb\0\x3\0\0\0\0\0u\0\0\0[\0\0\x4\x30\0\0\x3O\0\0\0u\0\0\0[\0\0\x4\x30\0\0\x3O\0\0\0\0\0\0\0\0\a\x80\0\0\0u\0\0\0[\0\0\x4\x30\0\0\x3O)
+window\state=@ByteArray(\0\0\0\xff\0\0\0\0\xfd\0\0\0\0\0\0\x3\xbc\0\0\x2\xda\0\0\0\x4\0\0\0\x4\0\0\0\b\0\0\0\b\xfc\0\0\0\0)
+```
+
+As you can see it has 2 sections: core and ui. 
+
+#### [core]
+The only variable now in core is the list of accounts. These are accounts user set up to have in the app. As you can see my config has 2 accounts.
+Each account has following fields:
+* login - pretty self expaining, your XMPP login (without @server.domain!)
+* name - it's an account ID, don't mess this up unless you know what you're doing. It is used to define where is you cache database. It's also used to assign you default name when joining a new MUC.
+* password - sometimes it stores you password, gonna explain lower
+* passwordType - a number that defines the way Squawk stores your password, possible options:
+  * 0 (plain) - this way squawk stores the password in plain text in the field password of this config file;
+  * 1 (jammed) - this way the password is still stored in the field password of this config file but it's scrambled, **NOT ENCRYPTED!** It's not safe the jamming key is stored in squawks source code!
+  * 2 (alwaysAsk) - this way the password is not stored on the disk but squawk aks you for it every time it tris to connect to your account, the field password is unused
+  * 3 (kwallet) - this way squawk stores the password in [KWallet](https://userbase.kde.org/KDE_Wallet_Manager) password manager if it's installed. First time you are going to be asked to grant Squawk permissions to access KWallet. If something didn't work with kwallet Squawk is going to aks your password like in option 2 (alwaysAsk).
+* resource - XMPP resource field. Basically it serves to name a device logged into your account. Modern clients don't even show it.
+* server - a server to that serves your account. So basically your jabber ID consist of login@server
+* 
+As you can see I store my posswords in KWallet.
+
+#### [ui]
+This section stores some UI related settings:
+* availability stores your last used availability, like Online or Chatty or Busy and so on. They are assigned to numbers, shortly speaking 0 means Online
+* connectedAccounts is a list that stores which accounts you actually have been using last time, you can keep them suspended if you please. As you can see, the size of that list is 1, so, it means last time I have been using only account with name Administrator
+* roster <Account name> expanded - this property holds which of your accounts and groups inside of them you have been expanding last time you used squawk. It doesn't store expanded contacts or expanded MUCs, just accounts and groups
+* splitter is a binary dump of the state of QSplitter in the middle of the program - like what was what size and what was collapsed
+* window\geometry is a binary dump of QWindow geometry of main window of the app, like what size it was.
+* window\state is pretty much the same as geometry but more about stuff like was it fullscreen or minimized.
+
+As you can see if you delete your config - worst thing that would happen - Squawk wouldn't remember your accounts