diff --git a/Library-Documentation.md b/Library-Documentation.md index 9cf1bc8..b930ef6 100644 --- a/Library-Documentation.md +++ b/Library-Documentation.md @@ -116,6 +116,9 @@ A class called `Logging` handles everything. However, logging directly using the #define LOG(level) \ Helper::Logger(level, __func__, Helper::LoggingProperties::FILE.data(), \ Helper::LoggingProperties::NAME.data(), __FILE__, __LINE__) +#define LOGF(file, level) \ + Helper::Logger(level, __func__, file, \ + Helper::LoggingProperties::NAME.data(), __FILE__, __LINE__) #define LOGN(name, level) \ Helper::Logger(level, __func__, Helper::LoggingProperties::FILE.data(), \ name, __FILE__, __LINE__) @@ -126,6 +129,10 @@ A class called `Logging` handles everything. However, logging directly using the if (condition) \ Helper::Logger(level, __func__, Helper::LoggingProperties::FILE.data(), \ Helper::LoggingProperties::NAME.data(), __FILE__, __LINE__) +#define LOGF_IF(file, level, condition) \ + if (condition) \ + Helper::Logger(level, __func__, file, \ + Helper::LoggingProperties::NAME.data(), __FILE__, __LINE__) #define LOGN_IF(name, level, condition) \ if (condition) \ Helper::Logger(level, __func__, Helper::LoggingProperties::FILE.data(), \ @@ -174,12 +181,15 @@ Now we can reinforce it with use cases. That would be good. ```c++ #include #include +#include int main(int argc, char** argv) { Helper::LoggingProperties::set("pmt", "/storage/emulated/0/Dccuments/last_pmt_logs.log"); LOG(INFO) << "Hello World!" << std::endl; + LOGF("last_logs_test.log", INFO) << "Hello World!" << std::endl; LOG_IF(WARNING, argc < 2) << "No argument speficed!" << std::endl; + LOGF_IF("last_logs_test.log", strcmp(argv[0], "pmt") == 0) << "This is pmt!" << std::endl; LOGN(argv[0], INFO) << "Hello World from " << argv[0] << " program!" << std::endl; LOGNF(argv[0], "last_logs_test.log", INFO) << "LOGNF() test!!!" << std::endl; LOGN_IF(argv[0], WARNING, argc < 2) << "No argument speficed! (test 2)" << std::endl; @@ -292,314 +302,61 @@ int main(int argc, char** argv) { ### Functions `libhelper` provides many helper functions. Some of these throw `Helper::Error`. We'll cover each one with code examples. -```c++ -#include -#include -#include +#### Checkers (not throws Helper::Error) -int main(int argc, char** argv) { - /** - Checker functions - don't throw Helper::Error +* `bool hasSuperUser()` - It is checked whether the user ID used is equivalent to AID_ROOT. See include/private/android_filesystem_config.h +* `bool hasAdbPermissions()` - It is checked whether the user ID used is equivalent to AID_SHELL. See include/private/android_filesystem_config.h +* `bool isExists(std::string_view entry)` - Checks whether the file/directory exists. +* `bool fileIsExists(std::string_view file)` - Checks whether the file exists. +* `bool directoryIsExists(std::string_view directory)` - Checks whether the directory exists. +* `bool linkIsExists(std::string_view entry)` - Checks whether the link (symbolic or hard) exists. +* `bool isLink(std::string_view entry)` - Checks if the entry is a symbolic link. +* `bool isSymbolicLink(std::string_view entry)` - Checks if the entry is a symbolic link. +* `bool isHardLink(std::string_view entry)` - Checks if the entry is a hard link. +* `bool areLinked(std::string_view entry1, std::string_view entry2)` - Checks whether entry1 is linked to entry2. - bool hasSuperUser(); - // Returns true if user id equals AID_ROOT. - // See srclib/libhelper/include/private/android_filesystem_config.h +#### File I/O (not throws Helper::Error) - bool hasAdbPermissions(); - // Returns true if user id equals AID_SHELL. - // See srclib/libhelper/include/private/android_filesystem_config.h +* `bool writeFile(std::string_view file, std::string_view text)` - Writes given text into file. If file does not exist, it is automatically created. Returns true on success. +* `std::optional readFile(std::string_view file)` - Reads file content into string. On success returns file content. On error returns std::nullopt. - bool isExists(std::string_view entry); - // Returns true if entry exists (file or directory). +#### Creators - bool fileIsExists(std::string_view file); - // Returns true if given file exists. +* `bool makeDirectory(std::string_view path)` - Create directory. +* `bool makeRecursiveDirectory(std::string_view paths)` - Create recursive directory. +* `bool createFile(std::string_view path)` - Create file. +* `bool createSymlink(std::string_view entry1, std::string_view entry2)` - Symlink entry1 to entry2. - bool directoryIsExists(std::string_view directory); - // Returns true if given directory exists. +#### Removers (not throws Helper::Error) - bool linkIsExists(std::string_view entry); - // Returns true if entry is symbolic or hard link. +* `bool eraseEntry(std::string_view entry)` - Remove file or empty directory. +* `bool eraseDirectoryRecursive(std::string_view directory)` - Remove directory and all directory contents recursively. - bool isLink(std::string_view entry); - // Returns true if entry is a symbolic link. +#### Getters (not throws Helper::Error) - bool isSymbolicLink(std::string_view entry); - // Alias of isLink(). +* `int64_t fileSize(std::string_view file)` - Get file size. +* `std::string readSymlink(std::string_view entry)` - Read symlinks. - bool isHardLink(std::string_view entry); - // Returns true if entry is a hard link. +#### SHA-256 - bool areLinked(std::string_view entry1, std::string_view entry2); - // Returns true if entry1 links to entry2 (symbolic link). - */ - - if (!Helper::hasSuperUser()) - std::cout << "Super user privileges not given." << std::endl; - - if (Helper::hasAdbPermissions()) - std::cout << "You have ADB shell privileges." << std::endl; +* `bool sha256Compare(std::string_view file1, std::string_view file2)` - Compare SHA-256 values of files. Throws Helper::Error on error occurred. +* `std::optional sha256Of(std::string_view path)` - Get SHA-256 of file. Throws Helper::Error on error occurred. - if (Helper::isExists("myentry")) - std::cout << "myentry exists." << std::endl; +#### Utilities (not throws Helper::Error) - if (Helper::fileIsExists("file.txt")) - std::cout << "file.txt exists." << std::endl; - - if (Helper::directoryIsExists("mydir")) - std::cout << "mydir exists." << std::endl; - - if (Helper::linkIsExists("mylinked_entry")) - std::cout << "mylinked_entry is symbolic or hard link." << std::endl; - - if (Helper::isLink("mylinked_entry")) - std::cout << "mylinked_entry is symbolic link." << std::endl; - - if (Helper::isHardLink("myhardlinked_entry")) - std::cout << "myhardlinked_entry is hard link." << std::endl; - - if (Helper::areLinked("mylinked_entry", "myentry")) - std::cout << "mylinked_entry links to myentry." << std::endl; - - - /** - File I/O - don't throw Helper::Error - - bool writeFile(std::string_view file, std::string_view text); - // Writes given text into file. - // If file does not exist, it is automatically created. - // Returns true on success. - - std::optional readFile(std::string_view file); - // Reads file content into string. - // On success returns file content. - // On error returns std::nullopt. - */ - - if (Helper::writeFile("file.txt", "hello world")) - std::cout << "file.txt written." << std::endl; - - auto result = Helper::readFile("file.txt"); - if (!result) - std::cerr << "Cannot read file.txt." << std::endl; - else - std::cout << "file.txt: " << *result << std::endl; - - - /** - Creators - don't throw Helper::Error - - bool makeDirectory(std::string_view path); - // Creates a directory at given path. - // Returns true on success. - - bool makeRecursiveDirectory(std::string_view paths); - // Creates all directories in given path recursively. - // Returns true on success. - - bool createFile(std::string_view path); - // Creates an empty file at given path. - // Returns true on success. - - bool createSymlink(std::string_view entry1, std::string_view entry2); - // Creates a symbolic link entry2 pointing to entry1. - // Returns true on success. - */ - - if (Helper::makeDirectory("dir")) - std::cout << "dir created." << std::endl; - - if (Helper::makeRecursiveDirectory("dir1/dir2/dir3")) - std::cout << "dir1/dir2/dir3 created." << std::endl; - - if (Helper::createFile("newfile.txt")) - std::cout << "newfile.txt created." << std::endl; - - if (Helper::createSymlink("newfile.txt", "newfile_symlink.txt")) - std::cout << "newfile.txt symlinked to newfile_symlink.txt." << std::endl; - - - /** - Removers - don't throw Helper::Error - - bool eraseEntry(std::string_view entry); - // Removes file or empty directory. - // Returns true on success. - - bool eraseDirectoryRecursive(std::string_view directory); - // Removes directory and all its contents recursively. - // Returns true on success. - */ - - if (Helper::eraseEntry("file.txt")) - std::cout << "file.txt erased." << std::endl; - - if (Helper::eraseDirectoryRecursive("dir1/dir2/dir3")) - std::cout << "dir1/dir2/dir3 erased." << std::endl; - - - /** - Getters - don't throw Helper::Error - - int64_T fileSize(std::string_view file); - // Returns file size in bytes. - // On error returns -1. - - std::string readSymlink(std::string_view entry); - // Reads the target of symbolic link. - // Returns empty string on error. - */ - - if (size_t size = Helper::fileSize("newfile.txt"); size == -1) - std::cout << "Cannot get size of newfile.txt" << std::endl; - else - std::cout << "Size of newfile.txt: " << size << std::endl; - - if (std::string s = Helper::readSymlink("newfile_symlink.txt"); s.empty()) - std::cout << "Cannot read symlink: newfile_symlink.txt" << std::endl; - else - std::cout << "newfile_symlink.txt points to " << s << std::endl; - - /** - SHA-256 helpers - - bool sha256Compare(std::string_view file1, std::string_view file2); - // Compares the SHA-256 hash of two files. - // Returns true if hashes are equal, false otherwise. - // Uses sha256Of() internally. - // Does not throw Helper::Error. - - std::optional sha256Of(std::string_view path); - // Calculates SHA-256 of a file at given path. - // Returns hex string of hash on success. - // On error, throws Helper::Error. - */ - - if (Helper::sha256Compare("file1.bin", "file2.bin")) - std::cout << "file1.bin and file2.bin are identical (SHA-256)" << std::endl; - else - std::cout << "Files differ (SHA-256)" << std::endl; - - if (auto hash = Helper::sha256Of("file1.bin")) - std::cout << "SHA-256 of file1.bin: " << *hash << std::endl; - else - std::cout << "Failed to calculate SHA-256 of file1.bin" << std::endl; - - /** - Utilities - don't throw Helper::Error - - bool copyFile(std::string_view file, std::string_view dest); - // Copies file to dest. - // Returns true on success. - - bool runCommand(std::string_view cmd); - // Runs a system command without capturing output. - // Returns true if exit status == 0. - - bool confirmPropt(std::string_view message); - // Shows message and asks for y/N from user. - // Returns true if user selects "Yes", false otherwise. - - bool changeMode(std::string_view file, mode_t mode); - // Changes file permissions. - // Returns true on success. - - bool changeOwner(std::string_view file, uid_t uid, gid_t gid); - // Changes file owner and group. - // Returns true on success. - - std::string currentWorkingDirectory(); - // Returns current working directory as string. - - std::string currentDate(); - // Returns current date as string (format: YYYY-MM-DD). - - std::string currentTime(); - // Returns current time as string (format: HH:MM:SS). - - std::string runCommandWithOutput(std::string_view cmd); - // Runs system command and returns its stdout as string. - - std::string pathJoin(std::string base, std::string relative); - // Joins base path with relative path and returns result. - - std::string pathBasename(std::string_view entry); - // Returns the filename part of given path. - - std::string pathDirname(std::string_view entry); - // Returns the directory part of given path. - - uint64_t getRandomOffset(uint64_t size, uint64_t bufferSize); - // Returns random offset depending on size and bufferSize. - */ - - if (Helper::copyFile("file.txt", "backup.txt")) - std::cout << "file.txt copied to backup.txt" << std::endl; - - if (Helper::runCommand("ls -l")) - std::cout << "Command executed successfully" << std::endl; - - if (Helper::confirmPropt("Do you want to continue?")) - std::cout << "User confirmed YES" << std::endl; - else - std::cout << "User selected NO" << std::endl; - - if (Helper::changeMode("file.txt", 0644)) - std::cout << "file.txt mode changed to 644" << std::endl; - - if (Helper::changeOwner("file.txt", 1000, 1000)) - std::cout << "file.txt owner changed to uid=1000 gid=1000" << std::endl; - - std::cout << "CWD: " << Helper::currentWorkingDirectory() << std::endl; - std::cout << "Today: " << Helper::currentDate() << std::endl; - std::cout << "Now: " << Helper::currentTime() << std::endl; - - std::string output = Helper::runCommandWithOutput("echo Hello"); - std::cout << "Output: " << output << std::endl; - - std::cout << "Joined path: " << Helper::pathJoin("/home/user", "docs/file.txt") << std::endl; - std::cout << "Basename: " << Helper::pathBasename("/home/user/docs/file.txt") << std::endl; - std::cout << "Dirname: " << Helper::pathDirname("/home/user/docs/file.txt") << std::endl; - - uint64_t offset = Helper::getRandomOffset(10240, 512); - std::cout << "Random offset: " << offset << std::endl; - - /** - Android - don't throw Helper::Error - WARNING: IF AN ANDROID-SPECIFIED SYSROOT IS NOT USED, IT WILL NOT BE - ADDED AUTOMATICALLY BECAUSE THERE IS NO __ANDROID__ DECLARATION. - - std::string getProperty(std::string_view prop); - // Reads a system property. - // Returns property value as string. - // Returns empty string if property not found. - - bool reboot(std::string_view arg); - // Reboots the system with given argument. - // Example args: "reboot", "recovery", "bootloader". - // Returns true on success. - */ - - std::string model = Helper::getProperty("ro.product.model"); - if (model.empty()) - std::cout << "Cannot read property ro.product.model" << std::endl; - else - std::cout << "Device model: " << model << std::endl; - - if (Helper::reboot("recovery")) - std::cout << "Rebooting into recovery..." << std::endl; - else - std::cerr << "Failed to reboot" << std::endl; - - /** - Library-specific - don't throw Helper::Error - - std::string getLibVersion(); - // Returns library version string. - */ - - std::cout << "Helper library version: " << Helper::getLibVersion() << std::endl; -``` +* `bool copyFile(std::string_view file, std::string_view dest)` - Copy file to dest. +* `bool runCommand(std::string_view cmd)` - Run shell command. +* `bool confirmPropt(std::string_view message)` - Shows message and asks for y/N from user. +* `bool changeMode(std::string_view file, mode_t mode)` - Change file permissions. +* `bool changeOwner(std::string_view file, uid_t uid, gid_t gid)` - Change file owner (user ID and group ID). +* `std::string currentWorkingDirectory()` - Get current working directory as string. Returns empty string on error. +* `std::string currentDate()` - Get current date as string (format: YYYY-MM-DD). Returns empty string on error. +* `std::string currentTime()` - Get current time as string (format: HH:MM:SS). Returns empty string on error. +* `std::pair runCommandWithOutput(std::string_view cmd)` - Run shell command return output as string. Returns std::pair. +* `std::string pathJoin(std::string base, std::string relative)` - Joins base path with relative path and returns result. +* `std::string pathBasename(std::string_view entry)` - Get the filename part of given path. +* `std::string pathDirname(std::string_view entry)` - Get the directory part of given path. +* `uint64_t getRandomOffset(uint64_t size, uint64_t bufferSize)` - Get random offset depending on size and bufferSize. ---