Class: Nextcloud::Ocs::FileSharingApi

Inherits:
Nextcloud::OcsApi show all
Includes:
Helpers
Defined in:
lib/nextcloud/ocs/file_sharing_api.rb

Overview

File sharing base class used for interfering with sharing, included federated

Defined Under Namespace

Classes: FederatedCloudShares

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#add_meta, #doc_to_hash, #get_meta, #has_dav_errors, #parse_dav_response, #parse_with_meta, #path_from_href

Methods inherited from Nextcloud::OcsApi

#app, #file_sharing, #group, #user

Methods inherited from Api

#ocs, #request, #webdav

Constructor Details

#initialize(args) ⇒ FileSharingApi

Initializes API with user credentials

Parameters:

  • args (Hash) —

    authentication credentials.

Options Hash (args):

  • :url (String) —

    Nextcloud instance URL

  • :username (String) —

    Nextcloud instance user username

  • :password (String) —

    Nextcloud instance user password



20
21
22
23
24
25
26
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 20

def initialize(args)
  super(args)

  @url = URI(
    @url.scheme + "://" + @url.host + "/ocs/v2.php/apps/files_sharing/api/v1/"
  )
end

Instance Attribute Details

#meta ⇒ Hash

Returns Information about API response.

Returns:

  • (Hash) —

    Information about API response



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 9

class FileSharingApi < OcsApi
  include Helpers

  attr_accessor :meta

  # Initializes API with user credentials
  #
  # @param [Hash] args authentication credentials.
  # @option args [String] :url Nextcloud instance URL
  # @option args [String] :username Nextcloud instance user username
  # @option args [String] :password Nextcloud instance user password
  def initialize(args)
    super(args)

    @url = URI(
      @url.scheme + "://" + @url.host + "/ocs/v2.php/apps/files_sharing/api/v1/"
    )
  end

  # Get information about specific share
  #
  # @param shareid [Integer]
  # @return [Hash] Information about share with meta
  def find(shareid)
    response = request(:get, "shares/#{shareid}")
    h = doc_to_hash(response, "//data/element").try(:[], "element")
    add_meta(response, h)
  end

  # Get all shares
  #
  # @return [Array] All shares of authenticated user
  def all
    response = request(:get, "shares")
    h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
    h = [h] if h.class == Hash
    add_meta(response, h)
  end

  # Get shares for a file or directory
  # optionally get shares including re-shares on a resource
  # or get shares for all the files in a directory
  #
  # @param path [String]
  # @param reshares [Boolean,nil]
  # @param subfiles [Boolean,nil]
  # @return [Array] Shares (may include re-shares for a file or directory) of a resource or all reshares of
  #   directory contents
  def specific(path, reshares = nil, subfiles = nil)
    response = request(:get, "shares?path=#{path}&reshares=#{reshares}&subfiles=#{subfiles}")
    h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
    h = [h] if h.class == Hash
    add_meta(response, h)
  end

  # Share an item
  #
  # @param path [String] Path of a file or directory to share
  # @param shareType [Integer] One of four possible values. 0 means an user, 1 means a group, 3 means a public link
  #   6 stands for federated cloud share
  # @param shareWith [String,nil] User or group identifier, can be omitted if shareType is neither 0, nor 1
  # @param publicUpload [Boolean,nil] If true, permits public uploads in directories shared by link
  # @param password [String,nil] Password-protects a share
  # @param permissions [Integer,nil] Sets permissions on a resource. 1 gives read rights, 2 update, 4 create,
  #   8 delete
  #  16 share, 31 all rights. Value should be one of previously listed.
  # @return [Object] Instance including meta response
  def create(path, shareType, shareWith=nil, publicUpload=nil, password=nil, permissions=nil)
    args = local_variables.reduce({}) { |c, i| c[i] = binding.local_variable_get(i); c }
    response = request(:post, "/shares", args)
    (@meta = get_meta(response)) && self
  end

  # Unshare an item
  #
  # @param shareid [Integer] Share ID
  # @return [Object] Instance with meta response
  def destroy(shareid)
    response = request(:delete, "/shares/#{shareid}")
    (@meta = get_meta(response)) && self
  end

  # Update permissions for a resource
  #
  # @param shareid [Integer] Share identifier
  # @param permissions [Integer] Must be one of the following: 1: read, 2: update, 4: create, 8: delete, 16: share,
  #   31: all rights.
  # @return [Object] Instance with meta response
  def update_permissions(shareid, permissions)
    update(shareid, "permissions", permissions)
  end

  # Update a password for a resource
  #
  # @param shareid [Integer] Share identifier
  # @param password [String] Password string
  # @return [Object] Instance with meta response
  def update_password(shareid, password)
    update(shareid, "password", password)
  end

  # Allow or disallow public uploads in a directory
  #
  # @param shareid [Integer] Share identifier
  # @param publicUpload [Boolean] True to permit public uploads in a directory, false to disallow
  # @return [Object] Instance with meta response
  def update_public_upload(shareid, publicUpload)
    update(shareid, "publicUpload", publicUpload)
  end

  # Update resource expiration date
  #
  # @param shareid [Integer] Share identifier
  # @param expireDate [String] Expiration date of a resource. Has to be in format of "YYYY-DD-MM"
  # @return [Object] Instance with meta response
  def update_expire_date(shareid, expireDate)
    update(shareid, "expireDate", expireDate)
  end

  # Wrapper to Federated Cloud Sharing API
  #
  # @!attribute [rw] meta
  #   @return [Hash] Information about API response
  class FederatedCloudShares
    include Helpers

    attr_accessor :meta

    # Creates Federated Cloud Sharing class instance
    #
    # @param api [Object] Api object
    def initialize(api)
      @api = api
    end

    # List accepted Federated Cloud Shares
    #
    # @return [Array] List of accepted Federated Cloud Shares
    def accepted
      response = @api.request(:get, "/remote_shares")
      h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
      h = [h] if h.class == Hash
      add_meta(response, h)
    end

    # List pending requests of Federated Cloud Shares
    #
    # @return [Array] List of pending Federated Cloud Shares
    def pending
      response = @api.request(:get, "/remote_shares/pending")
      h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
      h = [h] if h.class == Hash
      add_meta(response, h)
    end

    # Accept a request of a Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Object] Instance with meta response
    def accept(shareid)
      response = @api.request(:post, "/remote_shares/pending/#{shareid}")
      (@meta = get_meta(response)) && self
    end

    # Decline a request of a Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Object] Instance with meta response
    def decline(shareid)
      response = @api.request(:delete, "/remote_shares/pending/#{shareid}")
      (@meta = get_meta(response)) && self
    end

    # Delete an accepted Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Object] Instance with meta response
    def destroy(shareid)
      response = @api.request(:delete, "/remote_shares/#{shareid}")
      (@meta = get_meta(response)) && self
    end

    # Information about accepted Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Hash] Information about Federated Cloud Share with meta response
    def find(shareid)
      response = @api.request(:get, "/remote_shares/#{shareid}")
      h = doc_to_hash(response, "//data").try(:[], "data")
      add_meta(response, h)
    end
  end

  # Initiates a Federated Cloud Sharing class
  def federated
    FederatedCloudShares.new(self)
  end

  private

  # Update a resource
  #
  # @param shareid [Integer] Share identifier
  # @param key [String] Option to update
  # @param value [String] Setting to update to
  # @return [Object] Instance with meta information
  def update(shareid, key, value)
    response = request(:put, "/shares/#{shareid}", "#{key}": value)
    (@meta = get_meta(response)) && self
  end
end

#shareid ⇒ Integer

Returns Share identifier.

Returns:

  • (Integer) —

    Share identifier



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 9

class FileSharingApi < OcsApi
  include Helpers

  attr_accessor :meta

  # Initializes API with user credentials
  #
  # @param [Hash] args authentication credentials.
  # @option args [String] :url Nextcloud instance URL
  # @option args [String] :username Nextcloud instance user username
  # @option args [String] :password Nextcloud instance user password
  def initialize(args)
    super(args)

    @url = URI(
      @url.scheme + "://" + @url.host + "/ocs/v2.php/apps/files_sharing/api/v1/"
    )
  end

  # Get information about specific share
  #
  # @param shareid [Integer]
  # @return [Hash] Information about share with meta
  def find(shareid)
    response = request(:get, "shares/#{shareid}")
    h = doc_to_hash(response, "//data/element").try(:[], "element")
    add_meta(response, h)
  end

  # Get all shares
  #
  # @return [Array] All shares of authenticated user
  def all
    response = request(:get, "shares")
    h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
    h = [h] if h.class == Hash
    add_meta(response, h)
  end

  # Get shares for a file or directory
  # optionally get shares including re-shares on a resource
  # or get shares for all the files in a directory
  #
  # @param path [String]
  # @param reshares [Boolean,nil]
  # @param subfiles [Boolean,nil]
  # @return [Array] Shares (may include re-shares for a file or directory) of a resource or all reshares of
  #   directory contents
  def specific(path, reshares = nil, subfiles = nil)
    response = request(:get, "shares?path=#{path}&reshares=#{reshares}&subfiles=#{subfiles}")
    h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
    h = [h] if h.class == Hash
    add_meta(response, h)
  end

  # Share an item
  #
  # @param path [String] Path of a file or directory to share
  # @param shareType [Integer] One of four possible values. 0 means an user, 1 means a group, 3 means a public link
  #   6 stands for federated cloud share
  # @param shareWith [String,nil] User or group identifier, can be omitted if shareType is neither 0, nor 1
  # @param publicUpload [Boolean,nil] If true, permits public uploads in directories shared by link
  # @param password [String,nil] Password-protects a share
  # @param permissions [Integer,nil] Sets permissions on a resource. 1 gives read rights, 2 update, 4 create,
  #   8 delete
  #  16 share, 31 all rights. Value should be one of previously listed.
  # @return [Object] Instance including meta response
  def create(path, shareType, shareWith=nil, publicUpload=nil, password=nil, permissions=nil)
    args = local_variables.reduce({}) { |c, i| c[i] = binding.local_variable_get(i); c }
    response = request(:post, "/shares", args)
    (@meta = get_meta(response)) && self
  end

  # Unshare an item
  #
  # @param shareid [Integer] Share ID
  # @return [Object] Instance with meta response
  def destroy(shareid)
    response = request(:delete, "/shares/#{shareid}")
    (@meta = get_meta(response)) && self
  end

  # Update permissions for a resource
  #
  # @param shareid [Integer] Share identifier
  # @param permissions [Integer] Must be one of the following: 1: read, 2: update, 4: create, 8: delete, 16: share,
  #   31: all rights.
  # @return [Object] Instance with meta response
  def update_permissions(shareid, permissions)
    update(shareid, "permissions", permissions)
  end

  # Update a password for a resource
  #
  # @param shareid [Integer] Share identifier
  # @param password [String] Password string
  # @return [Object] Instance with meta response
  def update_password(shareid, password)
    update(shareid, "password", password)
  end

  # Allow or disallow public uploads in a directory
  #
  # @param shareid [Integer] Share identifier
  # @param publicUpload [Boolean] True to permit public uploads in a directory, false to disallow
  # @return [Object] Instance with meta response
  def update_public_upload(shareid, publicUpload)
    update(shareid, "publicUpload", publicUpload)
  end

  # Update resource expiration date
  #
  # @param shareid [Integer] Share identifier
  # @param expireDate [String] Expiration date of a resource. Has to be in format of "YYYY-DD-MM"
  # @return [Object] Instance with meta response
  def update_expire_date(shareid, expireDate)
    update(shareid, "expireDate", expireDate)
  end

  # Wrapper to Federated Cloud Sharing API
  #
  # @!attribute [rw] meta
  #   @return [Hash] Information about API response
  class FederatedCloudShares
    include Helpers

    attr_accessor :meta

    # Creates Federated Cloud Sharing class instance
    #
    # @param api [Object] Api object
    def initialize(api)
      @api = api
    end

    # List accepted Federated Cloud Shares
    #
    # @return [Array] List of accepted Federated Cloud Shares
    def accepted
      response = @api.request(:get, "/remote_shares")
      h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
      h = [h] if h.class == Hash
      add_meta(response, h)
    end

    # List pending requests of Federated Cloud Shares
    #
    # @return [Array] List of pending Federated Cloud Shares
    def pending
      response = @api.request(:get, "/remote_shares/pending")
      h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
      h = [h] if h.class == Hash
      add_meta(response, h)
    end

    # Accept a request of a Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Object] Instance with meta response
    def accept(shareid)
      response = @api.request(:post, "/remote_shares/pending/#{shareid}")
      (@meta = get_meta(response)) && self
    end

    # Decline a request of a Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Object] Instance with meta response
    def decline(shareid)
      response = @api.request(:delete, "/remote_shares/pending/#{shareid}")
      (@meta = get_meta(response)) && self
    end

    # Delete an accepted Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Object] Instance with meta response
    def destroy(shareid)
      response = @api.request(:delete, "/remote_shares/#{shareid}")
      (@meta = get_meta(response)) && self
    end

    # Information about accepted Federated Cloud Share
    #
    # @param shareid [Integer] Federated Cloud Share identifier
    # @return [Hash] Information about Federated Cloud Share with meta response
    def find(shareid)
      response = @api.request(:get, "/remote_shares/#{shareid}")
      h = doc_to_hash(response, "//data").try(:[], "data")
      add_meta(response, h)
    end
  end

  # Initiates a Federated Cloud Sharing class
  def federated
    FederatedCloudShares.new(self)
  end

  private

  # Update a resource
  #
  # @param shareid [Integer] Share identifier
  # @param key [String] Option to update
  # @param value [String] Setting to update to
  # @return [Object] Instance with meta information
  def update(shareid, key, value)
    response = request(:put, "/shares/#{shareid}", "#{key}": value)
    (@meta = get_meta(response)) && self
  end
end

Instance Method Details

#all ⇒ Array

Get all shares

Returns:

  • (Array) —

    All shares of authenticated user



41
42
43
44
45
46
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 41

def all
  response = request(:get, "shares")
  h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
  h = [h] if h.class == Hash
  add_meta(response, h)
end

#create(path, shareType, shareWith = nil, publicUpload = nil, password = nil, permissions = nil) ⇒ Object

Share an item

16 share, 31 all rights. Value should be one of previously listed.

Parameters:

  • path (String) —

    Path of a file or directory to share

  • shareType (Integer) —

    One of four possible values. 0 means an user, 1 means a group, 3 means a public link 6 stands for federated cloud share

  • shareWith (String, nil) (defaults to: nil) —

    User or group identifier, can be omitted if shareType is neither 0, nor 1

  • publicUpload (Boolean, nil) (defaults to: nil) —

    If true, permits public uploads in directories shared by link

  • password (String, nil) (defaults to: nil) —

    Password-protects a share

  • permissions (Integer, nil) (defaults to: nil) —

    Sets permissions on a resource. 1 gives read rights, 2 update, 4 create, 8 delete

Returns:

  • (Object) —

    Instance including meta response



76
77
78
79
80
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 76

def create(path, shareType, shareWith=nil, publicUpload=nil, password=nil, permissions=nil)
  args = local_variables.reduce({}) { |c, i| c[i] = binding.local_variable_get(i); c }
  response = request(:post, "/shares", args)
  (@meta = get_meta(response)) && self
end

#destroy(shareid) ⇒ Object

Unshare an item

Parameters:

  • shareid (Integer) —

    Share ID

Returns:

  • (Object) —

    Instance with meta response



86
87
88
89
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 86

def destroy(shareid)
  response = request(:delete, "/shares/#{shareid}")
  (@meta = get_meta(response)) && self
end

#federated ⇒ Object

Initiates a Federated Cloud Sharing class



203
204
205
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 203

def federated
  FederatedCloudShares.new(self)
end

#find(shareid) ⇒ Hash

Get information about specific share

Parameters:

  • shareid (Integer)

Returns:

  • (Hash) —

    Information about share with meta



32
33
34
35
36
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 32

def find(shareid)
  response = request(:get, "shares/#{shareid}")
  h = doc_to_hash(response, "//data/element").try(:[], "element")
  add_meta(response, h)
end

#specific(path, reshares = nil, subfiles = nil) ⇒ Array

Get shares for a file or directory optionally get shares including re-shares on a resource or get shares for all the files in a directory

Parameters:

  • path (String)
  • reshares (Boolean, nil) (defaults to: nil)
  • subfiles (Boolean, nil) (defaults to: nil)

Returns:

  • (Array) —

    Shares (may include re-shares for a file or directory) of a resource or all reshares of directory contents



57
58
59
60
61
62
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 57

def specific(path, reshares = nil, subfiles = nil)
  response = request(:get, "shares?path=#{path}&reshares=#{reshares}&subfiles=#{subfiles}")
  h = doc_to_hash(response, "//data").try(:[], "data").try(:[], "element")
  h = [h] if h.class == Hash
  add_meta(response, h)
end

#update_expire_date(shareid, expireDate) ⇒ Object

Update resource expiration date

Parameters:

  • shareid (Integer) —

    Share identifier

  • expireDate (String) —

    Expiration date of a resource. Has to be in format of “YYYY-DD-MM”

Returns:

  • (Object) —

    Instance with meta response



124
125
126
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 124

def update_expire_date(shareid, expireDate)
  update(shareid, "expireDate", expireDate)
end

#update_password(shareid, password) ⇒ Object

Update a password for a resource

Parameters:

  • shareid (Integer) —

    Share identifier

  • password (String) —

    Password string

Returns:

  • (Object) —

    Instance with meta response



106
107
108
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 106

def update_password(shareid, password)
  update(shareid, "password", password)
end

#update_permissions(shareid, permissions) ⇒ Object

Update permissions for a resource

Parameters:

  • shareid (Integer) —

    Share identifier

  • permissions (Integer) —

    Must be one of the following: 1: read, 2: update, 4: create, 8: delete, 16: share, 31: all rights.

Returns:

  • (Object) —

    Instance with meta response



97
98
99
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 97

def update_permissions(shareid, permissions)
  update(shareid, "permissions", permissions)
end

#update_public_upload(shareid, publicUpload) ⇒ Object

Allow or disallow public uploads in a directory

Parameters:

  • shareid (Integer) —

    Share identifier

  • publicUpload (Boolean) —

    True to permit public uploads in a directory, false to disallow

Returns:

  • (Object) —

    Instance with meta response



115
116
117
 
# File 'lib/nextcloud/ocs/file_sharing_api.rb', line 115

def update_public_upload(shareid, publicUpload)
  update(shareid, "publicUpload", publicUpload)
end