Orthanc Plugin SDK  1.5.2
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 _OrthancPluginFindAnswers_t OrthancPluginFindMatcher
 Opaque structure to an object that can be used to check whether a DICOM instance matches a C-Find query.
 
typedef struct _OrthancPluginPeers_t OrthancPluginPeers
 Opaque structure to the set of remote Orthanc Peers that are known to the local Orthanc server.
 
typedef struct _OrthancPluginJob_t OrthancPluginJob
 Opaque structure to a job to be executed by Orthanc.
 
typedef void(* OrthancPluginFree) (void *buffer)
 Signature of a function to free dynamic memory.
 
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 void(* OrthancPluginJobFinalize) (void *job)
 Callback to finalize one custom job. More...
 
typedef float(* OrthancPluginJobGetProgress) (void *job)
 Callback to check the progress of one custom job. More...
 
typedef const char *(* OrthancPluginJobGetContent) (void *job)
 Callback to retrieve the content of one custom job. More...
 
typedef const char *(* OrthancPluginJobGetSerialized) (void *job)
 Callback to serialize one custom job. More...
 
typedef OrthancPluginJobStepStatus(* OrthancPluginJobStep) (void *job)
 Callback to execute one step of a custom job. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginJobStop) (void *job, OrthancPluginJobStopReason reason)
 Callback executed once one custom job leaves the "running" state. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginJobReset) (void *job)
 Callback executed once one stopped custom job is started again. 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_DatabaseUnavailable,
  OrthancPluginErrorCode_CanceledJob,
  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  OrthancPluginConstraintType {
  OrthancPluginConstraintType_Equal,
  OrthancPluginConstraintType_SmallerOrEqual,
  OrthancPluginConstraintType_GreaterOrEqual,
  OrthancPluginConstraintType_Wildcard,
  OrthancPluginConstraintType_List
}
 
enum  OrthancPluginInstanceOrigin {
  OrthancPluginInstanceOrigin_Unknown,
  OrthancPluginInstanceOrigin_DicomProtocol,
  OrthancPluginInstanceOrigin_RestApi,
  OrthancPluginInstanceOrigin_Plugin,
  OrthancPluginInstanceOrigin_Lua
}
 
enum  OrthancPluginJobStepStatus {
  OrthancPluginJobStepStatus_Success,
  OrthancPluginJobStepStatus_Failure,
  OrthancPluginJobStepStatus_Continue
}
 
enum  OrthancPluginJobStopReason {
  OrthancPluginJobStopReason_Success,
  OrthancPluginJobStopReason_Paused,
  OrthancPluginJobStopReason_Failure,
  OrthancPluginJobStopReason_Canceled
}
 

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 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...
 
OrthancPluginFindMatcherOrthancPluginCreateFindMatcher (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...
 
OrthancPluginPeersOrthancPluginGetPeers (OrthancPluginContext *context)
 Return the list of available Orthanc peers. More...
 
void OrthancPluginFreePeers (OrthancPluginContext *context, OrthancPluginPeers *peers)
 Free the list of available Orthanc peers. More...
 
uint32_t OrthancPluginGetPeersCount (OrthancPluginContext *context, const OrthancPluginPeers *peers)
 Get the number of Orthanc peers. More...
 
const char * OrthancPluginGetPeerName (OrthancPluginContext *context, const OrthancPluginPeers *peers, uint32_t peerIndex)
 Get the symbolic name of an Orthanc peer. More...
 
const char * OrthancPluginGetPeerUrl (OrthancPluginContext *context, const OrthancPluginPeers *peers, uint32_t peerIndex)
 Get the base URL of an Orthanc peer. More...
 
const char * OrthancPluginGetPeerUserProperty (OrthancPluginContext *context, const OrthancPluginPeers *peers, uint32_t peerIndex, const char *userProperty)
 Get some user-defined property of an Orthanc peer. More...
 
OrthancPluginErrorCode OrthancPluginCallPeerApi (OrthancPluginContext *context, OrthancPluginMemoryBuffer *answerBody, OrthancPluginMemoryBuffer *answerHeaders, uint16_t *httpStatus, const OrthancPluginPeers *peers, uint32_t peerIndex, OrthancPluginHttpMethod method, const char *uri, uint32_t additionalHeadersCount, const char *const *additionalHeadersKeys, const char *const *additionalHeadersValues, const char *body, uint32_t bodySize, uint32_t timeout)
 Call the REST API of an Orthanc peer. More...
 
OrthancPluginJobOrthancPluginCreateJob (OrthancPluginContext *context, void *job, OrthancPluginJobFinalize finalize, const char *type, OrthancPluginJobGetProgress getProgress, OrthancPluginJobGetContent getContent, OrthancPluginJobGetSerialized getSerialized, OrthancPluginJobStep step, OrthancPluginJobStop stop, OrthancPluginJobReset reset)
 Create a custom job. More...
 
void OrthancPluginFreeJob (OrthancPluginContext *context, OrthancPluginJob *job)
 Free a custom job. More...
 
char * OrthancPluginSubmitJob (OrthancPluginContext *context, OrthancPluginJob *job, int priority)
 Submit a new job to the jobs engine of Orthanc. More...
 
const char * OrthancPluginAutodetectMimeType (OrthancPluginContext *context, const char *path)
 Detect the MIME type of a file. More...
 

Detailed Description

Typedef Documentation

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
methodThe HTTP method used by the request.
uriThe URI of interest.
ipThe IP address of the HTTP client.
headersCountThe number of HTTP headers.
headersKeysThe keys of the HTTP headers (always converted to low-case).
headersValuesThe values of the HTTP headers.
Returns
0 if forbidden access, 1 if allowed access, -1 if error.
Deprecated:
Please instead use 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
methodThe HTTP method used by the request.
uriThe URI of interest.
ipThe IP address of the HTTP client.
headersCountThe number of HTTP headers.
headersKeysThe keys of the HTTP headers (always converted to low-case).
headersValuesThe values of the HTTP headers.
getArgumentsCountThe number of GET arguments (only for the GET HTTP method).
getArgumentsKeysThe keys of the GET arguments (only for the GET HTTP method).
getArgumentsValuesThe values of the GET arguments (only for the GET HTTP method).
Returns
0 if forbidden access, 1 if allowed access, -1 if error.
typedef void(* OrthancPluginJobFinalize) (void *job)

Signature of a callback function that releases all the resources allocated by the given job. This job is the argument provided to OrthancPluginCreateJob().

Parameters
jobThe job of interest.
typedef const char*(* OrthancPluginJobGetContent) (void *job)

Signature of a callback function that returns human-readable statistics about the job. This statistics must be formatted as a JSON object. This information is notably displayed in the "Jobs" tab of "Orthanc Explorer".

Parameters
jobThe job of interest.
Returns
The statistics, as a JSON object encoded as a string.
typedef float(* OrthancPluginJobGetProgress) (void *job)

Signature of a callback function that returns the progress of the job.

Parameters
jobThe job of interest.
Returns
The progress, as a floating-point number ranging from 0 to 1.
typedef const char*(* OrthancPluginJobGetSerialized) (void *job)

Signature of a callback function that returns a serialized version of the job, formatted as a JSON object. This serialization is stored in the Orthanc database, and is used to reload the job on the restart of Orthanc. The "unserialization" callback (with OrthancPluginJobsUnserializer signature) will receive this serialized object.

Parameters
jobThe job of interest.
Returns
The serialized job, as a JSON object encoded as a string.
See also
OrthancPluginRegisterJobsUnserializer()
typedef OrthancPluginErrorCode(* OrthancPluginJobReset) (void *job)

Signature of a callback function that is invoked once a job leaves the "failure/canceled" state, to be started again. This function will typically reset the progress to zero. Note that before being actually executed, the job would first be tagged as "pending" in the Orthanc jobs engine.

Parameters
jobThe job of interest.
Returns
0 if success, or the error code if failure.
typedef OrthancPluginJobStepStatus(* OrthancPluginJobStep) (void *job)

Signature of a callback function that executes one step in the job. The jobs engine of Orthanc will make successive calls to this method, as long as it returns OrthancPluginJobStepStatus_Continue.

Parameters
jobThe job of interest.
Returns
The status of execution.
typedef OrthancPluginErrorCode(* OrthancPluginJobStop) (void *job, OrthancPluginJobStopReason reason)

Signature of a callback function that is invoked once a job leaves the "running" state. This can happen if the previous call to OrthancPluginJobStep has failed/succeeded, if the host Orthanc server is being stopped, or if the user manually tags the job as paused/canceled. This callback allows the plugin to free resources allocated for running this custom job (e.g. to stop threads, or to remove temporary files).

Note that handling pauses might involves a specific treatment (such a stopping threads, but keeping temporary files on the disk). This "paused" situation can be checked by looking at the "reason" parameter.

Parameters
jobThe job of interest.
reasonThe reason for leaving the "running" state.
Returns
0 if success, or the error code if failure.

Enumeration Type Documentation

The constraints on the tags (main DICOM tags and identifier tags) that must be supported by the database plugins.

Enumerator
OrthancPluginConstraintType_Equal 

Equal

OrthancPluginConstraintType_SmallerOrEqual 

Less or equal

OrthancPluginConstraintType_GreaterOrEqual 

More or equal

OrthancPluginConstraintType_Wildcard 

Wildcard matching

OrthancPluginConstraintType_List 

List of values

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

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

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

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

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_DatabaseUnavailable 

The database is currently not available (probably a transient situation)

OrthancPluginErrorCode_CanceledJob 

This job was canceled

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

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

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

Deprecated:
Plugins using OrthancPluginConstraintType will be faster
Enumerator
OrthancPluginIdentifierConstraint_Equal 

Equal

OrthancPluginIdentifierConstraint_SmallerOrEqual 

Less or equal

OrthancPluginIdentifierConstraint_GreaterOrEqual 

More or equal

OrthancPluginIdentifierConstraint_Wildcard 

Case-sensitive wildcard matching (with * and ?)

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

The possible status for one single step of a job.

Enumerator
OrthancPluginJobStepStatus_Success 

The job has successfully executed all its steps

OrthancPluginJobStepStatus_Failure 

The job has failed while executing this step

OrthancPluginJobStepStatus_Continue 

The job has still data to process after this step

Explains why the job should stop and release the resources it has allocated. This is especially important to disambiguate between the "paused" condition and the "final" conditions (success, failure, or canceled).

Enumerator
OrthancPluginJobStopReason_Success 

The job has succeeded

OrthancPluginJobStopReason_Paused 

The job was paused, and will be resumed later

OrthancPluginJobStopReason_Failure 

The job has failed, and might be resubmitted later

OrthancPluginJobStopReason_Canceled 

The job was canceled, and might be resubmitted later

The supported types of DICOM resources.

Enumerator
OrthancPluginResourceType_Patient 

Patient

OrthancPluginResourceType_Study 

Study

OrthancPluginResourceType_Series 

Series

OrthancPluginResourceType_Instance 

Instance

OrthancPluginResourceType_None 

Unavailable resource type

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

const char* OrthancPluginAutodetectMimeType ( OrthancPluginContext context,
const char *  path 
)

This function returns the MIME type of a file by inspecting its extension.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
pathPath to the file.
Returns
The MIME type. This is a statically-allocated string, do not free it.
OrthancPluginErrorCode OrthancPluginCallPeerApi ( OrthancPluginContext context,
OrthancPluginMemoryBuffer answerBody,
OrthancPluginMemoryBuffer answerHeaders,
uint16_t *  httpStatus,
const OrthancPluginPeers peers,
uint32_t  peerIndex,
OrthancPluginHttpMethod  method,
const char *  uri,
uint32_t  additionalHeadersCount,
const char *const *  additionalHeadersKeys,
const char *const *  additionalHeadersValues,
const char *  body,
uint32_t  bodySize,
uint32_t  timeout 
)

Make a REST call to the given URI in the REST API of a remote Orthanc peer. The result to the query is stored into a newly allocated memory buffer. The HTTP request will be done according to the "OrthancPeers" configuration option of Orthanc.

This function is thread-safe: Several threads sharing the same OrthancPluginPeers object can simultaneously call this function.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
answerBodyThe target memory buffer (out argument). It must be freed with OrthancPluginFreeMemoryBuffer().
answerHeadersThe 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.
httpStatusThe HTTP status after the execution of the request (out argument).
peersThe data structure describing the Orthanc peers.
peerIndexThe index of the peer of interest. This value must be lower than OrthancPluginGetPeersCount().
methodHTTP method to be used.
uriThe URI of interest in the REST API.
additionalHeadersCountThe number of HTTP headers to be added to the HTTP headers provided in the global configuration of Orthanc.
additionalHeadersKeysArray containing the keys of the HTTP headers (can be NULL if no header).
additionalHeadersValuesArray containing the values of the HTTP headers (can be NULL if no header).
bodyThe HTTP body for a POST or PUT request.
bodySizeThe size of the body.
timeoutTimeout in seconds (0 for default timeout).
Returns
0 if success, or the error code if failure.
See also
OrthancPluginHttpClient()
char* OrthancPluginComputeMd5 ( OrthancPluginContext context,
const void *  buffer,
uint32_t  size 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
bufferThe source memory buffer.
sizeThe 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().
char* OrthancPluginComputeSha1 ( OrthancPluginContext context,
const void *  buffer,
uint32_t  size 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
bufferThe source memory buffer.
sizeThe 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().
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
jsonThe input JSON file.
pixelDataThe image. Can be NULL, if the pixel data is encoded inside the JSON with the data URI scheme.
flagsFlags governing the output.
Returns
0 if success, other value if error.
See also
OrthancPluginDicomBufferToJson
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
queryThe C-Find DICOM query.
sizeThe size of the DICOM query.
Returns
The newly allocated matcher. It must be freed with OrthancPluginFreeFindMatcher().
OrthancPluginJob* OrthancPluginCreateJob ( OrthancPluginContext context,
void *  job,
OrthancPluginJobFinalize  finalize,
const char *  type,
OrthancPluginJobGetProgress  getProgress,
OrthancPluginJobGetContent  getContent,
OrthancPluginJobGetSerialized  getSerialized,
OrthancPluginJobStep  step,
OrthancPluginJobStop  stop,
OrthancPluginJobReset  reset 
)

This function creates a custom job to be run by the jobs engine of Orthanc.

Orthanc starts one dedicated thread per custom job that is running. It is guaranteed that all the callbacks will only be called from this single dedicated thread, in mutual exclusion: As a consequence, it is not mandatory to protect the various callbacks by mutexes.

The custom job can nonetheless launch its own processing threads on the first call to the "step()" callback, and stop them once the "stop()" callback is called.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
jobThe job to be executed.
finalizeThe finalization callback.
typeThe type of the job, provided to the job unserializer. See OrthancPluginRegisterJobsUnserializer().
getProgressThe progress callback.
getContentThe content callback.
getSerializedThe serialization callback.
stepThe callback to execute the individual steps of the job.
stopThe callback that is invoked once the job leaves the "running" state.
resetThe callback that is invoked if a stopped job is started again.
Returns
The newly allocated job. It must be freed with OrthancPluginFreeJob(), as long as it is not submitted with OrthancPluginSubmitJob().
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
bufferThe memory buffer containing the DICOM file.
sizeThe size of the memory buffer.
formatThe output format.
flagsFlags governing the output.
maxStringLengthThe 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
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceIdThe Orthanc identifier of the instance.
formatThe output format.
flagsFlags governing the output.
maxStringLengthThe 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
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
javascriptThe custom JavaScript code.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
matcherThe matcher of interest.
dicomThe DICOM instance to be matched.
sizeThe size of the DICOM instance.
Returns
1 if the DICOM instance matches the query, 0 otherwise.
void OrthancPluginFreeFindMatcher ( OrthancPluginContext context,
OrthancPluginFindMatcher matcher 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
matcherThe matcher of interest.
void OrthancPluginFreeJob ( OrthancPluginContext context,
OrthancPluginJob job 
)

This function frees an image that was created with OrthancPluginCreateJob().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
jobThe job.
void OrthancPluginFreeMemoryBuffer ( OrthancPluginContext context,
OrthancPluginMemoryBuffer buffer 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
bufferThe memory buffer to release.
void OrthancPluginFreePeers ( OrthancPluginContext context,
OrthancPluginPeers peers 
)

This function frees the data structure returned by OrthancPluginGetPeers().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
peersThe data structure describing the Orthanc peers.
void OrthancPluginFreeString ( OrthancPluginContext context,
char *  str 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
strThe string to be freed.
char* OrthancPluginGenerateUuid ( OrthancPluginContext context)

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

Parameters
contextThe 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().
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
argumentThe 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().
uint32_t OrthancPluginGetCommandLineArgumentsCount ( OrthancPluginContext context)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
Returns
The number of arguments.
char* OrthancPluginGetConfiguration ( OrthancPluginContext context)

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

Parameters
contextThe 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().
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
contextThe 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()
const char* OrthancPluginGetErrorDescription ( OrthancPluginContext context,
OrthancPluginErrorCode  error 
)

This function returns the description of a given error code.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
errorThe error code of interest.
Returns
The error description. This is a statically-allocated string, do not free it.
char* OrthancPluginGetOrthancDirectory ( OrthancPluginContext context)

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

Parameters
contextThe 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().
char* OrthancPluginGetOrthancPath ( OrthancPluginContext context)

This function returns the path to the Orthanc executable.

Parameters
contextThe 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().
const char* OrthancPluginGetPeerName ( OrthancPluginContext context,
const OrthancPluginPeers peers,
uint32_t  peerIndex 
)

This function returns the symbolic name of the Orthanc peer, which corresponds to the key of the "OrthancPeers" configuration option of Orthanc.

This function is thread-safe: Several threads sharing the same OrthancPluginPeers object can simultaneously call this function.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
peersThe data structure describing the Orthanc peers.
peerIndexThe index of the peer of interest. This value must be lower than OrthancPluginGetPeersCount().
Returns
The symbolic name, or NULL in the case of an error.
OrthancPluginPeers* OrthancPluginGetPeers ( OrthancPluginContext context)

This function returns the parameters of the Orthanc peers that are known to the Orthanc server hosting the plugin.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
Returns
NULL if error, or a newly allocated opaque data structure containing the peers. This structure must be freed with OrthancPluginFreePeers().
uint32_t OrthancPluginGetPeersCount ( OrthancPluginContext context,
const OrthancPluginPeers peers 
)

This function returns the number of Orthanc peers.

This function is thread-safe: Several threads sharing the same OrthancPluginPeers object can simultaneously call this function.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
peersThe data structure describing the Orthanc peers.
Returns
The number of peers.
const char* OrthancPluginGetPeerUrl ( OrthancPluginContext context,
const OrthancPluginPeers peers,
uint32_t  peerIndex 
)

This function returns the base URL to the REST API of some Orthanc peer.

This function is thread-safe: Several threads sharing the same OrthancPluginPeers object can simultaneously call this function.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
peersThe data structure describing the Orthanc peers.
peerIndexThe index of the peer of interest. This value must be lower than OrthancPluginGetPeersCount().
Returns
The URL, or NULL in the case of an error.
const char* OrthancPluginGetPeerUserProperty ( OrthancPluginContext context,
const OrthancPluginPeers peers,
uint32_t  peerIndex,
const char *  userProperty 
)

This function returns some user-defined property of some Orthanc peer. An user-defined property is a property that is associated with the peer in the Orthanc configuration file, but that is not recognized by the Orthanc core.

This function is thread-safe: Several threads sharing the same OrthancPluginPeers object can simultaneously call this function.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
peersThe data structure describing the Orthanc peers.
peerIndexThe index of the peer of interest. This value must be lower than OrthancPluginGetPeersCount().
userPropertyThe user property of interest.
Returns
The value of the user property, or NULL if it is not defined.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
answerBodyThe target memory buffer (out argument). It must be freed with OrthancPluginFreeMemoryBuffer().
answerHeadersThe 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.
httpStatusThe HTTP status after the execution of the request (out argument).
methodHTTP method to be used.
urlThe URL of interest.
headersCountThe number of HTTP headers.
headersKeysArray containing the keys of the HTTP headers (can be NULL if no header).
headersValuesArray containing the values of the HTTP headers (can be NULL if no header).
usernameThe username (can be NULL if no password protection).
passwordThe password (can be NULL if no password protection).
bodyThe HTTP body for a POST or PUT request.
bodySizeThe size of the body.
timeoutTimeout in seconds (0 for default timeout).
certificateFilePath to the client certificate for HTTPS, in PEM format (can be NULL if no client certificate or if not using HTTPS).
certificateKeyFilePath to the key of the client certificate for HTTPS, in PEM format (can be NULL if no client certificate or if not using HTTPS).
certificateKeyPasswordPassword to unlock the key of the client certificate (can be NULL if no client certificate or if not using HTTPS).
pkcs11Enable PKCS#11 client authentication for hardware security modules and smart cards.
Returns
0 if success, or the error code if failure.
See also
OrthancPluginCallPeerApi()
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
urlThe URL of interest.
usernameThe username (can be NULL if no password protection).
passwordThe password (can be NULL if no password protection).
Returns
0 if success, or the error code if failure.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
urlThe URL of interest.
usernameThe username (can be NULL if no password protection).
passwordThe password (can be NULL if no password protection).
Returns
0 if success, or the error code if failure.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
urlThe URL of interest.
bodyThe content of the body of the request.
bodySizeThe size of the body of the request.
usernameThe username (can be NULL if no password protection).
passwordThe password (can be NULL if no password protection).
Returns
0 if success, or the error code if failure.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
urlThe URL of interest.
bodyThe content of the body of the request.
bodySizeThe size of the body of the request.
usernameThe username (can be NULL if no password protection).
passwordThe password (can be NULL if no password protection).
Returns
0 if success, or the error code if failure.
void OrthancPluginLogError ( OrthancPluginContext context,
const char *  message 
)

Log an error message using the Orthanc logging system.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
messageThe message to be logged.
void OrthancPluginLogInfo ( OrthancPluginContext context,
const char *  message 
)

Log an information message using the Orthanc logging system.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
messageThe message to be logged.
void OrthancPluginLogWarning ( OrthancPluginContext context,
const char *  message 
)

Log a warning message using the Orthanc logging system.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
messageThe message to be logged.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetWhere to store the information about the tag.
nameThe name of the DICOM tag.
Returns
0 if success, other value if error.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
pathThe path of the file to be read.
Returns
0 if success, or the error code if failure.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
groupThe group of the tag.
elementThe element of the tag.
vrThe value representation of the tag.
nameThe nickname of the tag.
minMultiplicityThe minimum multiplicity of the tag (must be above 0).
maxMultiplicityThe 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()
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
codeThe error code that is internal to this plugin.
httpStatusThe HTTP status corresponding to this error.
messageThe description of the error.
Returns
The error code that has been assigned inside the Orthanc core.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
groupThe group of the tag.
elementThe element of the tag.
vrThe value representation of the tag.
nameThe nickname of the tag.
minMultiplicityThe minimum multiplicity of the tag (must be above 0).
maxMultiplicityThe maximum multiplicity of the tag. A value of 0 means an arbitrary multiplicity ("<tt>n</tt>").
privateCreatorThe private creator of this private tag.
Returns
0 if success, other value if error.
See also
OrthancPluginRegisterDictionaryTag()
void OrthancPluginSetDescription ( OrthancPluginContext context,
const char *  description 
)

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

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
descriptionThe description.
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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
uriThe root URI for this plugin.
char* OrthancPluginSubmitJob ( OrthancPluginContext context,
OrthancPluginJob job,
int  priority 
)

This function adds the given job to the pending jobs of Orthanc. Orthanc will take take of freeing it by invoking the finalization callback provided to OrthancPluginCreateJob().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
jobThe job, as received by OrthancPluginCreateJob().
priorityThe priority of the job.
Returns
ID of the newly-submitted job. This string must be freed by OrthancPluginFreeString().
OrthancPluginErrorCode OrthancPluginWriteFile ( OrthancPluginContext context,
const char *  path,
const void *  data,
uint32_t  size 
)

Write the content of a memory buffer to the filesystem.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
pathThe path of the file to be written.
dataThe content of the memory buffer.
sizeThe size of the memory buffer.
Returns
0 if success, or the error code if failure.