package cs3.sharing.ocm.v1beta1
Get desktop application:
View/edit binary Protocol Buffers messages
service OcmAPI
ocm_api.proto:60OCM API The OCM API is a share API meant for local users to offer local resources to remote recipients via the Open Cloud Mesh (OCM) protocol, and to manipulate shares received from remote users. Implementations are expected to call remote `/ocm` endpoints in response to the payloads received via this API. The APIs match the OCM v1.2+ spec including multi-protocol 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.
message
resources.proto:369Defines how a remote OCM recipient accesses a local resource when serving a share. This is a subset of the OCM protocol specifications.
Used in: , ,
oneof term
REQUIRED. One of the access method MUST be specified.
webdav_options = 1
Options for the WebDAV access method.
webapp_options = 2
Options for the Webapp access method.
generic_options = 4
Options for a generic access method. Used to implement future access methods.
The available access types for an OCM resource.
Used in: ,
ACCESS_TYPE_INVALID = 0
ACCESS_TYPE_REMOTE = 1
The resource is to be accessed remotely or interactively.
ACCESS_TYPE_DATATX = 2
The resource is to be transferred to the recipient.
Used as request type in: gateway.v1beta1.GatewayAPI.CreateOCMShare, OcmAPI.CreateOCMShare
optional opaque = 1
OPTIONAL. Opaque information.
optional resource_id = 2
REQUIRED. The unique identifier for the shared storage resource.
optional grantee = 3
REQUIRED. The grantee for the share.
optional recipient_mesh_provider = 4
REQUIRED. The details of the recipient user's mesh provider.
repeated access_methods = 5
REQUIRED. The protocols used to access the resource from remote.
optional expiration = 6
OPTIONAL. The expiration time for the ocm share.
Used as response type in: gateway.v1beta1.GatewayAPI.CreateOCMShare, OcmAPI.CreateOCMShare
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
optional share = 3
REQUIRED. The created share.
string recipient_display_name = 4
OPTIONAL. Display name of the recipient of the share.
message
resources.proto:317Defines the options for the Embedded protocol.
Used in:
string payload = 1
REQUIRED. The embedded payload.
Used as request type in: gateway.v1beta1.GatewayAPI.GetOCMShareByToken, OcmAPI.GetOCMShareByToken
string token = 1
REQUIRED. The unlisted token to identify the public share.
Used as response type in: gateway.v1beta1.GatewayAPI.GetOCMShareByToken, OcmAPI.GetOCMShareByToken
optional status = 1
REQUIRED. The response status.
optional share = 2
REQUIRED. The share.
Used as request type in: gateway.v1beta1.GatewayAPI.GetOCMShare, OcmAPI.GetOCMShare
optional opaque = 1
OPTIONAL. Opaque information.
optional ref = 2
REQUIRED. The reference to which the action should be performed.
Used as response type in: gateway.v1beta1.GatewayAPI.GetOCMShare, OcmAPI.GetOCMShare
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
optional share = 3
REQUIRED. The share.
Used as request type in: gateway.v1beta1.GatewayAPI.GetReceivedOCMShare, OcmAPI.GetReceivedOCMShare
optional opaque = 1
OPTIONAL. Opaque information.
optional ref = 2
REQUIRED. The reference of the received share.
Used as response type in: gateway.v1beta1.GatewayAPI.GetReceivedOCMShare, OcmAPI.GetReceivedOCMShare
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
optional share = 3
REQUIRED. The share.
Used as request type in: gateway.v1beta1.GatewayAPI.ListExistingOCMShares, gateway.v1beta1.GatewayAPI.ListOCMShares, OcmAPI.ListOCMShares
optional opaque = 1
OPTIONAL. Opaque information.
repeated 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.
REQUIRED. represents a filter to apply to the request.
Used in:
Filter.Type type = 2
REQUIRED.
oneof term
resource_id = 3
owner = 4
creator = 5
REQUIRED. The filter to apply.
Used in:
TYPE_INVALID = 0
TYPE_NO = 1
TYPE_RESOURCE_ID = 2
TYPE_OWNER = 3
TYPE_CREATOR = 4
TYPE_OWNER_PROVIDER = 5
TYPE_CREATOR_PROVIDER = 6
Used as response type in: gateway.v1beta1.GatewayAPI.ListOCMShares, OcmAPI.ListOCMShares
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
repeated 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
Used as request type in: gateway.v1beta1.GatewayAPI.ListReceivedOCMShares, OcmAPI.ListReceivedOCMShares
optional opaque = 1
OPTIONAL. Opaque information.
int32 page_size = 2
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 = 3
OPTIONAL. The client uses this field to request a specific page of the list results.
repeated filters = 4
OPTIONAL. The list of filters to apply if any.
Used in:
Filter.Type type = 1
REQUIRED.
oneof term
owner = 2
creator = 3
SharedResourceType shared_resource_type = 4
REQUIRED. The filter to apply.
Used in:
TYPE_INVALID = 0
TYPE_OWNER = 1
TYPE_CREATOR = 2
TYPE_SHARE_TYPE = 3
Used as response type in: gateway.v1beta1.GatewayAPI.ListReceivedOCMShares, OcmAPI.ListReceivedOCMShares
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
repeated 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
message
resources.proto:246The protocol which is used to get access to a remote OCM resource.
Used in: , , , ,
oneof term
REQUIRED. One of the protocols MUST be specified.
webdav_options = 1
Options for WebDAV protocol.
webapp_options = 2
Options for Webapp protocol.
generic_options = 4
Options for a generic protocol. Used to implement future protocols in the OCM specs.
embedded_options = 5
Options for embedded protocol.
A received share represents a share offered by a remote user to a local grantee.
Used in: , ,
optional id = 1
REQUIRED. Opaque unique identifier of the share.
string name = 2
REQUIRED. Name of the shared resource.
string remote_share_id = 3
REQUIRED. Identifier to identify the shared resource at the provider side. This is unique per provider such that if the same resource is shared twice, this will not be repeated. This correspond to the `providerId` in the OCM API specs.
optional grantee = 4
REQUIRED. The receiver of the share, like a user, group ...
optional 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 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 ctime = 7
REQUIRED. Creation time of the share.
optional mtime = 8
REQUIRED. Last modification time of the share.
optional expiration = 9
OPTIONAL. The expiration time for the ocm share.
ShareType share_type = 10
REQUIRED. Recipient share type. Deprecated: use recipient_type instead.
repeated protocols = 11
REQUIRED. List of protocols offered for this share. In the OCM specifications, this corresponds to the `protocol` property, to maintain backwards compatibility with OCM v1 where only a single protocol was implemented. Furthermore, `protocol.name` MAY be set to `multi` and `protocol.options` MAY be left empty in the OCM share payload, in order to use the `protocol.webdav` and similar properties.
ShareState state = 12
REQUIRED. The state of the share.
optional opaque = 13
OPTIONAL.
storage.provider.v1beta1.ResourceType resource_type = 14
REQUIRED. Resource type. Deprecated: a resource might not always be a storage resource, use shared_resource_type instead.
string code = 15
OPTIONAL. A nonce to be exchanged for a (potentially short-lived) bearer token. Deprecated in OCM 1.3.
RecipientType recipient_type = 16
REQUIRED. Recipient type, e.g. user or group.
SharedResourceType shared_resource_type = 17
REQUIRED. Shared resource type.
string destination = 18
OPTIONAL. Destination path of the share, in case the shared resource type is EMBEDDED or the access type is DATATX.
bool hidden = 19
OPTIONAL. Flag to hide the share, defaults to false.
Defines the types of recipient for an OCM share.
Used in: , , ,
RECIPIENT_TYPE_INVALID = 0
RECIPIENT_TYPE_USER = 1
Share of type user.
RECIPIENT_TYPE_GROUP = 2
Share of type group.
Used as request type in: gateway.v1beta1.GatewayAPI.RemoveOCMShare, OcmAPI.RemoveOCMShare
optional opaque = 1
OPTIONAL. Opaque information.
optional ref = 2
REQUIRED. The reference to which the action should be performed.
Used as response type in: gateway.v1beta1.GatewayAPI.RemoveOCMShare, OcmAPI.RemoveOCMShare
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
OCM Shares are shares created by a local owner (usually the authenticated user), who grants permissions to a remote recipient (grantee) on a specified (local) resource (resource_id). UserShares represents both user and groups.
Used in: , , , ,
optional id = 1
REQUIRED. Opaque unique identifier of the share.
optional resource_id = 2
REQUIRED. Unique identifier of the shared resource.
string name = 3
REQUIRED. Name of the shared resource.
string token = 4
REQUIRED. The unlisted token to give access to the ocm share.
optional grantee = 5
REQUIRED. The receiver of the share, like a user, group ...
optional owner = 6
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 creator = 7
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 ctime = 8
REQUIRED. Creation time of the share.
optional mtime = 9
REQUIRED. Last modification time of the share.
optional expiration = 10
OPTIONAL. The expiration time for the OCM share.
ShareType share_type = 11
REQUIRED. Recipient share type. Deprecated: use recipient_type instead.
repeated access_methods = 12
REQUIRED. Access methods represent how remote users would access the local resource.
string code = 13
OPTIONAL. A nonce to be exchanged for a (potentially short-lived) bearer token. Deprecated in OCM 1.3.
optional opaque = 14
OPTIONAL.
RecipientType recipient_type = 15
REQUIRED. Recipient type, e.g. user or group.
A share id identifies uniquely a share in the share provider namespace. A ShareId MUST be unique inside the share provider.
Used in: , , , , ,
string opaque_id = 1
REQUIRED. The internal id used by service implementor to uniquely identify the share in the internal implementation of the service. In the OCM specifications, this corresponds to the `providerId`.
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:
optional owner = 1
REQUIRED.
optional resource_id = 2
REQUIRED.
optional grantee = 3
REQUIRED.
The permissions for an OCM share. Deprecated: reshare is redundant with grant permissions.
Used in:
optional permissions = 1
bool reshare = 2
The mechanism to identify a share in the share provider namespace.
Used in: , , ,
oneof spec
REQUIRED. One of the specifications MUST be specified.
id = 1
The id of the share.
key = 2
The combination of fields that make the share unique.
string token = 3
The token of the share.
The state of the share.
Used in:
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, processed or rejected by the recipient of the share.
SHARE_STATE_ACCEPTED = 2
The recipient of the share has accepted the share or processed 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.
SHARE_STATE_TRANSFERRING = 4
The recipient of the share is transferring a copy of the resource: this MAY apply to shares with DATATX access type or to embedded shares
Defines the type of share based on its recipient. Deprecated: use RecipientType instead.
Used in: , , , , ,
SHARE_TYPE_INVALID = 0
SHARE_TYPE_USER = 1
Share of type user.
SHARE_TYPE_GROUP = 2
Share of type group.
The available types of shared resources.
Used in: , ,
SHARE_RESOURCE_TYPE_INVALID = 0
SHARE_RESOURCE_TYPE_FILE = 1
The file type represents a type that holds arbitrary data.
SHARE_RESOURCE_TYPE_CONTAINER = 2
The container type represents a type that can contain other resources.
SHARE_RESOURCE_TYPE_EMBEDDED = 3
The embedded type represents resources that are embedded inside the received share payload, for which there's no remote access to be performed. See also the `embedded` protocol.
Used as request type in: gateway.v1beta1.GatewayAPI.UpdateOCMShare, OcmAPI.UpdateOCMShare
optional opaque = 1
OPTIONAL. Opaque information.
optional ref = 2
REQUIRED.
repeated field = 3
REQUIRED.
Used in:
oneof field
One of the update fields MUST be specified.
expiration = 1
Update the expiration.
access_methods = 2
Update access methods.
Used as response type in: gateway.v1beta1.GatewayAPI.UpdateOCMShare, OcmAPI.UpdateOCMShare
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
TODO(labkode): clean up display_name ? we'll use storage links for that.
Used as request type in: gateway.v1beta1.GatewayAPI.UpdateReceivedOCMShare, OcmAPI.UpdateReceivedOCMShare
optional opaque = 1
OPTIONAL. Opaque information.
optional share = 2
REQUIRED. The received share to update.
optional 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.UpdateReceivedOCMShare, OcmAPI.UpdateReceivedOCMShare
optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
message
resources.proto:385Defines the options for the WebDAV access method, representing how a remote user accesses a local resource via the `webdav` OCM protocol.
Used in:
optional permissions = 1
REQUIRED. The permissions for the share.
repeated string requirements = 2
OPTIONAL. The requirements for the share.
repeated AccessType access_types = 3
OPTIONAL. Access types for the share, e.g. remote or data transfer. Defaults to remote.
message
resources.proto:265Defines the options for the WebDAV protocol, mapping to the `webdav` protocol in the OCM specifications.
Used in:
string shared_secret = 1
REQUIRED. Secret used to access the resource.
optional permissions = 2
Permissions of the shared resource. Deprecated: use share_permissions instead.
string uri = 3
REQUIRED. URI used to access the resource.
repeated string requirements = 4
OPTIONAL. The requirements for the share.
repeated AccessType access_types = 5
OPTIONAL. Access types for the share, e.g. remote or data transfer. Defaults to remote.
optional share_permissions = 6
REQUIRED. Permissions of the shared resource.
message
resources.proto:399Defines the options for the Webapp access method, representing how a remote user accesses a local app via the `webapp` OCM protocol.
Used in:
optional permissions = 1
REQUIRED. The permissions for the share.
repeated string requirements = 2
REQUIRED. The requirements for the share.
string app_name = 3
OPTIONAL. A descriptive name of the app in the remote user interface.
message
resources.proto:287Defines the options for the Webapp protocol, mapping to the `webapp` protocol in the OCM specifications.
Used in:
string shared_secret = 1
REQUIRED. Secret used to access the resource.
optional share_permissions = 2
REQUIRED. Permissions of the shared resource.
string uri = 3
REQUIRED. URI to open the resource with the remote app.
repeated string requirements = 4
REQUIRED. The requirements for the share.
repeated string targets = 5
REQUIRED. The targets that can be used to display the remote app.
string app_name = 6
OPTIONAL. A descriptive name of the remote app in the user interface.
string app_icon_hint = 7
OPTIONAL. A hint in the form of a media (MIME) type of the icon representing the remote app in the user interface.
repeated string media_types = 8
OPTIONAL. An array of media (MIME) types that the remote application can handle.