OCSController.php 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Bernhard Posselt <dev@bernhard-posselt.com>
  6. * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  7. * @author Donquixote <marjunebatac@gmail.com>
  8. * @author Morris Jobke <hey@morrisjobke.de>
  9. * @author Roeland Jago Douma <roeland@famdouma.nl>
  10. * @author Stefan Weil <sw@weilnetz.de>
  11. * @author Thomas Müller <thomas.mueller@tmit.eu>
  12. *
  13. * @license AGPL-3.0
  14. *
  15. * This code is free software: you can redistribute it and/or modify
  16. * it under the terms of the GNU Affero General Public License, version 3,
  17. * as published by the Free Software Foundation.
  18. *
  19. * This program is distributed in the hope that it will be useful,
  20. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  22. * GNU Affero General Public License for more details.
  23. *
  24. * You should have received a copy of the GNU Affero General Public License, version 3,
  25. * along with this program. If not, see <http://www.gnu.org/licenses/>
  26. *
  27. */
  28. namespace OCP\AppFramework;
  29. use OCP\AppFramework\Http\DataResponse;
  30. use OCP\AppFramework\Http\Response;
  31. use OCP\IRequest;
  32. /**
  33. * Base class to inherit your controllers from that are used for RESTful APIs
  34. * @since 8.1.0
  35. */
  36. abstract class OCSController extends ApiController {
  37. public const RESPOND_UNAUTHORISED = 997;
  38. public const RESPOND_SERVER_ERROR = 996;
  39. public const RESPOND_NOT_FOUND = 998;
  40. public const RESPOND_UNKNOWN_ERROR = 999;
  41. /** @var int */
  42. private $ocsVersion;
  43. /**
  44. * constructor of the controller
  45. * @param string $appName the name of the app
  46. * @param IRequest $request an instance of the request
  47. * @param string $corsMethods comma separated string of HTTP verbs which
  48. * should be allowed for websites or webapps when calling your API, defaults to
  49. * 'PUT, POST, GET, DELETE, PATCH'
  50. * @param string $corsAllowedHeaders comma separated string of HTTP headers
  51. * which should be allowed for websites or webapps when calling your API,
  52. * defaults to 'Authorization, Content-Type, Accept'
  53. * @param int $corsMaxAge number in seconds how long a preflighted OPTIONS
  54. * request should be cached, defaults to 1728000 seconds
  55. * @since 8.1.0
  56. */
  57. public function __construct($appName,
  58. IRequest $request,
  59. $corsMethods = 'PUT, POST, GET, DELETE, PATCH',
  60. $corsAllowedHeaders = 'Authorization, Content-Type, Accept, OCS-APIRequest',
  61. $corsMaxAge = 1728000) {
  62. parent::__construct($appName, $request, $corsMethods,
  63. $corsAllowedHeaders, $corsMaxAge);
  64. $this->registerResponder('json', function ($data) {
  65. return $this->buildOCSResponse('json', $data);
  66. });
  67. $this->registerResponder('xml', function ($data) {
  68. return $this->buildOCSResponse('xml', $data);
  69. });
  70. }
  71. /**
  72. * @param int $version
  73. * @since 11.0.0
  74. * @internal
  75. */
  76. public function setOCSVersion($version) {
  77. $this->ocsVersion = $version;
  78. }
  79. /**
  80. * Since the OCS endpoints default to XML we need to find out the format
  81. * again
  82. * @param mixed $response the value that was returned from a controller and
  83. * is not a Response instance
  84. * @param string $format the format for which a formatter has been registered
  85. * @throws \DomainException if format does not match a registered formatter
  86. * @return Response
  87. * @since 9.1.0
  88. */
  89. public function buildResponse($response, $format = 'xml') {
  90. return parent::buildResponse($response, $format);
  91. }
  92. /**
  93. * Unwrap data and build ocs response
  94. * @param string $format json or xml
  95. * @param DataResponse $data the data which should be transformed
  96. * @since 8.1.0
  97. * @return \OC\AppFramework\OCS\BaseResponse
  98. */
  99. private function buildOCSResponse($format, DataResponse $data) {
  100. if ($this->ocsVersion === 1) {
  101. return new \OC\AppFramework\OCS\V1Response($data, $format);
  102. }
  103. return new \OC\AppFramework\OCS\V2Response($data, $format);
  104. }
  105. }