Added comments to detail the mapping of OCM properties

cs3org · Mar 29, 2023 · d50fdbe · d50fdbe
1 parent 46e5545
commit d50fdbe
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 10 deletions.
diff --git 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
@@ -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
@@ -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
@@ -8854,7 +8854,9 @@ <h3 id="cs3.ocm.core.v1beta1.CreateOCMCoreShareRequest">CreateOCMCoreShareReques
                   <td><a href="#cs3.sharing.ocm.v1beta1.Protocol">cs3.sharing.ocm.v1beta1.Protocol</a></td>
                   <td>repeated</td>
                   <td><p>REQUIRED.
-The protocols which are used to establish synchronisation. </p></td>
+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. </p></td>
                 </tr>
 
             </tbody>
@@ -13417,7 +13419,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.ListOCMSharesRequest.Filter.Type">ListOCMSharesR
 
 
         <h3 id="cs3.sharing.ocm.v1beta1.OcmAPI">OcmAPI</h3>
-        <p>OCM Share Provider API</p><p>The OCM Share Provider API is meant to manipulate share</p><p>resources from the perspective of the creator or the share and</p><p>from the perspective of the receiver of the share.</p><p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL</p><p>NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and</p><p>"OPTIONAL" in this document are to be interpreted as described in</p><p>RFC 2119.</p><p>The following are global requirements that apply to all methods:</p><p>Any method MUST return CODE_OK on a succesful operation.</p><p>Any method MAY return NOT_IMPLEMENTED.</p><p>Any method MAY return INTERNAL.</p><p>Any method MAY return UNKNOWN.</p><p>Any method MAY return UNAUTHENTICATED.</p>
+        <p>OCM Share Provider API</p><p>The OCM Share Provider API is meant to manipulate share</p><p>resources from the perspective of the creator or the share and</p><p>from the perspective of the receiver of the share.</p><p>The following APIs match the OCM v1.1 spec, including the invitation</p><p>workflow and multi-protocol shares.</p><p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL</p><p>NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and</p><p>"OPTIONAL" in this document are to be interpreted as described in</p><p>RFC 2119.</p><p>The following are global requirements that apply to all methods:</p><p>Any method MUST return CODE_OK on a succesful operation.</p><p>Any method MAY return NOT_IMPLEMENTED.</p><p>Any method MAY return INTERNAL.</p><p>Any method MAY return UNKNOWN.</p><p>Any method MAY return UNAUTHENTICATED.</p>
         <table class="enum-table">
           <thead>
             <tr><td>Method Name</td><td>Request Type</td><td>Response Type</td><td>Description</td></tr>
@@ -13703,7 +13705,14 @@ <h3 id="cs3.sharing.ocm.v1beta1.ReceivedShare">ReceivedShare</h3>
                   <td>protocols</td>
                   <td><a href="#cs3.sharing.ocm.v1beta1.Protocol">Protocol</a></td>
                   <td>repeated</td>
-                  <td><p>REQUIRED. </p></td>
+                  <td><p>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. </p></td>
                 </tr>
 
                 <tr>
@@ -13829,7 +13838,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.Share">Share</h3>
                   <td><a href="#cs3.types.v1beta1.Timestamp">cs3.types.v1beta1.Timestamp</a></td>
                   <td></td>
                   <td><p>OPTIONAL.
-The expiration time for the ocm share. </p></td>
+The expiration time for the OCM share. </p></td>
                 </tr>
 
                 <tr>
@@ -13895,7 +13904,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.ShareGrant">ShareGrant</h3>
 
 
         <h3 id="cs3.sharing.ocm.v1beta1.ShareId">ShareId</h3>
-        <p>A share id identifies uniquely a // share in the share provider namespace.</p><p>A ShareId MUST be unique inside the share provider.</p>
+        <p>A share id identifies uniquely a share in the share provider namespace.</p><p>A ShareId MUST be unique inside the share provider.</p>
 
 
           <table class="field-table">
@@ -13910,8 +13919,9 @@ <h3 id="cs3.sharing.ocm.v1beta1.ShareId">ShareId</h3>
                   <td></td>
                   <td><p>REQUIRED.
 The internal id used by service implementor to
-uniquely identity the share in the internal
-implementation of the service. </p></td>
+uniquely identify the share in the internal
+implementation of the service.
+In the OCM specifications, this corresponds to the `providerId`. </p></td>
                 </tr>
 
             </tbody>