Create a MediaService to handle UrlPreview request - WIP

.idea/dictionaries/bmarty.xml

@@ -24,6 +24,7 @@
       <w>pbkdf</w>
       <w>pids</w>
       <w>pkcs</w>
+      <w>previewable</w>
       <w>riotx</w>
       <w>signin</w>
       <w>signout</w>

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/media/MediaService.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2020 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.matrix.android.sdk.api.session.media
+
+import org.matrix.android.sdk.api.cache.CacheStrategy
+import org.matrix.android.sdk.api.session.events.model.Event
+import org.matrix.android.sdk.api.util.JsonDict
+
+interface MediaService {
+    /**
+     * Extract URLs from an Event.
+     * @return the list of URLs contains in the body of the Event. It does not mean that URLs in this list have UrlPreview data
+     */
+    fun extractUrls(event: Event): List<String>
+
+    /**
+     * Get Raw Url Preview data from the homeserver. There is no cache management for this request
+     */
+    suspend fun getRawPreviewUrl(url: String): JsonDict
+
+    /**
+     * Get Url Preview data from the homeserver, or from cache, depending on the cache strategy
+     * @param url
+     */
+    suspend fun getPreviewUrl(url: String, cacheStrategy: CacheStrategy): PreviewUrlData
+
+    /**
+     * Clear the cache of all retrieved UrlPreview data
+     */
+    suspend fun clearCache()
+}

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/media/PreviewUrlData.kt

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2020 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.matrix.android.sdk.api.session.media
+
+/**
+ * Facility data class to get the common field of a PreviewUrl response form the server
+ *
+ * Example of return data for the url `https://matrix.org`:
+ * <pre>
+ * {
+ *     "matrix:image:size": 112805,
+ *     "og:description": "Matrix is an open standard for interoperable, decentralised, real-time communication",
+ *     "og:image": "mxc://matrix.org/2020-12-03_uFqjagCCTJbaaJxb",
+ *     "og:image:alt": "Matrix is an open standard for interoperable, decentralised, real-time communication",
+ *     "og:image:height": 467,
+ *     "og:image:type": "image/jpeg",
+ *     "og:image:width": 911,
+ *     "og:locale": "en_US",
+ *     "og:site_name": "Matrix.org",
+ *     "og:title": "Matrix.org",
+ *     "og:type": "website",
+ *     "og:url": "https://matrix.org"
+ * }
+ * </pre>
+ */
+data class PreviewUrlData(
+        // Value of field "og:url". If not provided, this is the value passed in parameter
+        val url: String,
+        // Value of field "og:title"
+        val title: String?,
+        // Value of field "og:description"
+        val description: String?,
+        // Value of field "og:image"
+        val mxcUrl: String?
+)

matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/session/media/MediaAPI.kt

@@ -16,9 +16,11 @@
 
 package org.matrix.android.sdk.internal.session.media
 
+import org.matrix.android.sdk.api.util.JsonDict
 import org.matrix.android.sdk.internal.network.NetworkConstants
 import retrofit2.Call
 import retrofit2.http.GET
+import retrofit2.http.Query
 
 internal interface MediaAPI {
     /**
@@ -27,4 +29,15 @@ internal interface MediaAPI {
      */
     @GET(NetworkConstants.URI_API_MEDIA_PREFIX_PATH_R0 + "config")
     fun getMediaConfig(): Call<GetMediaConfigResult>
+
+    /**
+     * Get information about a URL for the client. Typically this is called when a client
+     * sees a URL in a message and wants to render a preview for the user.
+     * Ref: https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-media-r0-preview-url
+     * @param url Required. The URL to get a preview of.
+     * @param ts The preferred point in time to return a preview for. The server may return a newer version
+     * if it does not have the requested version available.
+     */
+    @GET(NetworkConstants.URI_API_MEDIA_PREFIX_PATH_R0 + "preview_url")
+    fun getPreviewUrlData(@Query("url") url: String, @Query("ts") ts: Int?): Call<JsonDict>
 }