Skip to content

Commit 9cdb707

Browse files
KrasnovvvvvKrasnovvvvv
committed
Merge branch 'dev'
2 parents 8e79c97 + 241cd3a commit 9cdb707

2 files changed

Lines changed: 153 additions & 74 deletions

File tree

‎README.md‎

Lines changed: 105 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -17,46 +17,51 @@ A simple, lightweight, and efficient static library for integrating Yandex.Disk
1717

1818
🔥 Now available on vcpkg – install in one command!
1919

20-
You can quickly install the library using [vcpkg](#-new-installation-via-vcpkg-is-now-available)
20+
You can quickly install the library using [vcpkg](#-installation-via-vcpkg)
2121

2222
---
2323

2424
## ✨ Features
2525

26-
- **Full API Coverage:**
27-
Upload and download files and directories, manage directories, move and rename resources, handle trash operations, publish/unpublish files, and retrieve public download links
26+
- **Wide API Coverage:**
27+
Upload and download files and directories, manage directories, move and rename resources, handle trash operations, publish and unpublish files, and retrieve public links
2828

2929
- **Robust File Management:**
30-
Recursive upload/download of directories, existence checks, and detailed resource information retrieval
30+
Recursive upload and download of directories, existence checks, and detailed resource information retrieval
3131

3232
- **Trash Support:**
33-
List trash contents, restore files/folders to original locations, delete individual items or empty the entire trash
33+
List trash contents, restore files or folders to original locations, delete individual items, or empty the entire trash
3434

3535
- **Search Functionality:**
36-
Find files and folders by name both on the disk and in the trash, supporting recursive search and multiple matches
36+
Find files and folders by name both on the disk and in the trash, with recursive search support
3737

3838
- **Cross-Platform Compatibility:**
39-
Works on Windows, Linux, and macOS with support for Unicode paths
39+
Works on Windows, Linux, and macOS with Unicode path support
4040

4141
- **Minimal Dependencies:**
42-
Depends only on `libcurl` for HTTP communication and `nlohmann/json` for JSON parsing
42+
Uses only `libcurl` for HTTP communication and `nlohmann/json` for JSON parsing
4343

4444
- **Easy Integration:**
45-
Provided as a static library with a clean header interface for straightforward inclusion in your projects
45+
Provided as a static library with a clean public header interface for straightforward use in CMake projects
4646

4747
---
4848

4949
## 📁 Project Structure
50-
```
50+
51+
```text
5152
yandex-disk-cpp-client/
52-
├── docs # Generated documentation via Doxygen
53+
├── .github/workflows/ # GitHub Actions CI
54+
├── cmake/ # Package config templates
55+
├── docs/ # Generated Doxygen documentation and extra docs
5356
├── examples/ # Example usage programs
54-
├── include/ # Public headers (YandexDiskClient.h)
55-
├── src/ # Library source files (YandexDiskClient.cpp)
56-
├── CMakeLists.txt # Build configuration
57+
├── include/ # Public headers
58+
├── src/ # Library source files
59+
├── tests/ # Unit tests and test CMake configuration
60+
├── CMakeLists.txt # Root build configuration
61+
├── vcpkg.json # vcpkg manifest dependencies
5762
├── README.md # This file
5863
├── LICENSE # License file
59-
├── .gitignore # Git ignore rules
64+
└── .gitignore # Git ignore rules
6065
```
6166

6267
---
@@ -65,63 +70,81 @@ yandex-disk-cpp-client/
6570

6671
### 🛠️ Prerequisites
6772

68-
- C++17 compatible compiler (GCC, Clang, MSVC)
73+
- C++17 compatible compiler
6974
- CMake 3.28 or newer
70-
- libcurl
71-
- nlohmann/json
72-
- Environment variable `YADISK_TOKEN` with your Yandex.Disk OAuth token **(full disk access)**
75+
- [vcpkg](https://github.com/microsoft/vcpkg)
76+
- Yandex.Disk OAuth token with the required permissions
77+
78+
### 🔑 OAuth Token
79+
80+
Set the `YADISK_TOKEN` environment variable before running examples or your own application.
81+
82+
Detailed step-by-step instructions for registering a Yandex OAuth application and obtaining a token are available in [`docs/OAUTH_TOKEN.md`](docs/OAUTH_TOKEN.md).
7383

7484
### ⚡ Build and Run Example
7585

7686
```sh
7787
git clone https://github.com/Krasnovvvvv/yandex-disk-cpp-client.git
7888
cd yandex-disk-cpp-client
79-
mkdir build && cd build
80-
cmake ..
81-
cmake --build .
82-
./example_basic_usage
89+
90+
cmake -B build -S . \
91+
-DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake \
92+
-DBUILD_EXAMPLES=ON
93+
94+
cmake --build build
8395
```
8496

85-
### 🔥 New! Installation via vcpkg is now available
97+
Then run an example executable, for example:
8698

87-
You can now install **yandex-disk-cpp-client** directly from the official [vcpkg](https://github.com/microsoft/vcpkg) registry
88-
This makes setup and integration seamless for CMake-based projects
99+
```sh
100+
./build/example_basic_usage
101+
```
89102

90-
#### Install
103+
On Windows:
104+
105+
```powershell
106+
.\build\Debug\example_basic_usage.exe
107+
```
108+
109+
---
110+
111+
## 📦 Installation via vcpkg
91112

92-
Run the following command:
113+
You can install **yandex-disk-cpp-client** directly from the official [vcpkg](https://github.com/microsoft/vcpkg) registry.
114+
115+
#### Install
93116

94117
```bash
95118
vcpkg install yandex-disk-cpp-client
96119
```
97120

98-
If you’re using a specific triplet (e.g., MinGW or Linux static), specify it explicitly:
121+
If you use a specific triplet:
99122

100123
```bash
101124
vcpkg install yandex-disk-cpp-client:x64-mingw-static
102125
```
103126

104127
#### Use in CMake
105128

106-
Once installed, simply include vcpkg’s toolchain and use `find_package` to link the library:
107-
108129
```cmake
109130
find_package(yandex-disk-cpp-client CONFIG REQUIRED)
110131
target_link_libraries(example PRIVATE yandex-disk-cpp-client::yandex-disk-cpp-client)
111132
```
112133

113-
#### That’s it!
134+
#### Notes
114135

115-
- Dependencies such as **libcurl** and **nlohmann-json** are automatically resolved by vcpkg
116-
- Works out of the box on Windows, Linux, and macOS
136+
- `libcurl` and `nlohmann-json` are resolved automatically via vcpkg
137+
- Works on Windows, Linux, and macOS
138+
- Useful both for local development and CI environments
117139

118140
---
119141

120-
### 📖 Example Usage
142+
## 📖 Example Usage
121143

122144
```cpp
123145
#include "YandexDiskClient.h"
124-
#include <cstdlib> // for getenv
146+
#include <cstdlib>
147+
#include <iostream>
125148

126149
int main() {
127150
const char* token = std::getenv("YADISK_TOKEN");
@@ -132,71 +155,79 @@ int main() {
132155

133156
YandexDiskClient yandex(token);
134157

135-
// Upload a file
136-
yandex.uploadFile("/backup/data.zip", "C:/local/data.zip");
158+
auto quota = yandex.getQuotaInfo();
159+
std::cout << yandex.formatQuotaInfo(quota) << std::endl;
137160

138-
// List root directory contents
139161
auto list = yandex.getResourceList("/");
140162
std::cout << yandex.formatResourceList(list) << std::endl;
141163

142164
return 0;
143165
}
144166
```
145-
> For more examples, see `examples/`
167+
168+
> For more examples, see [`examples/`](examples/)
146169
147170
---
148171

149-
## 🧭 API Overview
150-
151-
| Function | Description |
152-
|------------------------------------------|-----------------------------------------------------------|
153-
| `getQuotaInfo()` | Retrieve disk quota info (total, used, trash size) |
154-
| `getResourceList(path)` | List files and folders at a given disk path |
155-
| `getResourceInfo(path)` | Get detailed info about a file or folder |
156-
| `uploadFile(disk_path, local_path)` | Upload a local file to disk |
157-
| `downloadFile(disk_path, local_path)` | Download a file from disk to local path |
158-
| `uploadDirectory(disk_path, local_path)` | Recursively upload a directory |
159-
| `downloadDirectory(disk_path, local_path)`| Recursively download a directory |
160-
| `deleteFileOrDir(path)` | Delete a file or directory |
161-
| `createDirectory(path)` | Create a directory |
162-
| `moveFileOrDir(from, to, overwrite)` | Move or rename a file or directory |
163-
| `publish(path)` | Publish a file or folder (make public) |
164-
| `unpublish(path)` | Remove public access |
165-
| `getPublicDownloadLink(path)` | Get public download URL |
166-
| `exists(path)` | Check if a file or folder exists |
167-
| `getTrashResourceList(path)` | List contents of trash |
168-
| `restoreFromTrash(path)` | Restore file/folder from trash to original location |
169-
| `deleteFromTrash(path)` | Permanently delete from trash |
170-
| `emptyTrash()` | Empty the entire trash |
171-
| `findTrashPathByName(name)` | Find all trash items by name |
172-
| `findResourcePathByName(name, start_path)`| Find all disk items by name, recursively |
172+
## 🧭 API Coverage
173+
174+
| Category | Methods |
175+
|----------|---------|
176+
| Disk info | `getQuotaInfo()`, `formatQuotaInfo()` |
177+
| Resource listing | `getResourceList(path)`, `formatResourceList(json)`, `getResourceInfo(path)` |
178+
| File operations | `uploadFile(disk_path, local_path)`, `downloadFile(disk_path, local_path)` |
179+
| Directory operations | `createDirectory(path)`, `uploadDirectory(disk_path, local_path)`, `downloadDirectory(disk_path, local_path)` |
180+
| Resource management | `deleteFileOrDir(path)`, `moveFileOrDir(from, to, overwrite)`, `renameFileOrDir(path, new_name, overwrite)`, `exists(path)` |
181+
| Public access | `publish(path)`, `unpublish(path)`, `getPublicDownloadLink(path)` |
182+
| Trash operations | `getTrashResourceList(path)`, `formatTrashResourceList(json)`, `restoreFromTrash(path)`, `deleteFromTrash(path)`, `emptyTrash()` |
183+
| Search | `findResourcePathByName(name, start_path)`, `findTrashPathByName(name)` |
173184

174185
---
175186

176-
## 📦 Dependencies
187+
## 🧪 Tests
177188

178-
- [libcurl](https://curl.se/libcurl/) — for HTTP requests
179-
- [nlohmann/json](https://github.com/nlohmann/json) — for JSON parsing
189+
Unit tests are located in the [`tests/`](tests/) directory and are built through a dedicated `tests/CMakeLists.txt`.
180190

181-
> These dependencies are automatically handled via CMake (assuming installed on your system or via package managers like vcpkg)
191+
To build and run tests:
192+
193+
```sh
194+
cmake -B build -S . \
195+
-DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake \
196+
-DBUILD_TESTS=ON \
197+
-DBUILD_EXAMPLES=OFF
198+
199+
cmake --build build
200+
ctest --test-dir build --output-on-failure
201+
```
182202

183203
---
184204

185205
## 📚 Documentation
186206

187-
Full API documentation is generated using Doxygen and available in the `docs/` folder
188-
You can also access the online documentation via GitHub Pages [![Documentation](https://img.shields.io/badge/docs-online-blue)](https://Krasnovvvvv.github.io/yandex-disk-cpp-client/)
207+
API documentation is generated with Doxygen and published from the `docs/` directory.
208+
209+
Online documentation:
210+
[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://Krasnovvvvv.github.io/yandex-disk-cpp-client/)
211+
212+
---
213+
214+
## 📦 Dependencies
215+
216+
- [libcurl](https://curl.se/libcurl/) — HTTP requests
217+
- [nlohmann/json](https://github.com/nlohmann/json) — JSON parsing
218+
- [GoogleTest](https://github.com/google/googletest) — unit tests only
219+
220+
If you use vcpkg manifest mode, dependencies are installed automatically from `vcpkg.json`.
189221

190222
---
191223

192224
## 🤝 Contribution
193225

194-
Contributions, bug reports, and feature requests are welcome!
195-
Please open issues or pull requests on the GitHub repository
226+
Contributions, bug reports, and feature requests are welcome.
227+
Please open an issue or submit a pull request.
196228

197229
---
198230

199231
## 📝 License
200232

201-
This project is licensed under the MIT License — see [![License](https://img.shields.io/github/license/Krasnovvvvv/yandex-disk-cpp-client)](LICENSE)
202-
233+
This project is licensed under the MIT License — see [LICENSE](LICENSE)

‎docs/OAUTH_TOKEN.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# 🔑 Getting a Yandex.Disk OAuth Token
2+
3+
## 1. Register an application
4+
5+
Create a Yandex OAuth application using the official developer portal.
6+
7+
Official guide:
8+
https://yandex.ru/dev/id/doc/ru/register-client
9+
10+
## 2. Save the client ID
11+
12+
After registration, copy your application's client ID.
13+
14+
## 3. Open the authorization URL
15+
16+
Replace `YOUR_CLIENT_ID` and open this URL in the browser:
17+
18+
```text
19+
https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
20+
```
21+
22+
## 4. Approve access
23+
24+
Sign in with your Yandex account and grant the requested permissions.
25+
26+
## 5. Copy the token
27+
28+
After successful authorization, the access token will be returned in the redirect URL fragment.
29+
30+
## 6. Export the token locally
31+
32+
Linux/macOS:
33+
34+
```bash
35+
export YADISK_TOKEN="your_token_here"
36+
```
37+
38+
Windows PowerShell:
39+
40+
```powershell
41+
$env:YADISK_TOKEN="your_token_here"
42+
```
43+
44+
## Notes
45+
46+
- Never commit real tokens to Git
47+
- Do not hardcode tokens in examples
48+
- Prefer environment variables for local development

0 commit comments

Comments
 (0)