From 72e0437cde34ce2cc7abf06a5b2730fd2eafa3f1 Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Wed, 29 Mar 2023 17:10:05 +0200 Subject: [PATCH] Added comments to detail the mapping of OCM properties (#206) --- cs3/ocm/core/v1beta1/ocm_core_api.proto | 2 ++ cs3/sharing/ocm/v1beta1/ocm_api.proto | 3 +++ cs3/sharing/ocm/v1beta1/resources.proto | 14 +++++++++++--- docs/index.html | 24 +++++++++++++++++------- 4 files changed, 33 insertions(+), 10 deletions(-) diff --git a/cs3/ocm/core/v1beta1/ocm_core_api.proto b/cs3/ocm/core/v1beta1/ocm_core_api.proto index 2f04a40..258fbfd 100644 --- a/cs3/ocm/core/v1beta1/ocm_core_api.proto +++ b/cs3/ocm/core/v1beta1/ocm_core_api.proto @@ -91,6 +91,8 @@ message CreateOCMCoreShareRequest { cs3.types.v1beta1.Timestamp expiration = 10; // REQUIRED. // The protocols which are used to establish synchronisation. + // See also cs3/sharing/ocm/v1beta1/resources.proto for how to map + // this to the OCM share payload. repeated cs3.sharing.ocm.v1beta1.Protocol protocols = 11; } diff --git a/cs3/sharing/ocm/v1beta1/ocm_api.proto b/cs3/sharing/ocm/v1beta1/ocm_api.proto index 04c82d7..0132740 100644 --- a/cs3/sharing/ocm/v1beta1/ocm_api.proto +++ b/cs3/sharing/ocm/v1beta1/ocm_api.proto @@ -42,6 +42,9 @@ import "google/protobuf/field_mask.proto"; // resources from the perspective of the creator or the share and // from the perspective of the receiver of the share. // +// The following APIs match the OCM v1.1 spec, including the invitation +// workflow and 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 diff --git a/cs3/sharing/ocm/v1beta1/resources.proto b/cs3/sharing/ocm/v1beta1/resources.proto index 4a77650..780bc04 100644 --- a/cs3/sharing/ocm/v1beta1/resources.proto +++ b/cs3/sharing/ocm/v1beta1/resources.proto @@ -72,7 +72,7 @@ message Share { // Last modification time of the share. cs3.types.v1beta1.Timestamp mtime = 9; // OPTIONAL. - // The expiration time for the ocm share. + // The expiration time for the OCM share. cs3.types.v1beta1.Timestamp expiration = 10; // REQUIRED. // Recipient share type. @@ -127,6 +127,13 @@ message ReceivedShare { // Recipient share type. cs3.sharing.ocm.v1beta1.ShareType share_type = 10; // 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. repeated Protocol protocols = 11; // REQUIRED. // The state of the share. @@ -176,13 +183,14 @@ message ShareKey { storage.provider.v1beta1.Grantee grantee = 3; } -// A share id identifies uniquely a // share in the share provider namespace. +// A share id identifies uniquely a share in the share provider namespace. // A ShareId MUST be unique inside the share provider. message ShareId { // REQUIRED. // The internal id used by service implementor to - // uniquely identity the share in the internal + // uniquely identify the share in the internal // implementation of the service. + // In the OCM specifications, this corresponds to the `providerId`. string opaque_id = 1; } diff --git a/docs/index.html b/docs/index.html index bd7a024..9d1f268 100644 --- a/docs/index.html +++ b/docs/index.html @@ -8854,7 +8854,9 @@

CreateOCMCoreShareReques cs3.sharing.ocm.v1beta1.Protocol repeated

REQUIRED. -The protocols which are used to establish synchronisation.

+The protocols which are used to establish synchronisation. +See also cs3/sharing/ocm/v1beta1/resources.proto for how to map +this to the OCM share payload.

@@ -13417,7 +13419,7 @@

ListOCMSharesR

OcmAPI

-

OCM Share Provider API

The OCM Share Provider API is meant to manipulate share

resources from the perspective of the creator or the share and

from the perspective of the receiver of the share.

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.

+

OCM Share Provider API

The OCM Share Provider API is meant to manipulate share

resources from the perspective of the creator or the share and

from the perspective of the receiver of the share.

The following APIs match the OCM v1.1 spec, including the invitation

workflow and 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.

@@ -13703,7 +13705,14 @@

ReceivedShare

- + @@ -13829,7 +13838,7 @@

Share

+The expiration time for the OCM share.

@@ -13895,7 +13904,7 @@

ShareGrant

ShareId

-

A share id identifies uniquely a // share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

+

A share id identifies uniquely a share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

Method NameRequest TypeResponse TypeDescription
protocols Protocol repeated

REQUIRED.

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.

cs3.types.v1beta1.Timestamp

OPTIONAL. -The expiration time for the ocm share.

@@ -13910,8 +13919,9 @@

ShareId

+uniquely identify the share in the internal +implementation of the service. +In the OCM specifications, this corresponds to the `providerId`.

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