289 lines
6.5 KiB
Markdown
289 lines
6.5 KiB
Markdown
# libnextcloud
|
|
|
|
Cross-platform C++17 library for Nextcloud connectivity on embedded devices and homebrew platforms.
|
|
|
|
## Overview
|
|
|
|
`libnextcloud` provides a clean, modern C++ API for interacting with Nextcloud servers. It's designed to work on resource-constrained devices like game console homebrew (Nintendo 3DS, Switch, Wii U) while also supporting desktop platforms.
|
|
|
|
**Status**: 🚧 In Development - Scaffolding complete, components being implemented
|
|
|
|
## Features (Planned)
|
|
|
|
- ✅ **Version Management**: Semantic versioning with compile-time and runtime queries
|
|
- ✅ **Type System**: Comprehensive error codes and data structures
|
|
- 🚧 **WebDAV Client**: HTTP/HTTPS communication with Nextcloud WebDAV API
|
|
- 🚧 **Authentication**: Basic Auth (OAuth2 planned)
|
|
- 🚧 **File Upload**: Streaming uploads with chunking and progress tracking
|
|
- 🚧 **Folder Management**: List, create, navigate remote folders
|
|
- 🚧 **Favorites & Recent**: Persistent user preferences
|
|
|
|
## Requirements
|
|
|
|
### Build Tools
|
|
- **CMake** 3.15 or later
|
|
- **C++17 compiler**: GCC 7+, Clang 5+, MSVC 2017+
|
|
|
|
### Dependencies
|
|
|
|
**Required** (when implementation complete):
|
|
- libcurl 7.68+
|
|
- mbedTLS 2.16+
|
|
- tinyxml2 9.0+
|
|
|
|
**Testing**:
|
|
- Google Test 1.11+
|
|
|
|
**Header-Only**:
|
|
- nlohmann/json 3.10+ (for configuration, future)
|
|
|
|
### Platform Support
|
|
|
|
| Platform | Status | Notes |
|
|
|----------|--------|-------|
|
|
| Linux | ✅ Development | Primary development platform |
|
|
| Nintendo 3DS | ✅ Planned | Via devkitARM in container |
|
|
| Nintendo Switch | 🔜 Planned | |
|
|
| Wii U | 🔜 Planned | |
|
|
| PlayStation Vita | 🔜 Planned | |
|
|
| Windows | 🔜 Planned | |
|
|
| macOS | 🔜 Planned | |
|
|
|
|
## Quick Start
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Configure (modern CMake style)
|
|
cmake -S . -B build
|
|
|
|
# Build
|
|
cmake --build build
|
|
|
|
# Run tests
|
|
cmake --build build --target test
|
|
# or with CTest for detailed output:
|
|
# ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
### Using in Your Project
|
|
|
|
#### CMake
|
|
|
|
```cmake
|
|
find_package(nextcloud REQUIRED)
|
|
|
|
add_executable(my_app main.cpp)
|
|
target_link_libraries(my_app nextcloud::nextcloud)
|
|
```
|
|
|
|
#### pkg-config
|
|
|
|
```bash
|
|
g++ -std=c++17 main.cpp $(pkg-config --cflags --libs libnextcloud)
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```cpp
|
|
#include <nextcloud/version.hpp>
|
|
#include <nextcloud/types.hpp>
|
|
#include <iostream>
|
|
|
|
int main() {
|
|
// Get library version
|
|
std::cout << "libnextcloud v" << nextcloud::getVersionString() << std::endl;
|
|
|
|
// Check version compatibility
|
|
if (nextcloud::isVersionAtLeast(0, 1, 0)) {
|
|
std::cout << "Version is compatible!" << std::endl;
|
|
}
|
|
|
|
// Use error types
|
|
nextcloud::NextcloudError error = nextcloud::NextcloudError::Success;
|
|
std::cout << "Status: " << nextcloud::errorToString(error) << std::endl;
|
|
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
shared/
|
|
├── CMakeLists.txt # Build configuration
|
|
├── README.md # This file
|
|
├── libnextcloud.pc.in # pkg-config template
|
|
├── nextcloudConfig.cmake.in # CMake config template
|
|
├── include/
|
|
│ └── nextcloud/
|
|
│ ├── version.hpp # Version information
|
|
│ ├── types.hpp # Common types and errors
|
|
│ ├── webdav_client.hpp # (Coming soon)
|
|
│ ├── auth.hpp # (Coming soon)
|
|
│ ├── upload_manager.hpp # (Coming soon)
|
|
│ ├── folder_manager.hpp # (Coming soon)
|
|
│ └── config.hpp # (Coming soon)
|
|
├── src/ # Implementation files (future)
|
|
├── tests/
|
|
│ ├── CMakeLists.txt
|
|
│ └── smoke_test.cpp # Basic tests
|
|
├── examples/ # Usage examples (future)
|
|
└── docs/ # Documentation (future)
|
|
```
|
|
|
|
## Building for Platforms
|
|
|
|
### Linux (Development)
|
|
|
|
```bash
|
|
mkdir build && cd build
|
|
cmake ..
|
|
make
|
|
make test
|
|
```
|
|
|
|
### Nintendo 3DS (Container)
|
|
|
|
```bash
|
|
# From project root
|
|
podman run --rm -v .:/project:z tomusan/devkitarm-3ds:latest \
|
|
bash -c "cd /project/shared && mkdir -p build && cd build && cmake .. && make"
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
### Version Information
|
|
|
|
```cpp
|
|
#include <nextcloud/version.hpp>
|
|
|
|
// Constants
|
|
nextcloud::VERSION_MAJOR // 0
|
|
nextcloud::VERSION_MINOR // 1
|
|
nextcloud::VERSION_PATCH // 0
|
|
nextcloud::VERSION_STRING // "0.1.0"
|
|
|
|
// Functions
|
|
std::string getVersionString();
|
|
void getVersion(int& major, int& minor, int& patch);
|
|
bool isVersionAtLeast(int major, int minor, int patch);
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
```cpp
|
|
#include <nextcloud/types.hpp>
|
|
|
|
// Error codes
|
|
enum class NextcloudError {
|
|
Success,
|
|
NetworkError,
|
|
AuthenticationFailed,
|
|
ServerError,
|
|
FileNotFound,
|
|
// ... more error codes
|
|
};
|
|
|
|
// Convert to string
|
|
const char* errorToString(NextcloudError error);
|
|
|
|
// Result type
|
|
nextcloud::Result<int> result;
|
|
if (result.isSuccess()) {
|
|
// Use result.value
|
|
} else {
|
|
std::cerr << result.errorMessage() << std::endl;
|
|
}
|
|
```
|
|
|
|
### Data Structures
|
|
|
|
```cpp
|
|
// Upload progress
|
|
struct UploadProgress {
|
|
std::string filename;
|
|
uint64_t bytesUploaded;
|
|
uint64_t totalBytes;
|
|
float percentComplete;
|
|
float bytesPerSecond;
|
|
int secondsRemaining;
|
|
};
|
|
|
|
// File information
|
|
struct FileInfo {
|
|
std::string name;
|
|
std::string path;
|
|
bool isDirectory;
|
|
uint64_t size;
|
|
std::time_t modifiedTime;
|
|
std::string contentType;
|
|
};
|
|
|
|
// Folder information
|
|
struct FolderInfo {
|
|
std::string path;
|
|
std::string displayName;
|
|
std::time_t lastUsed;
|
|
bool isFavorite;
|
|
};
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
cd build
|
|
ctest --output-on-failure
|
|
|
|
# Or use the custom target
|
|
make run_tests
|
|
|
|
# Run specific test
|
|
./tests/smoke_test
|
|
```
|
|
|
|
## Development Status
|
|
|
|
- ✅ **Phase 1: Scaffolding** - Complete
|
|
- Directory structure
|
|
- CMake build system
|
|
- Version and types headers
|
|
- Google Test integration
|
|
- Basic smoke tests
|
|
|
|
- 🚧 **Phase 2: WebDAV Client** - Not started
|
|
- Issue #8
|
|
|
|
- 🚧 **Phase 3: Authentication** - Not started
|
|
- Issue #9
|
|
|
|
- 🚧 **Phase 4: Upload Manager** - Not started
|
|
- Issue #10
|
|
|
|
- 🚧 **Phase 5: Folder Management** - Not started
|
|
- Issue #11
|
|
|
|
- 🚧 **Phase 6: Favorites & Recent** - Not started
|
|
- Issue #12
|
|
|
|
- 🚧 **Phase 7: Testing & Docs** - Not started
|
|
- Issue #13
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](../CONTRIBUTING.md) in the project root.
|
|
|
|
## License
|
|
|
|
[License TBD - to be determined]
|
|
|
|
## Related Documentation
|
|
|
|
- [Project Plan](../.plans/CreateLibNextcloud.md)
|
|
- [Issue #25](https://git.tomusan.com/maj/nextcloud-share/issues/25) - Initialize libnextcloud
|
|
|
|
---
|
|
|
|
**Note**: This library is in active development. The API is subject to change until version 1.0.0.
|