Functions to answer REST requests in a callback. More...

Functions
void	OrthancPluginAnswerBuffer (OrthancPluginContext context, OrthancPluginRestOutput output, const void answer, uint32_t answerSize, const char mimeType)
	Answer to a REST request. More...

void	OrthancPluginCompressAndAnswerJpegImage (OrthancPluginContext context, OrthancPluginRestOutput output, OrthancPluginPixelFormat format, uint32_t width, uint32_t height, uint32_t pitch, const void *buffer, uint8_t quality)
	Answer to a REST request with a JPEG image. More...

void	OrthancPluginCompressAndAnswerPngImage (OrthancPluginContext context, OrthancPluginRestOutput output, OrthancPluginPixelFormat format, uint32_t width, uint32_t height, uint32_t pitch, const void *buffer)
	Answer to a REST request with a PNG image. More...

void	OrthancPluginRedirect (OrthancPluginContext context, OrthancPluginRestOutput output, const char *redirection)
	Redirect a REST request. More...

void	OrthancPluginSendHttpStatus (OrthancPluginContext context, OrthancPluginRestOutput output, uint16_t status, const void *body, uint32_t bodySize)
	Send a HTTP status, with a custom body. More...

void	OrthancPluginSendHttpStatusCode (OrthancPluginContext context, OrthancPluginRestOutput output, uint16_t status)
	Send a HTTP status code. More...

void	OrthancPluginSendMethodNotAllowed (OrthancPluginContext context, OrthancPluginRestOutput output, const char *allowedMethods)
	Signal that this URI does not support this HTTP method. More...

OrthancPluginErrorCode	OrthancPluginSendMultipartItem (OrthancPluginContext context, OrthancPluginRestOutput output, const void *answer, uint32_t answerSize)
	Send an item as a part of some HTTP multipart answer. More...

OrthancPluginErrorCode	OrthancPluginSendMultipartItem2 (OrthancPluginContext context, OrthancPluginRestOutput output, const void answer, uint32_t answerSize, uint32_t headersCount, const char const headersKeys, const char const *headersValues)
	Send an item as a part of some HTTP multipart answer, with custom headers. More...

void	OrthancPluginSendUnauthorized (OrthancPluginContext context, OrthancPluginRestOutput output, const char *realm)
	Signal that a REST request is not authorized. More...

void	OrthancPluginSetCookie (OrthancPluginContext context, OrthancPluginRestOutput output, const char cookie, const char value)
	Set a cookie. More...

void	OrthancPluginSetHttpErrorDetails (OrthancPluginContext context, OrthancPluginRestOutput output, const char *details, uint8_t log)
	Provide a detailed description for an HTTP error. More...

void	OrthancPluginSetHttpHeader (OrthancPluginContext context, OrthancPluginRestOutput output, const char key, const char value)
	Set some HTTP header. More...

OrthancPluginErrorCode	OrthancPluginStartMultipartAnswer (OrthancPluginContext context, OrthancPluginRestOutput output, const char subType, const char contentType)
	Start an HTTP multipart answer. More...

Detailed Description

Function Documentation

◆ OrthancPluginAnswerBuffer()

void OrthancPluginAnswerBuffer	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const void *	answer,
		uint32_t	answerSize,
		const char *	mimeType
	)

This function answers to a REST request with the content of a memory buffer.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
answer	Pointer to the memory buffer containing the answer.
answerSize	Number of bytes of the answer.
mimeType	The MIME type of the answer.

◆ OrthancPluginCompressAndAnswerJpegImage()

void OrthancPluginCompressAndAnswerJpegImage	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		OrthancPluginPixelFormat	format,
		uint32_t	width,
		uint32_t	height,
		uint32_t	pitch,
		const void *	buffer,
		uint8_t	quality
	)

This function answers to a REST request with a JPEG image. The parameters of this function describe a memory buffer that contains an uncompressed image. The image will be automatically compressed as a JPEG image by the core system of Orthanc.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
format	The memory layout of the uncompressed image.
width	The width of the image.
height	The height of the image.
pitch	The pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
buffer	The memory buffer containing the uncompressed image.
quality	The quality of the JPEG encoding, between 1 (worst quality, best compression) and 100 (best quality, worst compression).

◆ OrthancPluginCompressAndAnswerPngImage()

void OrthancPluginCompressAndAnswerPngImage	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		OrthancPluginPixelFormat	format,
		uint32_t	width,
		uint32_t	height,
		uint32_t	pitch,
		const void *	buffer
	)

This function answers to a REST request with a PNG image. The parameters of this function describe a memory buffer that contains an uncompressed image. The image will be automatically compressed as a PNG image by the core system of Orthanc.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
format	The memory layout of the uncompressed image.
width	The width of the image.
height	The height of the image.
pitch	The pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
buffer	The memory buffer containing the uncompressed image.

◆ OrthancPluginRedirect()

void OrthancPluginRedirect	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	redirection
	)

This function answers to a REST request by redirecting the user to another URI using HTTP status 301.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
redirection	Where to redirect.

◆ OrthancPluginSendHttpStatus()

void OrthancPluginSendHttpStatus	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		uint16_t	status,
		const void *	body,
		uint32_t	bodySize
	)

This function answers to a HTTP request by sending a HTTP status code (such as "400 - Bad Request"), together with a body describing the error. The body will only be returned if the configuration option "HttpDescribeErrors" of Orthanc is set to "true".

Note that:

Successful requests (status 200) must use OrthancPluginAnswerBuffer().
Redirections (status 301) must use OrthancPluginRedirect().
Unauthorized access (status 401) must use OrthancPluginSendUnauthorized().
Methods not allowed (status 405) must use OrthancPluginSendMethodNotAllowed().

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
status	The HTTP status code to be sent.
body	The body of the answer.
bodySize	The size of the body.

See also: OrthancPluginSendHttpStatusCode()

◆ OrthancPluginSendHttpStatusCode()

void OrthancPluginSendHttpStatusCode	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		uint16_t	status
	)

This function answers to a REST request by sending a HTTP status code (such as "400 - Bad Request"). Note that:

Successful requests (status 200) must use OrthancPluginAnswerBuffer().
Redirections (status 301) must use OrthancPluginRedirect().
Unauthorized access (status 401) must use OrthancPluginSendUnauthorized().
Methods not allowed (status 405) must use OrthancPluginSendMethodNotAllowed().

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
status	The HTTP status code to be sent.

See also: OrthancPluginSendHttpStatus()

◆ OrthancPluginSendMethodNotAllowed()

void OrthancPluginSendMethodNotAllowed	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	allowedMethods
	)

This function answers to a REST request by signaling that the queried URI does not support this method.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
allowedMethods	The allowed methods for this URI (e.g. "GET,POST" after a PUT or a POST request).

◆ OrthancPluginSendMultipartItem()

OrthancPluginErrorCode OrthancPluginSendMultipartItem	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const void *	answer,
		uint32_t	answerSize
	)

This function sends an item as a part of some HTTP multipart answer that was initiated by OrthancPluginStartMultipartAnswer().

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
answer	Pointer to the memory buffer containing the item.
answerSize	Number of bytes of the item.

Returns: 0 if success, or the error code if failure (this notably happens if the connection is closed by the client).

See also: OrthancPluginSendMultipartItem2()

◆ OrthancPluginSendMultipartItem2()

OrthancPluginErrorCode OrthancPluginSendMultipartItem2	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const void *	answer,
		uint32_t	answerSize,
		uint32_t	headersCount,
		const char const	headersKeys,
		const char const	headersValues
	)

This function sends an item as a part of some HTTP multipart answer that was initiated by OrthancPluginStartMultipartAnswer(). In addition to OrthancPluginSendMultipartItem(), this function will set HTTP header associated with the item.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
answer	Pointer to the memory buffer containing the item.
answerSize	Number of bytes of the item.
headersCount	The number of HTTP headers.
headersKeys	Array containing the keys of the HTTP headers.
headersValues	Array containing the values of the HTTP headers.

Returns: 0 if success, or the error code if failure (this notably happens if the connection is closed by the client).

See also: OrthancPluginSendMultipartItem()

◆ OrthancPluginSendUnauthorized()

void OrthancPluginSendUnauthorized	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	realm
	)

This function answers to a REST request by signaling that it is not authorized.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
realm	The realm for the authorization process.

◆ OrthancPluginSetCookie()

void OrthancPluginSetCookie	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	cookie,
		const char *	value
	)

This function sets a cookie in the HTTP client.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
cookie	The cookie to be set.
value	The value of the cookie.

◆ OrthancPluginSetHttpErrorDetails()

void OrthancPluginSetHttpErrorDetails	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	details,
		uint8_t	log
	)

This function sets the detailed description associated with an HTTP error. This description will be displayed in the "Details" field of the JSON body of the HTTP answer. It is only taken into consideration if the REST callback returns an error code that is different from "OrthancPluginErrorCode_Success", and if the "HttpDescribeErrors" configuration option of Orthanc is set to "true".

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
details	The details of the error message.
log	Whether to also write the detailed error to the Orthanc logs.

◆ OrthancPluginSetHttpHeader()

void OrthancPluginSetHttpHeader	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	key,
		const char *	value
	)

This function sets a HTTP header in the HTTP answer.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
key	The HTTP header to be set.
value	The value of the HTTP header.

◆ OrthancPluginStartMultipartAnswer()

OrthancPluginErrorCode OrthancPluginStartMultipartAnswer	(	OrthancPluginContext *	context,
		OrthancPluginRestOutput *	output,
		const char *	subType,
		const char *	contentType
	)

Initiates a HTTP multipart answer, as the result of a REST request.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
output	The HTTP connection to the client application.
subType	The sub-type of the multipart answer ("mixed" or "related").
contentType	The MIME type of the items in the multipart answer.

Returns: 0 if success, or the error code if failure.

See also: OrthancPluginSendMultipartItem(), OrthancPluginSendMultipartItem2()