package cs3.sharing.collaboration.v1beta1

Get desktop application:
View/edit binary Protocol Buffers messages

User Share Provider API The User Share Provider API is meant to manipulate share resources for a specific share type (user or group) from the perspective of the creator of the share and from the perspective of the recipient, both known to the local system. See OCM for remote shares. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The following are global requirements that apply to all methods: Any method MUST return CODE_OK on a succesful operation. Any method MAY return NOT_IMPLEMENTED. Any method MAY return INTERNAL. Any method MAY return UNKNOWN. Any method MAY return UNAUTHENTICATED.

• rpc CreateShare (CreateShareRequest, CreateShareResponse)

  collaboration_api.proto:63

  Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_LOCKED if the resource reference already locked. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING.

• rpc GetReceivedShare (GetReceivedShareRequest, GetReceivedShareResponse)

  collaboration_api.proto:84

  Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist.

• rpc GetShare (GetShareRequest, GetShareResponse)

  collaboration_api.proto:69

  Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

• rpc ListReceivedShares (ListReceivedSharesRequest, ListReceivedSharesResponse)

  collaboration_api.proto:78

  List all shares the authenticated principal has received.

• rpc ListShares (ListSharesRequest, ListSharesResponse)

  collaboration_api.proto:73

  List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

• rpc RemoveShare (RemoveShareRequest, RemoveShareResponse)

  collaboration_api.proto:66

  Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

• rpc UpdateReceivedShare (UpdateReceivedShareRequest, UpdateReceivedShareResponse)

  collaboration_api.proto:81

  Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist.

• rpc UpdateShare (UpdateShareRequest, UpdateShareResponse)

  collaboration_api.proto:76

  Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

Used as request type in: gateway.v1beta1.GatewayAPI.CreateShare, CollaborationAPI.CreateShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional storage.provider.v1beta1.ResourceInfo resource_info = 2

  REQUIRED. The information of the resource to be shared.

• optional ShareGrant grant = 3

  REQUIRED. The share grant for the share.

Used as response type in: gateway.v1beta1.GatewayAPI.CreateShare, CollaborationAPI.CreateShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional Share share = 3

  REQUIRED. The created share.

Represents a filter to apply to the request.

Used in: ListReceivedSharesRequest, ListSharesRequest

• Filter.Type type = 2

  REQUIRED.

• oneof term

  • storage.provider.v1beta1.ResourceId resource_id = 3

  • identity.user.v1beta1.UserId owner = 4

  • identity.user.v1beta1.UserId creator = 5

  • storage.provider.v1beta1.GranteeType grantee_type = 6

  • string space_id = 7

  • ShareState state = 8

  • storage.provider.v1beta1.Grantee grantee = 9

  • bool space_root = 10

    Used with TYPE_SPACE_ROOT.

The filter to apply.

Used in: Filter

• TYPE_INVALID = 0

• TYPE_NO = 1

• TYPE_RESOURCE_ID = 2

• TYPE_OWNER = 3

• TYPE_CREATOR = 4

• TYPE_GRANTEE_TYPE = 5

• TYPE_EXCLUDE_DENIALS = 6

• TYPE_SPACE_ID = 7

• TYPE_STATE = 8

• TYPE_GRANTEE = 9

• TYPE_SPACE_ROOT = 10

  Filter shares by whether the shared resource is a space root. When the term `space_root` is true, only shares on space roots are returned. When false, shares on space roots are excluded.

Used as request type in: gateway.v1beta1.GatewayAPI.GetReceivedShare, CollaborationAPI.GetReceivedShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional ShareReference ref = 2

  REQUIRED. The reference of the received share.

Used as response type in: gateway.v1beta1.GatewayAPI.GetReceivedShare, CollaborationAPI.GetReceivedShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional ReceivedShare share = 3

  REQUIRED. The share.

Used as request type in: gateway.v1beta1.GatewayAPI.GetShare, CollaborationAPI.GetShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional ShareReference ref = 2

  REQUIRED. The reference to which the action should be performed.

Used as response type in: gateway.v1beta1.GatewayAPI.GetShare, CollaborationAPI.GetShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional Share share = 3

  REQUIRED. The share.

Used as request type in: gateway.v1beta1.GatewayAPI.ListExistingReceivedShares, gateway.v1beta1.GatewayAPI.ListReceivedShares, CollaborationAPI.ListReceivedShares

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• repeated Filter filters = 3

  OPTIONAL. The list of filters to apply if any.

• int32 page_size = 4

  OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

• string page_token = 5

  OPTIONAL. The client uses this field to request a specific page of the list results.

Used as response type in: gateway.v1beta1.GatewayAPI.ListReceivedShares, CollaborationAPI.ListReceivedShares

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• repeated ReceivedShare shares = 3

  REQUIRED. The list of received shares.

• string next_page_token = 4

  OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

Used as request type in: gateway.v1beta1.GatewayAPI.ListExistingShares, gateway.v1beta1.GatewayAPI.ListShares, CollaborationAPI.ListShares

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• repeated Filter filters = 2

  OPTIONAL. The list of filters to apply if any.

• int32 page_size = 3

  OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

• string page_token = 4

  OPTIONAL. The client uses this field to request a specific page of the list results.

Used as response type in: gateway.v1beta1.GatewayAPI.ListShares, CollaborationAPI.ListShares

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• repeated Share shares = 3

  REQUIRED. The list of shares.

• string next_page_token = 4

  OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

A received share is the share that a grantee will receive. It expands the original share by adding state to the share, a display name from the perspective of the grantee and a resource mount point in case the share will be mounted in a storage provider.

Used in: gateway.v1beta1.ReceivedShareResourceInfo, GetReceivedShareResponse, ListReceivedSharesResponse, UpdateReceivedShareRequest, UpdateReceivedShareResponse

• optional Share share = 1

  REQUIRED.

• ShareState state = 2

  REQUIRED. The state of the share.

• optional storage.provider.v1beta1.Reference mount_point = 3

  REQUIRED. The mount point of the share.

• bool hidden = 4

  OPTIONAL. Flag to hide the share, defaults to false.

• string alias = 5

  OPTIONAL. An alternate identifier to allow a recipient to rename the share. If missing, use the original folder name.

Used as request type in: gateway.v1beta1.GatewayAPI.RemoveShare, CollaborationAPI.RemoveShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional ShareReference ref = 2

  REQUIRED. The reference to which the action should be performed.

Used as response type in: gateway.v1beta1.GatewayAPI.RemoveShare, CollaborationAPI.RemoveShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

Shares are relationships between a resource owner (usually the authenticated user) who grants permissions to a recipient (grantee) on a specified resource (resource_id). UserShares represents both user and groups.

Used in: gateway.v1beta1.ShareResourceInfo, CreateShareResponse, GetShareResponse, ListSharesResponse, ReceivedShare, UpdateShareRequest, UpdateShareResponse

• optional ShareId id = 1

  REQUIRED. Opaque unique identifier of the share.

• optional storage.provider.v1beta1.ResourceId resource_id = 2

  REQUIRED. Unique identifier of the shared resource.

• optional SharePermissions permissions = 3

  REQUIRED. Permissions for the grantee to use the resource.

• optional storage.provider.v1beta1.Grantee grantee = 4

  REQUIRED. The receiver of the share, like a user, group ...

• optional identity.user.v1beta1.UserId owner = 5

  REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership.

• optional identity.user.v1beta1.UserId creator = 6

  REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal.

• optional types.v1beta1.Timestamp ctime = 7

  REQUIRED. Creation time of the share.

• optional types.v1beta1.Timestamp mtime = 8

  REQUIRED. Last modification time of the share.

• optional types.v1beta1.Timestamp expiration = 9

  OPTIONAL. The expiration time of the share.

• string description = 10

  OPTIONAL. A user-defined description for the share.

A share grant specifies the share permissions for a grantee.

Used in: CreateShareRequest

• optional storage.provider.v1beta1.Grantee grantee = 1

  REQUIRED. The grantee of the grant.

• optional SharePermissions permissions = 2

  REQUIRED. The share permissions for the grant.

• optional types.v1beta1.Timestamp expiration = 3

  OPTIONAL Expiration of the grant.

A share id identifies uniquely a // share in the share provider namespace. A ShareId MUST be unique inside the share provider.

Used in: Share, ShareReference

• string opaque_id = 2

  REQUIRED. The internal id used by service implementor to uniquely Collaboration the share in the internal implementation of the service.

Uniquely identifies a share in the share provider. A share MUST be uniquely identify by four (4) elements: 1) The share provider id 2) The owner of the share 3) The resource id 4) The grantee for the share This 4-tuple MUST be unique. For example, owner Alice shares the resource /home/docs with id home:1234 to an user named Bob. The 4-tuple will consist of 1) The share provider id = "user" 2) The owner of the share = "Alice" 3) The resource id = "home:1234" 4) The grantee for the share = Grantee("type" = "user", "" => "Bob")

Used in: ShareReference

• optional identity.user.v1beta1.UserId owner = 2

  REQUIRED.

• optional storage.provider.v1beta1.ResourceId resource_id = 3

  REQUIRED.

• optional storage.provider.v1beta1.Grantee grantee = 4

  REQUIRED.

The permissions for a share.

Used in: Share, ShareGrant, UpdateShareRequest.UpdateField

• optional storage.provider.v1beta1.ResourcePermissions permissions = 1

  TODO(labkode): additional permissions for shares like re-sharing and denying

The mechanism to identify a share in the share provider namespace.

Used in: GetReceivedShareRequest, GetShareRequest, RemoveShareRequest, UpdateShareRequest

• oneof spec

  REQUIRED. One of the specifications MUST be specified.

  • ShareId id = 1

    The id of the share.

  • ShareKey key = 2

    The combination of fields that make the share unique.

The state of the share.

Used in: Filter, ReceivedShare

• SHARE_STATE_INVALID = 0

  The share is no longer valid, for example, the share expired.

• SHARE_STATE_PENDING = 1

  New shares MUST be created in the SHARE_STATE_PENDING state. This state means the share is pending to be accepted or rejected by the recipient of the share.

• SHARE_STATE_ACCEPTED = 2

  The recipient of the share has accepted the share.

• SHARE_STATE_REJECTED = 3

  The recipient of the share has rejected the share. Does not mean the share is removed, the recipient MAY change the state to accepted or pending.

TODO(labkode): clean up display_name ? we'll use storage links for that.

Used as request type in: gateway.v1beta1.GatewayAPI.UpdateReceivedShare, CollaborationAPI.UpdateReceivedShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional ReceivedShare share = 2

  REQUIRED. The received share to update.

• optional google.protobuf.FieldMask update_mask = 3

  The update mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

Used as response type in: gateway.v1beta1.GatewayAPI.UpdateReceivedShare, CollaborationAPI.UpdateReceivedShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional ReceivedShare share = 3

  REQUIRED. The updated share.

Used as request type in: gateway.v1beta1.GatewayAPI.UpdateShare, CollaborationAPI.UpdateShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional ShareReference ref = 2

  REQUIRED. Deprecated use the share and update_mask attribute.

• optional UpdateShareRequest.UpdateField field = 3

  REQUIRED. Deprecated use the share and update_mask attribute.

• optional google.protobuf.FieldMask update_mask = 4

  The update mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

• optional Share share = 5

  REQUIRED. The share containing the new data

REQUIRED.

Used in: UpdateShareRequest

• oneof field

  One of the update fields MUST be specified.

  • SharePermissions permissions = 2

    Update the permissions.

  • string display_name = 3

    Update the display name.

  • types.v1beta1.Timestamp expiration = 4

    Update the expiration time.

Used as response type in: gateway.v1beta1.GatewayAPI.UpdateShare, CollaborationAPI.UpdateShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional Share share = 3

  REQUIRED. The updated share.