Package io.github.ma1uta.matrix.client.api

Interface ContentApi

@Path("/_matrix/media/r0")
public interface ContentApi

This module allows users to upload content to their homeserver which is retrievable from other homeservers. Its' purpose is to allow users to share attachments in a room. Key locations are represented as Matrix Key (MXC) URIs. They look like:

 mxc://(server-name)/(media-id)

 (server-name) : The name of the homeserver where this content originated, e.g. matrix.org
 (media-id) : An opaque ID which identifies the content.
 

Uploads are POSTed to a resource on the user's local homeserver which returns a token which is used to GET the download. Key is downloaded from the recipient's local homeserver, which must first transfer the content from the origin homeserver using the same API (unless the origin and destination homeservers are the same).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ContentApi.Method	The desired resizing method.

Method Summary

Modifier and Type	Method	Description
void	config(javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)	This endpoint allows clients to retrieve the configuration of the content repository, such as upload limitations.
void	download(String serverName, String mediaId, Boolean allowRemote, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	Download content from the content repository.
void	downloadFile(String serverName, String mediaId, String filename, Boolean allowRemote, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	Download content from the content repository as a given filename.
void	previewUrl(String url, String ts, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)	Get information about a PATH for a client.
void	thumbnail(String serverName, String mediaId, Long width, Long height, String method, Boolean allowRemote, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)	Download a thumbnail of the content from the content repository.
void	upload(InputStream inputStream, String filename, String contentType, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse, javax.ws.rs.core.SecurityContext securityContext)	Upload some content to the content repository.

Method Detail

upload

@POST
@Path("/upload")
@Produces("application/json")
void upload(InputStream inputStream,
            @QueryParam("filename")
            String filename,
            @HeaderParam("Content-Type")
            String contentType,
            @Context
            javax.ws.rs.core.UriInfo uriInfo,
            @Context
            javax.ws.rs.core.HttpHeaders httpHeaders,
            @Suspended
            javax.ws.rs.container.AsyncResponse asyncResponse,
            @Context
            javax.ws.rs.core.SecurityContext securityContext)

Upload some content to the content repository.
Rate-limited: Yes.
Requires auth: Yes.
Return: ContentUri. Required. The MXC URI to the uploaded content.

Status code 200: The MXC URI for the uploaded content.

Status code 429: This request was rate-limited.

Parameters:

inputStream - The file content.

filename - The name of the file being uploaded.

contentType - The content type of the file being uploaded.

uriInfo - Request Information.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

securityContext - Security context.

download

@GET
@Path("/download/{serverName}/{mediaId}")
@Produces("application/octet-stream")
void download(@PathParam("serverName")
              String serverName,
              @PathParam("mediaId")
              String mediaId,
              @QueryParam("allow_remote")
              Boolean allowRemote,
              @Context
              javax.ws.rs.core.UriInfo uriInfo,
              @Context
              javax.ws.rs.core.HttpHeaders httpHeaders,
              @Suspended
              javax.ws.rs.container.AsyncResponse asyncResponse)

Download content from the content repository.
Rate-limited: Yes.
Return: OutputStream.

Response headers:

Parameter	Type	Description
Content-Type	string	The content type of the file that was previously uploaded.
Content-Disposition	string	The name of the file that was previously uploaded, if set.

Status code 200: The content that was previously uploaded.

Status code 429: This request was rate-limited.

Parameters:

serverName - Required. The server name from the mxc:// URI (the authoritory component).

mediaId - Required. The media ID from the mxc:// URI (the path component).

allowRemote - Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided.

uriInfo - Request Information.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

downloadFile

@GET
@Path("/download/{serverName}/{mediaId}/{fileName}")
@Produces("application/octet-stream")
void downloadFile(@PathParam("serverName")
                  String serverName,
                  @PathParam("mediaId")
                  String mediaId,
                  @PathParam("fileName")
                  String filename,
                  @QueryParam("allow_remote")
                  Boolean allowRemote,
                  @Context
                  javax.ws.rs.core.UriInfo uriInfo,
                  @Context
                  javax.ws.rs.core.HttpHeaders httpHeaders,
                  @Suspended
                  javax.ws.rs.container.AsyncResponse asyncResponse)

Download content from the content repository as a given filename.
Rate-limited: Yes.
Return: OutputStream.

Response headers:

Parameter	Type	Description
Content-Type	string	The content type of the file that was previously uploaded.
Content-Disposition	string	The name of the file that was previously uploaded, if set.

Status code 200: The content that was previously uploaded.

Status code 429: This request was rate-limited.

Parameters:

serverName - Required. The server name from the mxc:// URI (the authoritory component).

mediaId - Required. The media ID from the mxc:// URI (the path component).

filename - Required. The filename to give in the Content-Disposition.

allowRemote - Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided.

uriInfo - Request Information.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

thumbnail

@GET
@Path("/thumbnail/{serverName}/{mediaId}")
@Produces("application/octet-stream")
void thumbnail(@PathParam("serverName")
               String serverName,
               @PathParam("mediaId")
               String mediaId,
               @QueryParam("width")
               Long width,
               @QueryParam("height")
               Long height,
               @QueryParam("method")
               String method,
               @QueryParam("allow_remote")
               Boolean allowRemote,
               @Context
               javax.ws.rs.core.UriInfo uriInfo,
               @Context
               javax.ws.rs.core.HttpHeaders httpHeaders,
               @Suspended
               javax.ws.rs.container.AsyncResponse asyncResponse)

Download a thumbnail of the content from the content repository.
Rate-limited: Yes.
Return: OutputStream.

Response headers:

Parameter	Type	Description
Key-Type	string	The content type of the file that was previously uploaded.

Status code 200: The content that was previously uploaded.

Status code 429: This request was rate-limited.

Parameters:

serverName - Required. The server name from the mxc:// URI (the authoritory component).

mediaId - Required. The media ID from the mxc:// URI (the path component)

width - The desired width of the thumbnail. The actual thumbnail may not match the size specified.

height - The desired height of the thumbnail. The actual thumbnail may not match the size specified.

method - The desired resizing method. One of: ["crop", "scale"].

allowRemote - Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided.

uriInfo - Request Information.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

previewUrl

@GET
@Path("/preview_url")
@Produces("application/json")
void previewUrl(@QueryParam("url")
                String url,
                @QueryParam("ts")
                String ts,
                @Context
                javax.ws.rs.core.UriInfo uriInfo,
                @Context
                javax.ws.rs.core.HttpHeaders httpHeaders,
                @Suspended
                javax.ws.rs.container.AsyncResponse asyncResponse,
                @Context
                javax.ws.rs.core.SecurityContext securityContext)

Get information about a PATH for a client.
Rate-limited: Yes.
Requires auth: Yes.
Return: Map.

Response headers:

Parameter	Type	Description
matrix:image:size	number	The byte-size of the image. Omitted if there is no image attached.
og:image	string	An MXC URI to the image. Omitted if there is no image.

Status code 200: The content that was previously uploaded.

Status code 429: This request was rate-limited.

Parameters:

url - Required. The PATH to get a preview of.

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.

uriInfo - Request Information.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

securityContext - Security context.

config

@GET
@Path("/config")
@Produces("application/json")
void config(@Context
            javax.ws.rs.core.UriInfo uriInfo,
            @Context
            javax.ws.rs.core.HttpHeaders httpHeaders,
            @Suspended
            javax.ws.rs.container.AsyncResponse asyncResponse,
            @Context
            javax.ws.rs.core.SecurityContext securityContext)

This endpoint allows clients to retrieve the configuration of the content repository, such as upload limitations. Clients SHOULD use this as a guide when using content repository endpoints. All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available.
NOTE: Both clients and server administrators should be aware that proxies between the client and the server may affect the apparent behaviour of content repository APIs, for example, proxies may enforce a lower upload size limit than is advertised by the server on this endpoint.
Rate-limited: Yes. Requires auth: Yes.
Return: ContentConfig.

Status code 200: The public content repository configuration for the matrix server.

Status code 429: This request was rate-limited.

Parameters:

uriInfo - Request Information.

httpHeaders - Http headers.

asyncResponse - Asynchronous response.

securityContext - Security context.