moodle/repository/nextcloud/classes/ocs_client.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * REST interface to Nextcloud's implementation of Open Collaboration Services.
 *
 * @package    repository_nextcloud
 * @copyright  2017 Jan Dageförde (Learnweb, University of Münster)
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
namespace repository_nextcloud;

use core\oauth2\client;
use core\oauth2\rest;

defined('MOODLE_INTERNAL') || die();

/**
 * REST interface to Nextcloud's implementation of Open Collaboration Services.
 *
 * @package    repository_nextcloud
 * @copyright  2017 Jan Dageförde (Learnweb, University of Münster)
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class ocs_client extends rest {

    /**
     * shareType=0 creates a private user share.
     */
    const SHARE_TYPE_USER = 0;

    /**
     * shareType=3 creates a public share.
     */
    const SHARE_TYPE_PUBLIC = 3;

    /**
     * permissions=1 gives read permission for a share.
     */
    const SHARE_PERMISSION_READ = 1;

    /**
     * permissions=1 gives read permission for a share.
     */
    const SHARE_PERMISSION_ALL = 31;

    /**
     * OCS endpoint as configured for the used issuer.
     * @var \moodle_url
     */
    private $ocsendpoint;


    /**
     * Get endpoint URLs from the used issuer to use them in get_api_functions().
     * @param client $oauthclient OAuth-authenticated Nextcloud client
     * @throws configuration_exception Exception if critical endpoints are missing.
     * @throws \moodle_exception when trying to construct a moodleurl
     */
    public function __construct(client $oauthclient) {
        parent::__construct($oauthclient);

        $issuer = $oauthclient->get_issuer();
        $ocsendpoint = $issuer->get_endpoint_url('ocs');
        if ($ocsendpoint === false) {
            throw new configuration_exception('Endpoint ocs_endpoint not defined.');
        }
        $this->ocsendpoint = new \moodle_url($ocsendpoint);
        if (empty($this->ocsendpoint->get_param('format'))) {
            $this->ocsendpoint->params(array('format' => 'xml'));
        }
    }

    /**
     * Define relevant functions of the OCS API.
     *
     * Previously, the instruction to create a oauthclient recommended the user to enter the return format (format=xml).
     * However, in this case the shareid is appended at the wrong place. Therefore, a new url is build which inserts the
     * shareid at the suitable place for delete_share and get_information_of_share.
     * create_share docs: https://docs.nextcloud.com/server/13/developer_manual/core/ocs-share-api.html#create-a-new-share
     *
     */
    public function get_api_functions() {
        return [
            'create_share' => [
                'endpoint' => $this->ocsendpoint->out(false),
                'method' => 'post',
                'args' => [
                    'path' => PARAM_TEXT, // Could be PARAM_PATH, we really don't want to enforce a Moodle understanding of paths.
                    'shareType' => PARAM_INT,
                    'shareWith' => PARAM_TEXT, // Name of receiving user/group. Required if SHARE_TYPE_USER.
                    'publicUpload' => PARAM_RAW, // Actually Boolean, but neither String-Boolean ('false') nor PARAM_BOOL (0/1).
                    'permissions' => PARAM_INT,
                    'shareWith' => PARAM_TEXT,
                    'expireDate' => PARAM_TEXT
                ],
                'response' => 'text/xml'
            ],
            'delete_share' => [
                'endpoint' => $this->build_share_url(),
                'method' => 'delete',
                'args' => [
                    'share_id' => PARAM_INT
                ],
                'response' => 'text/xml'
            ],
            'get_shares' => [
                'endpoint' => $this->ocsendpoint->out(false),
                'method' => 'get',
                'args' => [
                    'path' => PARAM_TEXT,
                    'reshares' => PARAM_RAW, // Returns not only the shares from the current user but all of the given file.
                    'subfiles' => PARAM_RAW, // Returns all shares within a folder, given that path defines a folder.
                ],
                'response' => 'text/xml'
            ],
            'get_information_of_share' => [
                'endpoint' => $this->build_share_url(),
                'method' => 'get',
                'args' => [
                    'share_id' => PARAM_INT
                ],
                'response' => 'text/xml'
            ],
        ];
    }

    /**
     * Private Function to return a url with the shareid in the path.
     * @return string
     */
    private function build_share_url() {
        // Out_omit_querystring() in combination with ocsendpoint->get_path() is not used since both function include
        // /ocs/v1.php.
        $shareurl = $this->ocsendpoint->get_scheme() . '://' . $this->ocsendpoint->get_host() . ':' .
            $this->ocsendpoint->get_port() . $this->ocsendpoint->get_path() . '/{share_id}?' .
            $this->ocsendpoint->get_query_string(false);
        return $shareurl;
    }

    /**
     * In POST requests, Moodle's REST API assumes that params are
     * - transmitted as part of the URL or
     * - expressed in JSON.
     * Neither is true; we are passing an array to $functionargs which is then put into CURLOPT_POSTFIELDS.
     * Curl assumes the content type to be `multipart/form-data` then, but the Moodle REST API tries to put
     * a JSON content type. As a result, clients would fail.
     * To make this less tedious to use, we assume that the params-as-array-in-$functionargs is the default for us.
     *
     * @param string $functionname Name of a function from get_api_functions()
     * @param array $functionargs Request parameters
     * @param bool|string $rawpost Optional param to include in the body of a post
     * @param bool|string $contenttype Content type of the request body. Default: multipart/form-data if !$rawpost, JSON otherwise
     * @return object|string
     * @throws \coding_exception
     * @throws \core\oauth2\rest_exception
     */
    public function call($functionname, $functionargs, $rawpost = false, $contenttype = false) {
        if ($rawpost === false && $contenttype === false) {
            return parent::call($functionname, $functionargs, false, 'multipart/form-data');
        } else {
            return parent::call($functionname, $functionargs, $rawpost, $contenttype);
        }
    }

}