Your IP : 192.168.165.1
<?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);
}
}
}