nextcloud-share/shared/README.md

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

# 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

find_package(nextcloud REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app nextcloud::nextcloud)

pkg-config

g++ -std=c++17 main.cpp $(pkg-config --cflags --libs libnextcloud)

Basic Usage

#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)

mkdir build && cd build
cmake ..
make
make test

Nintendo 3DS (Container)

# 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

#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

#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

// 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

# 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 in the project root.

License

[License TBD - to be determined]

Related Documentation

• Project Plan
• Issue #25 - Initialize libnextcloud

---

Note: This library is in active development. The API is subject to change until version 1.0.0.