Orthanc Plugin SDK: Toolbox

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

Classes | Typedefs | Enumerations | Functions
Toolbox

Generic functions to help with the creation of plugins. More...

## Classes
struct | OrthancPluginHttpRequest
| The parameters of a REST request. More...
struct | OrthancPluginMemoryBuffer
| A memory buffer allocated by the core system of Orthanc. More...
struct | OrthancPluginDictionaryEntry
| An entry in the dictionary of DICOM tags. More...

## Typedefs
typedef struct _OrthancPluginRestOutput_t | OrthancPluginRestOutput
| Opaque structure that represents the HTTP connection to the client application.
typedef struct _OrthancPluginDicomInstance_t | OrthancPluginDicomInstance
| Opaque structure that represents a DICOM instance received by Orthanc.
typedef struct _OrthancPluginWorklistQuery_t | OrthancPluginWorklistQuery
| Opaque structure to an object that represents a C-Find query for worklists.
typedef struct _OrthancPluginWorklistAnswers_t | OrthancPluginWorklistAnswers
| Opaque structure to an object that represents the answers to a C-Find query for worklists.
typedef struct _OrthancPluginFindQuery_t | OrthancPluginFindQuery
| Opaque structure to an object that represents a C-Find query.
typedef struct _OrthancPluginFindAnswers_t | OrthancPluginFindAnswers
| Opaque structure to an object that represents the answers to a C-Find query for worklists.
typedef struct _OrthancPluginFindAnswers_t | OrthancPluginFindMatcher
| Opaque structure to an object that can be used to check whether a DICOM instance matches a C-Find query.
typedef void(* | OrthancPluginFree) (void *buffer)
| Signature of a function to free dynamic memory.
typedef OrthancPluginErrorCode(* | OrthancPluginWorklistCallback) (OrthancPluginWorklistAnswers *answers, const OrthancPluginWorklistQuery *query, const char *issuerAet, const char *calledAet)
| Callback to handle the C-Find SCP requests for worklists. More...
typedef int32_t(* | OrthancPluginIncomingHttpRequestFilter) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues)
| Callback to filter incoming HTTP requests received by Orthanc. More...
typedef int32_t(* | OrthancPluginIncomingHttpRequestFilter2) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, uint32_t getArgumentsCount, const char *const *getArgumentsKeys, const char *const *getArgumentsValues)
| Callback to filter incoming HTTP requests received by Orthanc. More...
typedef OrthancPluginErrorCode(* | OrthancPluginFindCallback) (OrthancPluginFindAnswers *answers, const OrthancPluginFindQuery *query, const char *issuerAet, const char *calledAet)
| Callback to handle incoming C-Find SCP requests. More...
typedef void *(* | OrthancPluginMoveCallback) (OrthancPluginResourceType resourceType, const char *patientId, const char *accessionNumber, const char *studyInstanceUid, const char *seriesInstanceUid, const char *sopInstanceUid, const char *originatorAet, const char *sourceAet, const char *targetAet, uint16_t originatorId)
| Callback to handle incoming C-Move SCP requests. More...
typedef uint32_t(* | OrthancPluginGetMoveSize) (void *moveDriver)
| Callback to read the size of a C-Move driver. More...
typedef OrthancPluginErrorCode(* | OrthancPluginApplyMove) (void *moveDriver)
| Callback to apply one C-Move suboperation. More...
typedef void(* | OrthancPluginFreeMove) (void *moveDriver)
| Callback to free one C-Move driver. More...
typedef struct _OrthancPluginContext_t | OrthancPluginContext
| Data structure that contains information about the Orthanc core.

## Enumerations
enum | OrthancPluginErrorCode { OrthancPluginErrorCode_InternalError, OrthancPluginErrorCode_Success, OrthancPluginErrorCode_Plugin, OrthancPluginErrorCode_NotImplemented, OrthancPluginErrorCode_ParameterOutOfRange, OrthancPluginErrorCode_NotEnoughMemory, OrthancPluginErrorCode_BadParameterType, OrthancPluginErrorCode_BadSequenceOfCalls, OrthancPluginErrorCode_InexistentItem, OrthancPluginErrorCode_BadRequest, OrthancPluginErrorCode_NetworkProtocol, OrthancPluginErrorCode_SystemCommand, OrthancPluginErrorCode_Database, OrthancPluginErrorCode_UriSyntax, OrthancPluginErrorCode_InexistentFile, OrthancPluginErrorCode_CannotWriteFile, OrthancPluginErrorCode_BadFileFormat, OrthancPluginErrorCode_Timeout, OrthancPluginErrorCode_UnknownResource, OrthancPluginErrorCode_IncompatibleDatabaseVersion, OrthancPluginErrorCode_FullStorage, OrthancPluginErrorCode_CorruptedFile, OrthancPluginErrorCode_InexistentTag, OrthancPluginErrorCode_ReadOnly, OrthancPluginErrorCode_IncompatibleImageFormat, OrthancPluginErrorCode_IncompatibleImageSize, OrthancPluginErrorCode_SharedLibrary, OrthancPluginErrorCode_UnknownPluginService, OrthancPluginErrorCode_UnknownDicomTag, OrthancPluginErrorCode_BadJson, OrthancPluginErrorCode_Unauthorized, OrthancPluginErrorCode_BadFont, OrthancPluginErrorCode_DatabasePlugin, OrthancPluginErrorCode_StorageAreaPlugin, OrthancPluginErrorCode_EmptyRequest, OrthancPluginErrorCode_NotAcceptable, OrthancPluginErrorCode_NullPointer, OrthancPluginErrorCode_SQLiteNotOpened, OrthancPluginErrorCode_SQLiteAlreadyOpened, OrthancPluginErrorCode_SQLiteCannotOpen, OrthancPluginErrorCode_SQLiteStatementAlreadyUsed, OrthancPluginErrorCode_SQLiteExecute, OrthancPluginErrorCode_SQLiteRollbackWithoutTransaction, OrthancPluginErrorCode_SQLiteCommitWithoutTransaction, OrthancPluginErrorCode_SQLiteRegisterFunction, OrthancPluginErrorCode_SQLiteFlush, OrthancPluginErrorCode_SQLiteCannotRun, OrthancPluginErrorCode_SQLiteCannotStep, OrthancPluginErrorCode_SQLiteBindOutOfRange, OrthancPluginErrorCode_SQLitePrepareStatement, OrthancPluginErrorCode_SQLiteTransactionAlreadyStarted, OrthancPluginErrorCode_SQLiteTransactionCommit, OrthancPluginErrorCode_SQLiteTransactionBegin, OrthancPluginErrorCode_DirectoryOverFile, OrthancPluginErrorCode_FileStorageCannotWrite, OrthancPluginErrorCode_DirectoryExpected, OrthancPluginErrorCode_HttpPortInUse, OrthancPluginErrorCode_DicomPortInUse, OrthancPluginErrorCode_BadHttpStatusInRest, OrthancPluginErrorCode_RegularFileExpected, OrthancPluginErrorCode_PathToExecutable, OrthancPluginErrorCode_MakeDirectory, OrthancPluginErrorCode_BadApplicationEntityTitle, OrthancPluginErrorCode_NoCFindHandler, OrthancPluginErrorCode_NoCMoveHandler, OrthancPluginErrorCode_NoCStoreHandler, OrthancPluginErrorCode_NoApplicationEntityFilter, OrthancPluginErrorCode_NoSopClassOrInstance, OrthancPluginErrorCode_NoPresentationContext, OrthancPluginErrorCode_DicomFindUnavailable, OrthancPluginErrorCode_DicomMoveUnavailable, OrthancPluginErrorCode_CannotStoreInstance, OrthancPluginErrorCode_CreateDicomNotString, OrthancPluginErrorCode_CreateDicomOverrideTag, OrthancPluginErrorCode_CreateDicomUseContent, OrthancPluginErrorCode_CreateDicomNoPayload, OrthancPluginErrorCode_CreateDicomUseDataUriScheme, OrthancPluginErrorCode_CreateDicomBadParent, OrthancPluginErrorCode_CreateDicomParentIsInstance, OrthancPluginErrorCode_CreateDicomParentEncoding, OrthancPluginErrorCode_UnknownModality, OrthancPluginErrorCode_BadJobOrdering, OrthancPluginErrorCode_JsonToLuaTable, OrthancPluginErrorCode_CannotCreateLua, OrthancPluginErrorCode_CannotExecuteLua, OrthancPluginErrorCode_LuaAlreadyExecuted, OrthancPluginErrorCode_LuaBadOutput, OrthancPluginErrorCode_NotLuaPredicate, OrthancPluginErrorCode_LuaReturnsNoString, OrthancPluginErrorCode_StorageAreaAlreadyRegistered, OrthancPluginErrorCode_DatabaseBackendAlreadyRegistered, OrthancPluginErrorCode_DatabaseNotInitialized, OrthancPluginErrorCode_SslDisabled, OrthancPluginErrorCode_CannotOrderSlices, OrthancPluginErrorCode_NoWorklistHandler, OrthancPluginErrorCode_AlreadyExistingTag }
enum | OrthancPluginHttpMethod { OrthancPluginHttpMethod_Get, OrthancPluginHttpMethod_Post, OrthancPluginHttpMethod_Put, OrthancPluginHttpMethod_Delete }
enum | OrthancPluginContentType { OrthancPluginContentType_Unknown, OrthancPluginContentType_Dicom, OrthancPluginContentType_DicomAsJson }
enum | OrthancPluginResourceType { OrthancPluginResourceType_Patient, OrthancPluginResourceType_Study, OrthancPluginResourceType_Series, OrthancPluginResourceType_Instance, OrthancPluginResourceType_None }
enum | OrthancPluginValueRepresentation { OrthancPluginValueRepresentation_AE, OrthancPluginValueRepresentation_AS, OrthancPluginValueRepresentation_AT, OrthancPluginValueRepresentation_CS, OrthancPluginValueRepresentation_DA, OrthancPluginValueRepresentation_DS, OrthancPluginValueRepresentation_DT, OrthancPluginValueRepresentation_FD, OrthancPluginValueRepresentation_FL, OrthancPluginValueRepresentation_IS, OrthancPluginValueRepresentation_LO, OrthancPluginValueRepresentation_LT, OrthancPluginValueRepresentation_OB, OrthancPluginValueRepresentation_OF, OrthancPluginValueRepresentation_OW, OrthancPluginValueRepresentation_PN, OrthancPluginValueRepresentation_SH, OrthancPluginValueRepresentation_SL, OrthancPluginValueRepresentation_SQ, OrthancPluginValueRepresentation_SS, OrthancPluginValueRepresentation_ST, OrthancPluginValueRepresentation_TM, OrthancPluginValueRepresentation_UI, OrthancPluginValueRepresentation_UL, OrthancPluginValueRepresentation_UN, OrthancPluginValueRepresentation_US, OrthancPluginValueRepresentation_UT }
enum | OrthancPluginDicomToJsonFormat { OrthancPluginDicomToJsonFormat_Full, OrthancPluginDicomToJsonFormat_Short, OrthancPluginDicomToJsonFormat_Human }
enum | OrthancPluginDicomToJsonFlags { OrthancPluginDicomToJsonFlags_None, OrthancPluginDicomToJsonFlags_IncludeBinary, OrthancPluginDicomToJsonFlags_IncludePrivateTags, OrthancPluginDicomToJsonFlags_IncludeUnknownTags, OrthancPluginDicomToJsonFlags_IncludePixelData, OrthancPluginDicomToJsonFlags_ConvertBinaryToAscii, OrthancPluginDicomToJsonFlags_ConvertBinaryToNull }
enum | OrthancPluginCreateDicomFlags { OrthancPluginCreateDicomFlags_None, OrthancPluginCreateDicomFlags_DecodeDataUriScheme, OrthancPluginCreateDicomFlags_GenerateIdentifiers }
enum | OrthancPluginIdentifierConstraint { OrthancPluginIdentifierConstraint_Equal, OrthancPluginIdentifierConstraint_SmallerOrEqual, OrthancPluginIdentifierConstraint_GreaterOrEqual, OrthancPluginIdentifierConstraint_Wildcard }
enum | OrthancPluginInstanceOrigin { OrthancPluginInstanceOrigin_Unknown, OrthancPluginInstanceOrigin_DicomProtocol, OrthancPluginInstanceOrigin_RestApi, OrthancPluginInstanceOrigin_Plugin, OrthancPluginInstanceOrigin_Lua }

## Functions
void | OrthancPluginFreeString (OrthancPluginContext *context, char *str)
| Free a string. More...
void | OrthancPluginFreeMemoryBuffer (OrthancPluginContext *context, OrthancPluginMemoryBuffer *buffer)
| Free a memory buffer. More...
void | OrthancPluginLogError (OrthancPluginContext *context, const char *message)
| Log an error. More...
void | OrthancPluginLogWarning (OrthancPluginContext *context, const char *message)
| Log a warning. More...
void | OrthancPluginLogInfo (OrthancPluginContext *context, const char *message)
| Log an information. More...
char * | OrthancPluginGetOrthancPath (OrthancPluginContext *context)
| Return the path to the Orthanc executable. More...
char * | OrthancPluginGetOrthancDirectory (OrthancPluginContext *context)
| Return the directory containing the Orthanc. More...
char * | OrthancPluginGetConfigurationPath (OrthancPluginContext *context)
| Return the path to the configuration file(s). More...
void | OrthancPluginSetRootUri (OrthancPluginContext *context, const char *uri)
| Set the URI where the plugin provides its Web interface. More...
void | OrthancPluginSetDescription (OrthancPluginContext *context, const char *description)
| Set a description for this plugin. More...
void | OrthancPluginExtendOrthancExplorer (OrthancPluginContext *context, const char *javascript)
| Extend the JavaScript code of Orthanc Explorer. More...
uint32_t | OrthancPluginGetCommandLineArgumentsCount (OrthancPluginContext *context)
| Get the number of command-line arguments. More...
char * | OrthancPluginGetCommandLineArgument (OrthancPluginContext *context, uint32_t argument)
| Get the value of a command-line argument. More...
char * | OrthancPluginGetConfiguration (OrthancPluginContext *context)
| Return the content of the configuration file(s). More...
OrthancPluginErrorCode | OrthancPluginReadFile (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *path)
| Read a file. More...
OrthancPluginErrorCode | OrthancPluginWriteFile (OrthancPluginContext *context, const char *path, const void *data, uint32_t size)
| Write a file. More...
const char * | OrthancPluginGetErrorDescription (OrthancPluginContext *context, OrthancPluginErrorCode error)
| Get the description of a given error code. More...
OrthancPluginErrorCode | OrthancPluginHttpGet (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *url, const char *username, const char *password)
| Issue a HTTP GET call. More...
OrthancPluginErrorCode | OrthancPluginHttpPost (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *url, const char *body, uint32_t bodySize, const char *username, const char *password)
| Issue a HTTP POST call. More...
OrthancPluginErrorCode | OrthancPluginHttpPut (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *url, const char *body, uint32_t bodySize, const char *username, const char *password)
| Issue a HTTP PUT call. More...
OrthancPluginErrorCode | OrthancPluginHttpDelete (OrthancPluginContext *context, const char *url, const char *username, const char *password)
| Issue a HTTP DELETE call. More...
OrthancPluginErrorCode | OrthancPluginRegisterErrorCode (OrthancPluginContext *context, int32_t code, uint16_t httpStatus, const char *message)
| Declare a custom error code for this plugin. More...
OrthancPluginErrorCode | OrthancPluginRegisterDictionaryTag (OrthancPluginContext *context, uint16_t group, uint16_t element, OrthancPluginValueRepresentation vr, const char *name, uint32_t minMultiplicity, uint32_t maxMultiplicity)
| Register a new tag into the DICOM dictionary. More...
OrthancPluginErrorCode | OrthancPluginRegisterPrivateDictionaryTag (OrthancPluginContext *context, uint16_t group, uint16_t element, OrthancPluginValueRepresentation vr, const char *name, uint32_t minMultiplicity, uint32_t maxMultiplicity, const char *privateCreator)
| Register a new private tag into the DICOM dictionary. More...
char * | OrthancPluginDicomBufferToJson (OrthancPluginContext *context, const void *buffer, uint32_t size, OrthancPluginDicomToJsonFormat format, OrthancPluginDicomToJsonFlags flags, uint32_t maxStringLength)
| Format a DICOM memory buffer as a JSON string. More...
char * | OrthancPluginDicomInstanceToJson (OrthancPluginContext *context, const char *instanceId, OrthancPluginDicomToJsonFormat format, OrthancPluginDicomToJsonFlags flags, uint32_t maxStringLength)
| Format a DICOM instance as a JSON string. More...
OrthancPluginErrorCode | OrthancPluginRegisterWorklistCallback (OrthancPluginContext *context, OrthancPluginWorklistCallback callback)
| Register a callback to handle modality worklists requests. More...
OrthancPluginErrorCode | OrthancPluginWorklistAddAnswer (OrthancPluginContext *context, OrthancPluginWorklistAnswers *answers, const OrthancPluginWorklistQuery *query, const void *dicom, uint32_t size)
| Add one answer to some modality worklist request. More...
OrthancPluginErrorCode | OrthancPluginWorklistMarkIncomplete (OrthancPluginContext *context, OrthancPluginWorklistAnswers *answers)
| Mark the set of worklist answers as incomplete. More...
int32_t | OrthancPluginWorklistIsMatch (OrthancPluginContext *context, const OrthancPluginWorklistQuery *query, const void *dicom, uint32_t size)
| Test whether a worklist matches the query. More...
OrthancPluginErrorCode | OrthancPluginWorklistGetDicomQuery (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const OrthancPluginWorklistQuery *query)
| Retrieve the worklist query as a DICOM file. More...
OrthancPluginErrorCode | OrthancPluginCreateDicom (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *json, const OrthancPluginImage *pixelData, OrthancPluginCreateDicomFlags flags)
| Create a DICOM instance from a JSON string and an image. More...
char * | OrthancPluginComputeMd5 (OrthancPluginContext *context, const void *buffer, uint32_t size)
| Compute an MD5 hash. More...
char * | OrthancPluginComputeSha1 (OrthancPluginContext *context, const void *buffer, uint32_t size)
| Compute a SHA-1 hash. More...
OrthancPluginErrorCode | OrthancPluginLookupDictionary (OrthancPluginContext *context, OrthancPluginDictionaryEntry *target, const char *name)
| Get information about the given DICOM tag. More...
OrthancPluginErrorCode | OrthancPluginHttpClient (OrthancPluginContext *context, OrthancPluginMemoryBuffer *answerBody, OrthancPluginMemoryBuffer *answerHeaders, uint16_t *httpStatus, OrthancPluginHttpMethod method, const char *url, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, const char *body, uint32_t bodySize, const char *username, const char *password, uint32_t timeout, const char *certificateFile, const char *certificateKeyFile, const char *certificateKeyPassword, uint8_t pkcs11)
| Issue a HTTP call with full flexibility. More...
char * | OrthancPluginGenerateUuid (OrthancPluginContext *context)
| Generate an UUID. More...
OrthancPluginErrorCode | OrthancPluginRegisterFindCallback (OrthancPluginContext *context, OrthancPluginFindCallback callback)
| Register a callback to handle C-Find requests. More...
OrthancPluginErrorCode | OrthancPluginFindAddAnswer (OrthancPluginContext *context, OrthancPluginFindAnswers *answers, const void *dicom, uint32_t size)
| Add one answer to some C-Find request. More...
OrthancPluginErrorCode | OrthancPluginFindMarkIncomplete (OrthancPluginContext *context, OrthancPluginFindAnswers *answers)
| Mark the set of C-Find answers as incomplete. More...
uint32_t | OrthancPluginGetFindQuerySize (OrthancPluginContext *context, const OrthancPluginFindQuery *query)
| Get the number of tags in a C-Find query. More...
OrthancPluginErrorCode | OrthancPluginGetFindQueryTag (OrthancPluginContext *context, uint16_t *group, uint16_t *element, const OrthancPluginFindQuery *query, uint32_t index)
| Get one tag in a C-Find query. More...
char * | OrthancPluginGetFindQueryTagName (OrthancPluginContext *context, const OrthancPluginFindQuery *query, uint32_t index)
| Get the symbolic name of one tag in a C-Find query. More...
char * | OrthancPluginGetFindQueryValue (OrthancPluginContext *context, const OrthancPluginFindQuery *query, uint32_t index)
| Get the value associated with one tag in a C-Find query. More...
OrthancPluginErrorCode | OrthancPluginRegisterMoveCallback (OrthancPluginContext *context, OrthancPluginMoveCallback callback, OrthancPluginGetMoveSize getMoveSize, OrthancPluginApplyMove applyMove, OrthancPluginFreeMove freeMove)
| Register a callback to handle C-Move requests. More...
OrthancPluginFindMatcher * | OrthancPluginCreateFindMatcher (OrthancPluginContext *context, const void *query, uint32_t size)
| Create a C-Find matcher. More...
void | OrthancPluginFreeFindMatcher (OrthancPluginContext *context, OrthancPluginFindMatcher *matcher)
| Free a C-Find matcher. More...
int32_t | OrthancPluginFindMatcherIsMatch (OrthancPluginContext *context, const OrthancPluginFindMatcher *matcher, const void *dicom, uint32_t size)
| Test whether a DICOM instance matches a C-Find query. More...

## Detailed Description

## Typedef Documentation

## ◆ OrthancPluginApplyMove

typedef OrthancPluginErrorCode(* OrthancPluginApplyMove) (void *moveDriver)

Signature of a callback function that applies the next C-Move suboperation that os to be achieved by the given C-Move driver. This driver is the return value of a previous call to the OrthancPluginMoveCallback() callback.

Parameters

  moveDriver | The C-Move driver of interest.

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

## ◆ OrthancPluginFindCallback

typedef OrthancPluginErrorCode(* OrthancPluginFindCallback) (OrthancPluginFindAnswers *answers, const OrthancPluginFindQuery *query, const char *issuerAet, const char *calledAet)

Signature of a callback function that is triggered whenever Orthanc receives a C-Find SCP request not concerning modality worklists.

Parameters

  answers | The target structure where answers must be stored.
  query | The worklist query.
  issuerAet | The Application Entity Title (AET) of the modality from which the request originates.
  calledAet | The Application Entity Title (AET) of the modality that is called by the request.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginFreeMove

typedef void(* OrthancPluginFreeMove) (void *moveDriver)

Signature of a callback function that releases the resources allocated by the given C-Move driver. This driver is the return value of a previous call to the OrthancPluginMoveCallback() callback.

Parameters

  moveDriver | The C-Move driver of interest.

## ◆ OrthancPluginGetMoveSize

typedef uint32_t(* OrthancPluginGetMoveSize) (void *moveDriver)

Signature of a callback function that returns the number of C-Move suboperations that are to be achieved by the given C-Move driver. This driver is the return value of a previous call to the OrthancPluginMoveCallback() callback.

Parameters

  moveDriver | The C-Move driver of interest.

Returns
  The number of suboperations.

## ◆ OrthancPluginIncomingHttpRequestFilter

typedef int32_t(* OrthancPluginIncomingHttpRequestFilter) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues)

Signature of a callback function that is triggered whenever Orthanc receives an HTTP/REST request, and that answers whether this request should be allowed. If the callback returns "0" ("false"), the server answers with HTTP status code 403 (Forbidden).

Parameters

  method | The HTTP method used by the request.
  uri | The URI of interest.
  ip | The IP address of the HTTP client.
  headersCount | The number of HTTP headers.
  headersKeys | The keys of the HTTP headers (always converted to low-case).
  headersValues | The values of the HTTP headers.

Returns
  0 if forbidden access, 1 if allowed access, -1 if error.

Deprecated:
  Please instead use OrthancPluginIncomingHttpRequestFilter2()

## ◆ OrthancPluginIncomingHttpRequestFilter2

typedef int32_t(* OrthancPluginIncomingHttpRequestFilter2) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, uint32_t getArgumentsCount, const char *const *getArgumentsKeys, const char *const *getArgumentsValues)

Signature of a callback function that is triggered whenever Orthanc receives an HTTP/REST request, and that answers whether this request should be allowed. If the callback returns "0" ("false"), the server answers with HTTP status code 403 (Forbidden).

Parameters

  method | The HTTP method used by the request.
  uri | The URI of interest.
  ip | The IP address of the HTTP client.
  headersCount | The number of HTTP headers.
  headersKeys | The keys of the HTTP headers (always converted to low-case).
  headersValues | The values of the HTTP headers.
  getArgumentsCount | The number of GET arguments (only for the GET HTTP method).
  getArgumentsKeys | The keys of the GET arguments (only for the GET HTTP method).
  getArgumentsValues | The values of the GET arguments (only for the GET HTTP method).

Returns
  0 if forbidden access, 1 if allowed access, -1 if error.

## ◆ OrthancPluginMoveCallback

typedef void*(* OrthancPluginMoveCallback) (OrthancPluginResourceType resourceType, const char *patientId, const char *accessionNumber, const char *studyInstanceUid, const char *seriesInstanceUid, const char *sopInstanceUid, const char *originatorAet, const char *sourceAet, const char *targetAet, uint16_t originatorId)

Signature of a callback function that is triggered whenever Orthanc receives a C-Move SCP request. The callback receives the type of the resource of interest (study, series, instance...) together with the DICOM tags containing its identifiers. In turn, the plugin must create a driver object that will be responsible for driving the successive move suboperations.

Parameters

  resourceType | The type of the resource of interest. Note that this might be set to ResourceType_None if the QueryRetrieveLevel (0008,0052) tag was not provided by the issuer (i.e. the originator modality).
  patientId | Content of the PatientID (0x0010, 0x0020) tag of the resource of interest. Might be NULL.
  accessionNumber | Content of the AccessionNumber (0x0008, 0x0050) tag. Might be NULL.
  studyInstanceUid | Content of the StudyInstanceUID (0x0020, 0x000d) tag. Might be NULL.
  seriesInstanceUid | Content of the SeriesInstanceUID (0x0020, 0x000e) tag. Might be NULL.
  sopInstanceUid | Content of the SOPInstanceUID (0x0008, 0x0018) tag. Might be NULL.
  originatorAet | The Application Entity Title (AET) of the modality from which the request originates.
  sourceAet | The Application Entity Title (AET) of the modality that should send its DICOM files to another modality.
  targetAet | The Application Entity Title (AET) of the modality that should receive the DICOM files.
  originatorId | The Message ID issued by the originator modality, as found in tag (0000,0110) of the DICOM query emitted by the issuer.

Returns
  The NULL value if the plugin cannot deal with this query, or a pointer to the driver object that is responsible for handling the successive move suboperations.

Note
  If targetAet equals sourceAet, this is actually a query/retrieve operation.

## ◆ OrthancPluginWorklistCallback

typedef OrthancPluginErrorCode(* OrthancPluginWorklistCallback) (OrthancPluginWorklistAnswers *answers, const OrthancPluginWorklistQuery *query, const char *issuerAet, const char *calledAet)

Signature of a callback function that is triggered when Orthanc receives a C-Find SCP request against modality worklists.

Parameters

  answers | The target structure where answers must be stored.
  query | The worklist query.
  issuerAet | The Application Entity Title (AET) of the modality from which the request originates.
  calledAet | The Application Entity Title (AET) of the modality that is called by the request.

Returns
  0 if success, other value if error.

## Enumeration Type Documentation

## ◆ OrthancPluginContentType

enum OrthancPluginContentType

The content types that are supported by Orthanc plugins.

Enumerator
OrthancPluginContentType_Unknown | Unknown content type
OrthancPluginContentType_Dicom | DICOM
OrthancPluginContentType_DicomAsJson | JSON summary of a DICOM file

## ◆ OrthancPluginCreateDicomFlags

enum OrthancPluginCreateDicomFlags

Flags to the creation of a DICOM file.

See also
  OrthancPluginCreateDicom()

Enumerator
OrthancPluginCreateDicomFlags_DecodeDataUriScheme | Decode fields encoded using data URI scheme
OrthancPluginCreateDicomFlags_GenerateIdentifiers | Automatically generate DICOM identifiers

## ◆ OrthancPluginDicomToJsonFlags

enum OrthancPluginDicomToJsonFlags

Flags to customize a DICOM-to-JSON conversion. By default, binary tags are formatted using Data URI scheme.

Enumerator
OrthancPluginDicomToJsonFlags_IncludeBinary | Include the binary tags
OrthancPluginDicomToJsonFlags_IncludePrivateTags | Include the private tags
OrthancPluginDicomToJsonFlags_IncludeUnknownTags | Include the tags unknown by the dictionary
OrthancPluginDicomToJsonFlags_IncludePixelData | Include the pixel data
OrthancPluginDicomToJsonFlags_ConvertBinaryToAscii | Output binary tags as-is, dropping non-ASCII
OrthancPluginDicomToJsonFlags_ConvertBinaryToNull | Signal binary tags as null values

## ◆ OrthancPluginDicomToJsonFormat

enum OrthancPluginDicomToJsonFormat

The possible output formats for a DICOM-to-JSON conversion.

See also
  OrthancPluginDicomToJson()

Enumerator
OrthancPluginDicomToJsonFormat_Full | Full output, with most details
OrthancPluginDicomToJsonFormat_Short | Tags output as hexadecimal numbers
OrthancPluginDicomToJsonFormat_Human | Human-readable JSON

## ◆ OrthancPluginErrorCode

enum OrthancPluginErrorCode

For Microsoft Visual Studio, a compatibility "stdint.h" can be downloaded at the following URL: https://orthanc.googlecode.com/hg/Resources/ThirdParty/VisualStudio/stdint.h The various error codes that can be returned by the Orthanc core.

Enumerator
OrthancPluginErrorCode_InternalError | Internal error
OrthancPluginErrorCode_Success | Success
OrthancPluginErrorCode_Plugin | Error encountered within the plugin engine
OrthancPluginErrorCode_NotImplemented | Not implemented yet
OrthancPluginErrorCode_ParameterOutOfRange | Parameter out of range
OrthancPluginErrorCode_NotEnoughMemory | The server hosting Orthanc is running out of memory
OrthancPluginErrorCode_BadParameterType | Bad type for a parameter
OrthancPluginErrorCode_BadSequenceOfCalls | Bad sequence of calls
OrthancPluginErrorCode_InexistentItem | Accessing an inexistent item
OrthancPluginErrorCode_BadRequest | Bad request
OrthancPluginErrorCode_NetworkProtocol | Error in the network protocol
OrthancPluginErrorCode_SystemCommand | Error while calling a system command
OrthancPluginErrorCode_Database | Error with the database engine
OrthancPluginErrorCode_UriSyntax | Badly formatted URI
OrthancPluginErrorCode_InexistentFile | Inexistent file
OrthancPluginErrorCode_CannotWriteFile | Cannot write to file
OrthancPluginErrorCode_BadFileFormat | Bad file format
OrthancPluginErrorCode_Timeout | Timeout
OrthancPluginErrorCode_UnknownResource | Unknown resource
OrthancPluginErrorCode_IncompatibleDatabaseVersion | Incompatible version of the database
OrthancPluginErrorCode_FullStorage | The file storage is full
OrthancPluginErrorCode_CorruptedFile | Corrupted file (e.g. inconsistent MD5 hash)
OrthancPluginErrorCode_InexistentTag | Inexistent tag
OrthancPluginErrorCode_ReadOnly | Cannot modify a read-only data structure
OrthancPluginErrorCode_IncompatibleImageFormat | Incompatible format of the images
OrthancPluginErrorCode_IncompatibleImageSize | Incompatible size of the images
OrthancPluginErrorCode_SharedLibrary | Error while using a shared library (plugin)
OrthancPluginErrorCode_UnknownPluginService | Plugin invoking an unknown service
OrthancPluginErrorCode_UnknownDicomTag | Unknown DICOM tag
OrthancPluginErrorCode_BadJson | Cannot parse a JSON document
OrthancPluginErrorCode_Unauthorized | Bad credentials were provided to an HTTP request
OrthancPluginErrorCode_BadFont | Badly formatted font file
OrthancPluginErrorCode_DatabasePlugin | The plugin implementing a custom database back-end does not fulfill the proper interface
OrthancPluginErrorCode_StorageAreaPlugin | Error in the plugin implementing a custom storage area
OrthancPluginErrorCode_EmptyRequest | The request is empty
OrthancPluginErrorCode_NotAcceptable | Cannot send a response which is acceptable according to the Accept HTTP header
OrthancPluginErrorCode_NullPointer | Cannot handle a NULL pointer
OrthancPluginErrorCode_SQLiteNotOpened | SQLite: The database is not opened
OrthancPluginErrorCode_SQLiteAlreadyOpened | SQLite: Connection is already open
OrthancPluginErrorCode_SQLiteCannotOpen | SQLite: Unable to open the database
OrthancPluginErrorCode_SQLiteStatementAlreadyUsed | SQLite: This cached statement is already being referred to
OrthancPluginErrorCode_SQLiteExecute | SQLite: Cannot execute a command
OrthancPluginErrorCode_SQLiteRollbackWithoutTransaction | SQLite: Rolling back a nonexistent transaction (have you called Begin()?)
OrthancPluginErrorCode_SQLiteCommitWithoutTransaction | SQLite: Committing a nonexistent transaction
OrthancPluginErrorCode_SQLiteRegisterFunction | SQLite: Unable to register a function
OrthancPluginErrorCode_SQLiteFlush | SQLite: Unable to flush the database
OrthancPluginErrorCode_SQLiteCannotRun | SQLite: Cannot run a cached statement
OrthancPluginErrorCode_SQLiteCannotStep | SQLite: Cannot step over a cached statement
OrthancPluginErrorCode_SQLiteBindOutOfRange | SQLite: Bing a value while out of range (serious error)
OrthancPluginErrorCode_SQLitePrepareStatement | SQLite: Cannot prepare a cached statement
OrthancPluginErrorCode_SQLiteTransactionAlreadyStarted | SQLite: Beginning the same transaction twice
OrthancPluginErrorCode_SQLiteTransactionCommit | SQLite: Failure when committing the transaction
OrthancPluginErrorCode_SQLiteTransactionBegin | SQLite: Cannot start a transaction
OrthancPluginErrorCode_DirectoryOverFile | The directory to be created is already occupied by a regular file
OrthancPluginErrorCode_FileStorageCannotWrite | Unable to create a subdirectory or a file in the file storage
OrthancPluginErrorCode_DirectoryExpected | The specified path does not point to a directory
OrthancPluginErrorCode_HttpPortInUse | The TCP port of the HTTP server is privileged or already in use
OrthancPluginErrorCode_DicomPortInUse | The TCP port of the DICOM server is privileged or already in use
OrthancPluginErrorCode_BadHttpStatusInRest | This HTTP status is not allowed in a REST API
OrthancPluginErrorCode_RegularFileExpected | The specified path does not point to a regular file
OrthancPluginErrorCode_PathToExecutable | Unable to get the path to the executable
OrthancPluginErrorCode_MakeDirectory | Cannot create a directory
OrthancPluginErrorCode_BadApplicationEntityTitle | An application entity title (AET) cannot be empty or be longer than 16 characters
OrthancPluginErrorCode_NoCFindHandler | No request handler factory for DICOM C-FIND SCP
OrthancPluginErrorCode_NoCMoveHandler | No request handler factory for DICOM C-MOVE SCP
OrthancPluginErrorCode_NoCStoreHandler | No request handler factory for DICOM C-STORE SCP
OrthancPluginErrorCode_NoApplicationEntityFilter | No application entity filter
OrthancPluginErrorCode_NoSopClassOrInstance | DicomUserConnection: Unable to find the SOP class and instance
OrthancPluginErrorCode_NoPresentationContext | DicomUserConnection: No acceptable presentation context for modality
OrthancPluginErrorCode_DicomFindUnavailable | DicomUserConnection: The C-FIND command is not supported by the remote SCP
OrthancPluginErrorCode_DicomMoveUnavailable | DicomUserConnection: The C-MOVE command is not supported by the remote SCP
OrthancPluginErrorCode_CannotStoreInstance | Cannot store an instance
OrthancPluginErrorCode_CreateDicomNotString | Only string values are supported when creating DICOM instances
OrthancPluginErrorCode_CreateDicomOverrideTag | Trying to override a value inherited from a parent module
OrthancPluginErrorCode_CreateDicomUseContent | Use "Content" to inject an image into a new DICOM instance
OrthancPluginErrorCode_CreateDicomNoPayload | No payload is present for one instance in the series
OrthancPluginErrorCode_CreateDicomUseDataUriScheme | The payload of the DICOM instance must be specified according to Data URI scheme
OrthancPluginErrorCode_CreateDicomBadParent | Trying to attach a new DICOM instance to an inexistent resource
OrthancPluginErrorCode_CreateDicomParentIsInstance | Trying to attach a new DICOM instance to an instance (must be a series, study or patient)
OrthancPluginErrorCode_CreateDicomParentEncoding | Unable to get the encoding of the parent resource
OrthancPluginErrorCode_UnknownModality | Unknown modality
OrthancPluginErrorCode_BadJobOrdering | Bad ordering of filters in a job
OrthancPluginErrorCode_JsonToLuaTable | Cannot convert the given JSON object to a Lua table
OrthancPluginErrorCode_CannotCreateLua | Cannot create the Lua context
OrthancPluginErrorCode_CannotExecuteLua | Cannot execute a Lua command
OrthancPluginErrorCode_LuaAlreadyExecuted | Arguments cannot be pushed after the Lua function is executed
OrthancPluginErrorCode_LuaBadOutput | The Lua function does not give the expected number of outputs
OrthancPluginErrorCode_NotLuaPredicate | The Lua function is not a predicate (only true/false outputs allowed)
OrthancPluginErrorCode_LuaReturnsNoString | The Lua function does not return a string
OrthancPluginErrorCode_StorageAreaAlreadyRegistered | Another plugin has already registered a custom storage area
OrthancPluginErrorCode_DatabaseBackendAlreadyRegistered | Another plugin has already registered a custom database back-end
OrthancPluginErrorCode_DatabaseNotInitialized | Plugin trying to call the database during its initialization
OrthancPluginErrorCode_SslDisabled | Orthanc has been built without SSL support
OrthancPluginErrorCode_CannotOrderSlices | Unable to order the slices of the series
OrthancPluginErrorCode_NoWorklistHandler | No request handler factory for DICOM C-Find Modality SCP
OrthancPluginErrorCode_AlreadyExistingTag | Cannot override the value of a tag that already exists

## ◆ OrthancPluginHttpMethod

enum OrthancPluginHttpMethod

The various HTTP methods for a REST call.

Enumerator
OrthancPluginHttpMethod_Get | GET request
OrthancPluginHttpMethod_Post | POST request
OrthancPluginHttpMethod_Put | PUT request
OrthancPluginHttpMethod_Delete | DELETE request

## ◆ OrthancPluginIdentifierConstraint

enum OrthancPluginIdentifierConstraint

The constraints on the DICOM identifiers that must be supported by the database plugins.

Enumerator
OrthancPluginIdentifierConstraint_Equal | Equal
OrthancPluginIdentifierConstraint_SmallerOrEqual | Less or equal
OrthancPluginIdentifierConstraint_GreaterOrEqual | More or equal
OrthancPluginIdentifierConstraint_Wildcard | Case-sensitive wildcard matching (with * and ?)

## ◆ OrthancPluginInstanceOrigin

enum OrthancPluginInstanceOrigin

The origin of a DICOM instance that has been received by Orthanc.

Enumerator
OrthancPluginInstanceOrigin_Unknown | Unknown origin
OrthancPluginInstanceOrigin_DicomProtocol | Instance received through DICOM protocol
OrthancPluginInstanceOrigin_RestApi | Instance received through REST API of Orthanc
OrthancPluginInstanceOrigin_Plugin | Instance added to Orthanc by a plugin
OrthancPluginInstanceOrigin_Lua | Instance added to Orthanc by a Lua script

## ◆ OrthancPluginResourceType

enum OrthancPluginResourceType

The supported types of DICOM resources.

Enumerator
OrthancPluginResourceType_Patient | Patient
OrthancPluginResourceType_Study | Study
OrthancPluginResourceType_Series | Series
OrthancPluginResourceType_Instance | Instance
OrthancPluginResourceType_None | Unavailable resource type

## ◆ OrthancPluginValueRepresentation

enum OrthancPluginValueRepresentation

The value representations present in the DICOM standard (version 2013).

Enumerator
OrthancPluginValueRepresentation_AE | Application Entity
OrthancPluginValueRepresentation_AS | Age String
OrthancPluginValueRepresentation_AT | Attribute Tag
OrthancPluginValueRepresentation_CS | Code String
OrthancPluginValueRepresentation_DA | Date
OrthancPluginValueRepresentation_DS | Decimal String
OrthancPluginValueRepresentation_DT | Date Time
OrthancPluginValueRepresentation_FD | Floating Point Double
OrthancPluginValueRepresentation_FL | Floating Point Single
OrthancPluginValueRepresentation_IS | Integer String
OrthancPluginValueRepresentation_LO | Long String
OrthancPluginValueRepresentation_LT | Long Text
OrthancPluginValueRepresentation_OB | Other Byte String
OrthancPluginValueRepresentation_OF | Other Float String
OrthancPluginValueRepresentation_OW | Other Word String
OrthancPluginValueRepresentation_PN | Person Name
OrthancPluginValueRepresentation_SH | Short String
OrthancPluginValueRepresentation_SL | Signed Long
OrthancPluginValueRepresentation_SQ | Sequence of Items
OrthancPluginValueRepresentation_SS | Signed Short
OrthancPluginValueRepresentation_ST | Short Text
OrthancPluginValueRepresentation_TM | Time
OrthancPluginValueRepresentation_UI | Unique Identifier (UID)
OrthancPluginValueRepresentation_UL | Unsigned Long
OrthancPluginValueRepresentation_UN | Unknown
OrthancPluginValueRepresentation_US | Unsigned Short
OrthancPluginValueRepresentation_UT | Unlimited Text

## Function Documentation

## ◆ OrthancPluginComputeMd5()

char* OrthancPluginComputeMd5 | ( | OrthancPluginContext * | context,
|  | const void * | buffer,
|  | uint32_t | size
| ) |  |

This functions computes the MD5 cryptographic hash of the given memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | The source memory buffer.
  size | The size in bytes of the source buffer.

Returns
  The NULL value in case of error, or a string containing the cryptographic hash. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginComputeSha1()

char* OrthancPluginComputeSha1 | ( | OrthancPluginContext * | context,
|  | const void * | buffer,
|  | uint32_t | size
| ) |  |

This functions computes the SHA-1 cryptographic hash of the given memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | The source memory buffer.
  size | The size in bytes of the source buffer.

Returns
  The NULL value in case of error, or a string containing the cryptographic hash. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginCreateDicom()

OrthancPluginErrorCode OrthancPluginCreateDicom | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const char * | json,
|  | const OrthancPluginImage * | pixelData,
|  | OrthancPluginCreateDicomFlags | flags
| ) |  |

This function takes as input a string containing a JSON file describing the content of a DICOM instance. As an output, it writes the corresponding DICOM instance to a newly allocated memory buffer. Additionally, an image to be encoded within the DICOM instance can also be provided.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  json | The input JSON file.
  pixelData | The image. Can be NULL, if the pixel data is encoded inside the JSON with the data URI scheme.
  flags | Flags governing the output.

Returns
  0 if success, other value if error.

See also
  OrthancPluginDicomBufferToJson

## ◆ OrthancPluginCreateFindMatcher()

OrthancPluginFindMatcher* OrthancPluginCreateFindMatcher | ( | OrthancPluginContext * | context,
|  | const void * | query,
|  | uint32_t | size
| ) |  |

This function creates a "matcher" object that can be used to check whether a DICOM instance matches a C-Find query. The C-Find query must be expressed as a DICOM buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  query | The C-Find DICOM query.
  size | The size of the DICOM query.

Returns
  The newly allocated matcher. It must be freed with OrthancPluginFreeFindMatcher().

## ◆ OrthancPluginDicomBufferToJson()

char* OrthancPluginDicomBufferToJson | ( | OrthancPluginContext * | context,
|  | const void * | buffer,
|  | uint32_t | size,
|  | OrthancPluginDicomToJsonFormat | format,
|  | OrthancPluginDicomToJsonFlags | flags,
|  | uint32_t | maxStringLength
| ) |  |

This function takes as input a memory buffer containing a DICOM file, and outputs a JSON string representing the tags of this DICOM file.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | The memory buffer containing the DICOM file.
  size | The size of the memory buffer.
  format | The output format.
  flags | Flags governing the output.
  maxStringLength | The maximum length of a field. Too long fields will be output as "null". The 0 value means no maximum length.

Returns
  The NULL value if the case of an error, or the JSON string. This string must be freed by OrthancPluginFreeString().

See also
  OrthancPluginDicomInstanceToJson

## ◆ OrthancPluginDicomInstanceToJson()

char* OrthancPluginDicomInstanceToJson | ( | OrthancPluginContext * | context,
|  | const char * | instanceId,
|  | OrthancPluginDicomToJsonFormat | format,
|  | OrthancPluginDicomToJsonFlags | flags,
|  | uint32_t | maxStringLength
| ) |  |

This function formats a DICOM instance that is stored in Orthanc, and outputs a JSON string representing the tags of this DICOM instance.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  instanceId | The Orthanc identifier of the instance.
  format | The output format.
  flags | Flags governing the output.
  maxStringLength | The maximum length of a field. Too long fields will be output as "null". The 0 value means no maximum length.

Returns
  The NULL value if the case of an error, or the JSON string. This string must be freed by OrthancPluginFreeString().

See also
  OrthancPluginDicomInstanceToJson

## ◆ OrthancPluginExtendOrthancExplorer()

void OrthancPluginExtendOrthancExplorer | ( | OrthancPluginContext * | context,
|  | const char * | javascript
| ) |  |

Add JavaScript code to customize the default behavior of Orthanc Explorer. This can for instance be used to add new buttons.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  javascript | The custom JavaScript code.

## ◆ OrthancPluginFindAddAnswer()

OrthancPluginErrorCode OrthancPluginFindAddAnswer | ( | OrthancPluginContext * | context,
|  | OrthancPluginFindAnswers * | answers,
|  | const void * | dicom,
|  | uint32_t | size
| ) |  |

This function adds one answer (encoded as a DICOM file) to the set of answers corresponding to some C-Find SCP request that is not related to modality worklists.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  answers | The set of answers.
  dicom | The answer to be added, encoded as a DICOM file.
  size | The size of the DICOM file.

Returns
  0 if success, other value if error.

See also
  OrthancPluginCreateDicom()

## ◆ OrthancPluginFindMarkIncomplete()

OrthancPluginErrorCode OrthancPluginFindMarkIncomplete | ( | OrthancPluginContext * | context,
|  | OrthancPluginFindAnswers * | answers
| ) |  |

This function marks as incomplete the set of answers corresponding to some C-Find SCP request that is not related to modality worklists. This must be used if canceling the handling of a request when too many answers are to be returned.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  answers | The set of answers.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginFindMatcherIsMatch()

int32_t OrthancPluginFindMatcherIsMatch | ( | OrthancPluginContext * | context,
|  | const OrthancPluginFindMatcher * | matcher,
|  | const void * | dicom,
|  | uint32_t | size
| ) |  |

This function checks whether one DICOM instance matches C-Find matcher that was previously allocated using OrthancPluginCreateFindMatcher().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  matcher | The matcher of interest.
  dicom | The DICOM instance to be matched.
  size | The size of the DICOM instance.

Returns
  1 if the DICOM instance matches the query, 0 otherwise.

## ◆ OrthancPluginFreeFindMatcher()

void OrthancPluginFreeFindMatcher | ( | OrthancPluginContext * | context,
|  | OrthancPluginFindMatcher * | matcher
| ) |  |

This function frees a matcher that was created using OrthancPluginCreateFindMatcher().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  matcher | The matcher of interest.

## ◆ OrthancPluginFreeMemoryBuffer()

void OrthancPluginFreeMemoryBuffer | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | buffer
| ) |  |

Free a memory buffer that was allocated by the core system of Orthanc.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | The memory buffer to release.

## ◆ OrthancPluginFreeString()

void OrthancPluginFreeString | ( | OrthancPluginContext * | context,
|  | char * | str
| ) |  |

Free a string that was allocated by the core system of Orthanc.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  str | The string to be freed.

## ◆ OrthancPluginGenerateUuid()

char* OrthancPluginGenerateUuid | ( | OrthancPluginContext * | context | ) |

Generate a random GUID/UUID (globally unique identifier).

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  NULL in the case of an error, or a newly allocated string containing the UUID. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetCommandLineArgument()

char* OrthancPluginGetCommandLineArgument | ( | OrthancPluginContext * | context,
|  | uint32_t | argument
| ) |  |

Get the value of one of the command-line arguments that were used to launch Orthanc. The number of available arguments can be retrieved by OrthancPluginGetCommandLineArgumentsCount().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  argument | The index of the argument.

Returns
  The value of the argument, or NULL in the case of an error. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetCommandLineArgumentsCount()

uint32_t OrthancPluginGetCommandLineArgumentsCount | ( | OrthancPluginContext * | context | ) |

Retrieve the number of command-line arguments that were used to launch Orthanc.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  The number of arguments.

## ◆ OrthancPluginGetConfiguration()

char* OrthancPluginGetConfiguration | ( | OrthancPluginContext * | context | ) |

This function returns the content of the configuration that is used by Orthanc, formatted as a JSON string.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  NULL in the case of an error, or a newly allocated string containing the configuration. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetConfigurationPath()

char* OrthancPluginGetConfigurationPath | ( | OrthancPluginContext * | context | ) |

This function returns the path to the configuration file(s) that was specified when starting Orthanc. Since version 0.9.1, this path can refer to a folder that stores a set of configuration files. This function is deprecated in favor of OrthancPluginGetConfiguration().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  NULL in the case of an error, or a newly allocated string containing the path. This string must be freed by OrthancPluginFreeString().

See also
  OrthancPluginGetConfiguration()

## ◆ OrthancPluginGetErrorDescription()

const char* OrthancPluginGetErrorDescription | ( | OrthancPluginContext * | context,
|  | OrthancPluginErrorCode | error
| ) |  |

This function returns the description of a given error code.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  error | The error code of interest.

Returns
  The error description. This is a statically-allocated string, do not free it.

## ◆ OrthancPluginGetFindQuerySize()

uint32_t OrthancPluginGetFindQuerySize | ( | OrthancPluginContext * | context,
|  | const OrthancPluginFindQuery * | query
| ) |  |

This function returns the number of tags that are contained in the given C-Find query.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  query | The C-Find query.

Returns
  The number of tags.

## ◆ OrthancPluginGetFindQueryTag()

OrthancPluginErrorCode OrthancPluginGetFindQueryTag | ( | OrthancPluginContext * | context,
|  | uint16_t * | group,
|  | uint16_t * | element,
|  | const OrthancPluginFindQuery * | query,
|  | uint32_t | index
| ) |  |

This function returns the group and the element of one DICOM tag in the given C-Find query.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  group | The group of the tag (output).
  element | The element of the tag (output).
  query | The C-Find query.
  index | The index of the tag of interest.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginGetFindQueryTagName()

char* OrthancPluginGetFindQueryTagName | ( | OrthancPluginContext * | context,
|  | const OrthancPluginFindQuery * | query,
|  | uint32_t | index
| ) |  |

This function returns the symbolic name of one DICOM tag in the given C-Find query.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  query | The C-Find query.
  index | The index of the tag of interest.

Returns
  The NULL value in case of error, or a string containing the name of the tag.
  0 if success, other value if error.

## ◆ OrthancPluginGetFindQueryValue()

char* OrthancPluginGetFindQueryValue | ( | OrthancPluginContext * | context,
|  | const OrthancPluginFindQuery * | query,
|  | uint32_t | index
| ) |  |

This function returns the value associated with one tag in the given C-Find query.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  query | The C-Find query.
  index | The index of the tag of interest.

Returns
  The NULL value in case of error, or a string containing the value of the tag.
  0 if success, other value if error.

## ◆ OrthancPluginGetOrthancDirectory()

char* OrthancPluginGetOrthancDirectory | ( | OrthancPluginContext * | context | ) |

This function returns the path to the directory containing the Orthanc executable.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  NULL in the case of an error, or a newly allocated string containing the path. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetOrthancPath()

char* OrthancPluginGetOrthancPath | ( | OrthancPluginContext * | context | ) |

This function returns the path to the Orthanc executable.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  NULL in the case of an error, or a newly allocated string containing the path. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginHttpClient()

OrthancPluginErrorCode OrthancPluginHttpClient | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | answerBody,
|  | OrthancPluginMemoryBuffer * | answerHeaders,
|  | uint16_t * | httpStatus,
|  | OrthancPluginHttpMethod | method,
|  | const char * | url,
|  | uint32_t | headersCount,
|  | const char *const * | headersKeys,
|  | const char *const * | headersValues,
|  | const char * | body,
|  | uint32_t | bodySize,
|  | const char * | username,
|  | const char * | password,
|  | uint32_t | timeout,
|  | const char * | certificateFile,
|  | const char * | certificateKeyFile,
|  | const char * | certificateKeyPassword,
|  | uint8_t | pkcs11
| ) |  |

Make a HTTP call to the given URL. The result to the query is stored into a newly allocated memory buffer. The HTTP request will be done accordingly to the global configuration of Orthanc (in particular, the options "HttpProxy", "HttpTimeout", "HttpsVerifyPeers", "HttpsCACertificates", and "Pkcs11" will be taken into account).

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  answerBody | The target memory buffer (out argument). It must be freed with OrthancPluginFreeMemoryBuffer().
  answerHeaders | The target memory buffer for the HTTP headers in the answers (out argument). The answer headers are formatted as a JSON object (associative array). The buffer must be freed with OrthancPluginFreeMemoryBuffer(). This argument can be set to NULL if the plugin has no interest in the HTTP headers.
  httpStatus | The HTTP status after the execution of the request (out argument).
  method | HTTP method to be used.
  url | The URL of interest.
  headersCount | The number of HTTP headers.
  headersKeys | Array containing the keys of the HTTP headers (can be `NULL` if no header).
  headersValues | Array containing the values of the HTTP headers (can be `NULL` if no header).
  username | The username (can be `NULL` if no password protection).
  password | The password (can be `NULL` if no password protection).
  body | The body of the POST request.
  bodySize | The size of the body.
  timeout | Timeout in seconds (0 for default timeout).
  certificateFile | Path to the client certificate for HTTPS, in PEM format (can be `NULL` if no client certificate or if not using HTTPS).
  certificateKeyFile | Path to the key of the client certificate for HTTPS, in PEM format (can be `NULL` if no client certificate or if not using HTTPS).
  certificateKeyPassword | Password to unlock the key of the client certificate (can be `NULL` if no client certificate or if not using HTTPS).
  pkcs11 | Enable PKCS#11 client authentication for hardware security modules and smart cards.

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

## ◆ OrthancPluginHttpDelete()

OrthancPluginErrorCode OrthancPluginHttpDelete | ( | OrthancPluginContext * | context,
|  | const char * | url,
|  | const char * | username,
|  | const char * | password
| ) |  |

Make a HTTP DELETE call to the given URL. Favor OrthancPluginRestApiDelete() if calling the built-in REST API of the Orthanc instance that hosts this plugin.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  url | The URL of interest.
  username | The username (can be `NULL` if no password protection).
  password | The password (can be `NULL` if no password protection).

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

## ◆ OrthancPluginHttpGet()

OrthancPluginErrorCode OrthancPluginHttpGet | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const char * | url,
|  | const char * | username,
|  | const char * | password
| ) |  |

Make a HTTP GET call to the given URL. The result to the query is stored into a newly allocated memory buffer. Favor OrthancPluginRestApiGet() if calling the built-in REST API of the Orthanc instance that hosts this plugin.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  url | The URL of interest.
  username | The username (can be `NULL` if no password protection).
  password | The password (can be `NULL` if no password protection).

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

## ◆ OrthancPluginHttpPost()

OrthancPluginErrorCode OrthancPluginHttpPost | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const char * | url,
|  | const char * | body,
|  | uint32_t | bodySize,
|  | const char * | username,
|  | const char * | password
| ) |  |

Make a HTTP POST call to the given URL. The result to the query is stored into a newly allocated memory buffer. Favor OrthancPluginRestApiPost() if calling the built-in REST API of the Orthanc instance that hosts this plugin.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  url | The URL of interest.
  body | The content of the body of the request.
  bodySize | The size of the body of the request.
  username | The username (can be `NULL` if no password protection).
  password | The password (can be `NULL` if no password protection).

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

## ◆ OrthancPluginHttpPut()

OrthancPluginErrorCode OrthancPluginHttpPut | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const char * | url,
|  | const char * | body,
|  | uint32_t | bodySize,
|  | const char * | username,
|  | const char * | password
| ) |  |

Make a HTTP PUT call to the given URL. The result to the query is stored into a newly allocated memory buffer. Favor OrthancPluginRestApiPut() if calling the built-in REST API of the Orthanc instance that hosts this plugin.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  url | The URL of interest.
  body | The content of the body of the request.
  bodySize | The size of the body of the request.
  username | The username (can be `NULL` if no password protection).
  password | The password (can be `NULL` if no password protection).

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

## ◆ OrthancPluginLogError()

void OrthancPluginLogError | ( | OrthancPluginContext * | context,
|  | const char * | message
| ) |  |

Log an error message using the Orthanc logging system.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  message | The message to be logged.

## ◆ OrthancPluginLogInfo()

void OrthancPluginLogInfo | ( | OrthancPluginContext * | context,
|  | const char * | message
| ) |  |

Log an information message using the Orthanc logging system.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  message | The message to be logged.

## ◆ OrthancPluginLogWarning()

void OrthancPluginLogWarning | ( | OrthancPluginContext * | context,
|  | const char * | message
| ) |  |

Log a warning message using the Orthanc logging system.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  message | The message to be logged.

## ◆ OrthancPluginLookupDictionary()

OrthancPluginErrorCode OrthancPluginLookupDictionary | ( | OrthancPluginContext * | context,
|  | OrthancPluginDictionaryEntry * | target,
|  | const char * | name
| ) |  |

This functions makes a lookup in the dictionary of DICOM tags that are known to Orthanc, and returns information about this tag. The tag can be specified using its human-readable name (e.g. "PatientName") or a set of two hexadecimal numbers (e.g. "0010-0020").

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | Where to store the information about the tag.
  name | The name of the DICOM tag.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginReadFile()

OrthancPluginErrorCode OrthancPluginReadFile | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const char * | path
| ) |  |

Read the content of a file on the filesystem, and returns it into a newly allocated memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  path | The path of the file to be read.

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

## ◆ OrthancPluginRegisterDictionaryTag()

OrthancPluginErrorCode OrthancPluginRegisterDictionaryTag | ( | OrthancPluginContext * | context,
|  | uint16_t | group,
|  | uint16_t | element,
|  | OrthancPluginValueRepresentation | vr,
|  | const char * | name,
|  | uint32_t | minMultiplicity,
|  | uint32_t | maxMultiplicity
| ) |  |

This function declares a new public tag in the dictionary of DICOM tags that are known to Orthanc. This function should be used in the OrthancPluginInitialize() callback.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  group | The group of the tag.
  element | The element of the tag.
  vr | The value representation of the tag.
  name | The nickname of the tag.
  minMultiplicity | The minimum multiplicity of the tag (must be above 0).
  maxMultiplicity | The maximum multiplicity of the tag. A value of 0 means an arbitrary multiplicity ("<tt>n</tt>").

Returns
  0 if success, other value if error.

See also
  OrthancPluginRegisterPrivateDictionaryTag()

## ◆ OrthancPluginRegisterErrorCode()

OrthancPluginErrorCode OrthancPluginRegisterErrorCode | ( | OrthancPluginContext * | context,
|  | int32_t | code,
|  | uint16_t | httpStatus,
|  | const char * | message
| ) |  |

This function declares a custom error code that can be generated by this plugin. This declaration is used to enrich the body of the HTTP answer in the case of an error, and to set the proper HTTP status code.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  code | The error code that is internal to this plugin.
  httpStatus | The HTTP status corresponding to this error.
  message | The description of the error.

Returns
  The error code that has been assigned inside the Orthanc core.

## ◆ OrthancPluginRegisterFindCallback()

OrthancPluginErrorCode OrthancPluginRegisterFindCallback | ( | OrthancPluginContext * | context,
|  | OrthancPluginFindCallback | callback
| ) |  |

This function registers a callback to handle C-Find SCP requests that are not related to modality worklists.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  callback | The callback.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginRegisterMoveCallback()

OrthancPluginErrorCode OrthancPluginRegisterMoveCallback | ( | OrthancPluginContext * | context,
|  | OrthancPluginMoveCallback | callback,
|  | OrthancPluginGetMoveSize | getMoveSize,
|  | OrthancPluginApplyMove | applyMove,
|  | OrthancPluginFreeMove | freeMove
| ) |  |

This function registers a callback to handle C-Move SCP requests.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  callback | The main callback.
  getMoveSize | Callback to read the number of C-Move suboperations.
  applyMove | Callback to apply one C-Move suboperations.
  freeMove | Callback to free the C-Move driver.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginRegisterPrivateDictionaryTag()

OrthancPluginErrorCode OrthancPluginRegisterPrivateDictionaryTag | ( | OrthancPluginContext * | context,
|  | uint16_t | group,
|  | uint16_t | element,
|  | OrthancPluginValueRepresentation | vr,
|  | const char * | name,
|  | uint32_t | minMultiplicity,
|  | uint32_t | maxMultiplicity,
|  | const char * | privateCreator
| ) |  |

This function declares a new private tag in the dictionary of DICOM tags that are known to Orthanc. This function should be used in the OrthancPluginInitialize() callback.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  group | The group of the tag.
  element | The element of the tag.
  vr | The value representation of the tag.
  name | The nickname of the tag.
  minMultiplicity | The minimum multiplicity of the tag (must be above 0).
  maxMultiplicity | The maximum multiplicity of the tag. A value of 0 means an arbitrary multiplicity ("<tt>n</tt>").
  privateCreator | The private creator of this private tag.

Returns
  0 if success, other value if error.

See also
  OrthancPluginRegisterDictionaryTag()

## ◆ OrthancPluginRegisterWorklistCallback()

OrthancPluginErrorCode OrthancPluginRegisterWorklistCallback | ( | OrthancPluginContext * | context,
|  | OrthancPluginWorklistCallback | callback
| ) |  |

This function registers a callback to handle C-Find SCP requests on modality worklists.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  callback | The callback.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginSetDescription()

void OrthancPluginSetDescription | ( | OrthancPluginContext * | context,
|  | const char * | description
| ) |  |

Set a description for this plugin. It is displayed in the "Plugins" page of Orthanc Explorer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  description | The description.

## ◆ OrthancPluginSetRootUri()

void OrthancPluginSetRootUri | ( | OrthancPluginContext * | context,
|  | const char * | uri
| ) |  |

For plugins that come with a Web interface, this function declares the entry path where to find this interface. This information is notably used in the "Plugins" page of Orthanc Explorer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  uri | The root URI for this plugin.

## ◆ OrthancPluginWorklistAddAnswer()

OrthancPluginErrorCode OrthancPluginWorklistAddAnswer | ( | OrthancPluginContext * | context,
|  | OrthancPluginWorklistAnswers * | answers,
|  | const OrthancPluginWorklistQuery * | query,
|  | const void * | dicom,
|  | uint32_t | size
| ) |  |

This function adds one worklist (encoded as a DICOM file) to the set of answers corresponding to some C-Find SCP request against modality worklists.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  answers | The set of answers.
  query | The worklist query, as received by the callback.
  dicom | The worklist to answer, encoded as a DICOM file.
  size | The size of the DICOM file.

Returns
  0 if success, other value if error.

See also
  OrthancPluginCreateDicom()

## ◆ OrthancPluginWorklistGetDicomQuery()

OrthancPluginErrorCode OrthancPluginWorklistGetDicomQuery | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const OrthancPluginWorklistQuery * | query
| ) |  |

This function retrieves the DICOM file that underlies a C-Find SCP query against modality worklists.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | Memory buffer where to store the DICOM file. It must be freed with OrthancPluginFreeMemoryBuffer().
  query | The worklist query, as received by the callback.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginWorklistIsMatch()

int32_t OrthancPluginWorklistIsMatch | ( | OrthancPluginContext * | context,
|  | const OrthancPluginWorklistQuery * | query,
|  | const void * | dicom,
|  | uint32_t | size
| ) |  |

This function checks whether one worklist (encoded as a DICOM file) matches the C-Find SCP query against modality worklists. This function must be called before adding the worklist as an answer through OrthancPluginWorklistAddAnswer().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  query | The worklist query, as received by the callback.
  dicom | The worklist to answer, encoded as a DICOM file.
  size | The size of the DICOM file.

Returns
  1 if the worklist matches the query, 0 otherwise.

## ◆ OrthancPluginWorklistMarkIncomplete()

OrthancPluginErrorCode OrthancPluginWorklistMarkIncomplete | ( | OrthancPluginContext * | context,
|  | OrthancPluginWorklistAnswers * | answers
| ) |  |

This function marks as incomplete the set of answers corresponding to some C-Find SCP request against modality worklists. This must be used if canceling the handling of a request when too many answers are to be returned.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  answers | The set of answers.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginWriteFile()

OrthancPluginErrorCode OrthancPluginWriteFile | ( | OrthancPluginContext * | context,
|  | const char * | path,
|  | const void * | data,
|  | uint32_t | size
| ) |  |

Write the content of a memory buffer to the filesystem.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  path | The path of the file to be written.
  data | The content of the memory buffer.
  size | The size of the memory buffer.

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