Updated Library Documentation (markdown)
@@ -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 <libhelper/lib.hpp>
|
||||
#include <iostream>
|
||||
#include <string.h>
|
||||
|
||||
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 <libhelper/lib.hpp>
|
||||
#include <iostream>
|
||||
#include <stdio.h>
|
||||
#### 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<std::string> 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<std::string> 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<std::string> 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<std::string> 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<std::string, int> runCommandWithOutput(std::string_view cmd)` - Run shell command return output as string. Returns std::pair<std::string, int>.
|
||||
* `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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user