Orthanc Plugin SDK: REST

| Orthanc Plugin SDK 1.12.7 Documentation of the plugin interface of Orthanc

Functions
REST

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.
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.
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.
void | OrthancPluginRedirect (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *redirection)
| Redirect a REST request.
void | OrthancPluginSendHttpStatus (OrthancPluginContext *context, OrthancPluginRestOutput *output, uint16_t status, const void *body, uint32_t bodySize)
| Send a HTTP status, with a custom body.
void | OrthancPluginSendHttpStatusCode (OrthancPluginContext *context, OrthancPluginRestOutput *output, uint16_t status)
| Send a HTTP status code.
void | OrthancPluginSendMethodNotAllowed (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *allowedMethods)
| Signal that this URI does not support this HTTP method.
OrthancPluginErrorCode | OrthancPluginSendMultipartItem (OrthancPluginContext *context, OrthancPluginRestOutput *output, const void *answer, uint32_t answerSize)
| Send an item as a part of some HTTP multipart answer.
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.
OrthancPluginErrorCode | OrthancPluginSendStreamChunk (OrthancPluginContext *context, OrthancPluginRestOutput *output, const void *answer, uint32_t answerSize)
| Send a chunk as a part of an HTTP stream answer.
void | OrthancPluginSendUnauthorized (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *realm)
| Signal that a REST request is not authorized.
void | OrthancPluginSetCookie (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *cookie, const char *value)
| Set a cookie.
void | OrthancPluginSetHttpErrorDetails (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *details, uint8_t log)
| Provide a detailed description for an HTTP error.
void | OrthancPluginSetHttpHeader (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *key, const char *value)
| Set some HTTP header.
OrthancPluginErrorCode | OrthancPluginStartMultipartAnswer (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *subType, const char *contentType)
| Start an HTTP multipart answer.
OrthancPluginErrorCode | OrthancPluginStartStreamAnswer (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *contentType)
| Start an HTTP stream answer.

## 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()

## ◆ OrthancPluginSendStreamChunk()

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

This function sends a chunk as part of an HTTP stream answer that was initiated by OrthancPluginStartStreamAnswer().

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
  OrthancPluginStartStreamAnswer()

## ◆ 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()

## ◆ OrthancPluginStartStreamAnswer()

OrthancPluginErrorCode OrthancPluginStartStreamAnswer | ( | OrthancPluginContext * | context,
|  | OrthancPluginRestOutput * | output,
|  | const char * | contentType )

Initiates an HTTP stream 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.
  contentType | The MIME type of the items in the stream answer.

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

See also
  OrthancPluginSendStreamChunk()