Orthanc Plugin SDK: REST

| Orthanc Plugin SDK 1.3.0 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 char *answer, uint32_t answerSize, const char *mimeType)
| Answer to a REST request. 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 | OrthancPluginSendHttpStatusCode (OrthancPluginContext *context, OrthancPluginRestOutput *output, uint16_t status)
| Send a HTTP status code. More...
void | OrthancPluginSendUnauthorized (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *realm)
| Signal that a REST request is not authorized. More...
void | OrthancPluginSendMethodNotAllowed (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *allowedMethods)
| Signal that this URI does not support this HTTP method. More...
void | OrthancPluginSetCookie (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *cookie, const char *value)
| Set a cookie. 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...
OrthancPluginErrorCode | OrthancPluginSendMultipartItem (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *answer, uint32_t answerSize)
| Send an item as a part of some HTTP multipart answer. More...
void | OrthancPluginSendHttpStatus (OrthancPluginContext *context, OrthancPluginRestOutput *output, uint16_t status, const char *body, uint32_t bodySize)
| Send a HTTP status, with a custom body. 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...
OrthancPluginErrorCode | OrthancPluginSendMultipartItem2 (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *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...

## Detailed Description

## Function Documentation

## ◆ OrthancPluginAnswerBuffer()

void OrthancPluginAnswerBuffer | ( | OrthancPluginContext * | context,
|  | OrthancPluginRestOutput * | output,
|  | const char * | 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 char * | 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 char * | 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 char * | 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.

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