feat(lib): initialize libnextcloud C++17 library scaffolding (#25)
This commit is contained in:
288
shared/README.md
Normal file
288
shared/README.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user