Orthanc Plugin SDK  1.3.1
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

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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
answerPointer to the memory buffer containing the answer.
answerSizeNumber of bytes of the answer.
mimeTypeThe MIME type of the answer.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
formatThe memory layout of the uncompressed image.
widthThe width of the image.
heightThe height of the image.
pitchThe pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
bufferThe memory buffer containing the uncompressed image.
qualityThe quality of the JPEG encoding, between 1 (worst quality, best compression) and 100 (best quality, worst compression).
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
formatThe memory layout of the uncompressed image.
widthThe width of the image.
heightThe height of the image.
pitchThe pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
bufferThe memory buffer containing the uncompressed image.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
redirectionWhere to redirect.
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:

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
statusThe HTTP status code to be sent.
bodyThe body of the answer.
bodySizeThe size of the body.
See also
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:

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
statusThe HTTP status code to be sent.
See also
OrthancPluginSendHttpStatus()
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
allowedMethodsThe allowed methods for this URI (e.g. "GET,POST" after a PUT or a POST request).
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
answerPointer to the memory buffer containing the item.
answerSizeNumber 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()
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
answerPointer to the memory buffer containing the item.
answerSizeNumber of bytes of the item.
headersCountThe number of HTTP headers.
headersKeysArray containing the keys of the HTTP headers.
headersValuesArray 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()
void OrthancPluginSendUnauthorized ( OrthancPluginContext context,
OrthancPluginRestOutput output,
const char *  realm 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
realmThe realm for the authorization process.
void OrthancPluginSetCookie ( OrthancPluginContext context,
OrthancPluginRestOutput output,
const char *  cookie,
const char *  value 
)

This function sets a cookie in the HTTP client.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
cookieThe cookie to be set.
valueThe value of the cookie.
void OrthancPluginSetHttpHeader ( OrthancPluginContext context,
OrthancPluginRestOutput output,
const char *  key,
const char *  value 
)

This function sets a HTTP header in the HTTP answer.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
keyThe HTTP header to be set.
valueThe value of the HTTP header.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
outputThe HTTP connection to the client application.
subTypeThe sub-type of the multipart answer ("mixed" or "related").
contentTypeThe MIME type of the items in the multipart answer.
Returns
0 if success, or the error code if failure.
See also
OrthancPluginSendMultipartItem(), OrthancPluginSendMultipartItem2()