orthanc: Plugins/OrthancCPlugin/OrthancCPlugin.h comparison

comparison Plugins/OrthancCPlugin/OrthancCPlugin.h @ 907:9b8298234254 plugins

documentation

author	Sebastien Jodogne <s.jodogne@gmail.com>
date	Thu, 19 Jun 2014 14:28:43 +0200
parents	cbc0ea03dffe
children	e078ea944089

comparison

equal deleted inserted replaced

-:cbc0ea03dffe
+:9b8298234254
 /**
 * \mainpage
 *
-* This SDK allows external developers to create plugins that can be
+* This C/C++ SDK allows external developers to create plugins that
-* loaded into Orthanc to extend its functionality. Each Orthanc
+* can be loaded into Orthanc to extend its functionality. Each
-* plugin must expose 4 public functions with the following
+* Orthanc plugin must expose 4 public functions with the following
 * signatures:
 *
-* - <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext*)</tt>:
+* -# <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext* context)</tt>:
-*   This function is invoked by Orthanc
+*    This function is invoked by Orthanc when it loads the plugin on startup.
-* - <tt>void OrthancPluginFinalize()</tt>
+*    The plugin must store the context pointer so that it can use the plugin
-* - <tt>const char* OrthancPluginGetName()</tt>
+*    services of Orthanc. It must also register all its callbacks using
-* - <tt>const char* OrthancPluginGetVersion()</tt>
+*    ::OrthancPluginRegisterRestCallback().
+* -# <tt>void OrthancPluginFinalize()</tt>:
+*    This function is invoked by Orthanc during its shutdown. The plugin
+*    must free all its memory.
+* -# <tt>const char* OrthancPluginGetName()</tt>:
+*    The plugin must return a short string to identify itself.
+* -# <tt>const char* OrthancPluginGetVersion()</tt>
+*    The plugin must return a string containing its version number.
+*
+* The name and the version of a plugin is only used to prevent it
+* from being loaded twice.
+*
+*
 **/
 /**
 #endif
 /********************************************************************
-** Inclusion of standard libaries.
+** Inclusion of standard libraries.
 ********************************************************************/
 #ifdef _MSC_VER
 #include "../../Resources/VisualStudio/stdint.h"
 #else
 #ifdef __cplusplus
 extern "C"
 {
 #endif
+/**
+* The various HTTP methods for a REST call.
+**/
 typedef enum
 {
-OrthancPluginHttpMethod_Get = 1,
+OrthancPluginHttpMethod_Get = 1,    /*!< GET request */
-OrthancPluginHttpMethod_Post = 2,
+OrthancPluginHttpMethod_Post = 2,   /*!< POST request */
-OrthancPluginHttpMethod_Put = 3,
+OrthancPluginHttpMethod_Put = 3,    /*!< PUT request */
-OrthancPluginHttpMethod_Delete = 4
+OrthancPluginHttpMethod_Delete = 4  /*!< DELETE request */
 } OrthancPluginHttpMethod;
+/**
+* @brief The parameters of a REST request.
+**/
 typedef struct
 {
-OrthancPluginHttpMethod method;
+/**
+* @brief The HTTP method.
-/* Groups of the regular expression */
+**/
+OrthancPluginHttpMethod method;
+/**
+* @brief The number of groups of the regular expression.
+**/
+uint32_t                groupsCount;
+/**
+* @brief The matched values for the groups of the regular expression.
+**/
 const char* const*      groups;
-uint32_t                groupsCount;
+/**
-/* For GET requests */
+* @brief For a GET request, the number of GET parameters.
+**/
+uint32_t                getCount;
+/**
+* @brief For a GET request, the keys of the GET parameters.
+**/
 const char* const*      getKeys;
+/**
+* @brief For a GET request, the values of the GET parameters.
+**/
 const char* const*      getValues;
-uint32_t                getCount;
+/**
-/* For POST and PUT requests */
+* @brief For a PUT or POST request, the content of the body.
+**/
 const char*             body;
+/**
+* @brief For a PUT or POST request, the number of bytes of the body.
+**/
 uint32_t                bodySize;
 } OrthancPluginHttpRequest;
 typedef enum
 {
 /* Generic services */
-OrthancPluginService_LogInfo = 1,
+_OrthancPluginService_LogInfo = 1,
-OrthancPluginService_LogWarning = 2,
+_OrthancPluginService_LogWarning = 2,
-OrthancPluginService_LogError = 3,
+_OrthancPluginService_LogError = 3,
 /* Registration of callbacks */
-OrthancPluginService_RegisterRestCallback = 1000,
+_OrthancPluginService_RegisterRestCallback = 1000,
 /* Sending answers to REST calls */
-OrthancPluginService_AnswerBuffer = 2000,
+_OrthancPluginService_AnswerBuffer = 2000,
-OrthancPluginService_CompressAndAnswerPngImage = 2001,
+_OrthancPluginService_CompressAndAnswerPngImage = 2001,
 /* Access to the Orthanc database */
-OrthancPluginService_GetDicomForInstance = 3000
+_OrthancPluginService_GetDicomForInstance = 3000
-} OrthancPluginService;
+} _OrthancPluginService;
 /**
 * The memory layout of the pixels of an image.
 **/
 OrthancPluginPixelFormat_RGBA32 = 5
 } OrthancPluginPixelFormat;
+/**
+* @brief A memory buffer allocated by the core system of Orthanc.
+*
+* A memory buffer allocated by the core system of Orthanc. When the
+* content of the buffer is not useful anymore, it must be free by a
+* call to ::OrthancPluginFreeMemoryBuffer().
+**/
 typedef struct
 {
+/**
+* @brief The content of the buffer.
+**/
 void*      data;
+/**
+* @brief The number of bytes in the buffer.
+**/
 uint32_t   size;
 } OrthancPluginMemoryBuffer;
+/**
+* @brief Opaque structure that represents the HTTP connection to the client application.
+**/
 typedef struct _OrthancPluginRestOutput_t OrthancPluginRestOutput;
+/**
+* @brief Signature of a function that answers to a REST request.
+**/
 typedef int32_t (*OrthancPluginRestCallback) (
 OrthancPluginRestOutput* output,
 const char* url,
 const OrthancPluginHttpRequest* request);
+/**
+* @brief Opaque structure that contains information about the Orthanc core.
+**/
 typedef struct _OrthancPluginContext_t
 {
 void*        pluginsManager;
 const char*  orthancVersion;
 void       (*Free) (void* buffer);
 int32_t    (*InvokeService) (struct _OrthancPluginContext_t* context,
-OrthancPluginService service,
+_OrthancPluginService service,
 const void* params);
 } OrthancPluginContext;
+/**
+* @brief Free a string.
+*
+* Free a string that was allocated by the core system of Orthanc.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param str The string to be freed.
+**/
 ORTHANC_PLUGIN_INLINE void  OrthancPluginFreeString(
 OrthancPluginContext* context,
 char* str)
 {
 context->Free(str);
 }
+/**
+* @brief Free a memory buffer.
+*
+* Free a memory buffer that was allocated by the core system of Orthanc.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param buffer The memory buffer to release.
+**/
 ORTHANC_PLUGIN_INLINE void  OrthancPluginFreeMemoryBuffer(
 OrthancPluginContext* context,
 OrthancPluginMemoryBuffer* buffer)
 {
 context->Free(buffer->data);
 }
+/**
+* @brief Log an error.
+*
+* Log an error message using the Orthanc logging system.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param message The message to be logged.
+**/
 ORTHANC_PLUGIN_INLINE void OrthancPluginLogError(
 OrthancPluginContext* context,
-const char* str)
+const char* message)
 {
-context->InvokeService(context, OrthancPluginService_LogError, str);
+context->InvokeService(context, _OrthancPluginService_LogError, message);
 }
+/**
+* @brief Log a warning.
+*
+* Log a warning message using the Orthanc logging system.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param message The message to be logged.
+**/
 ORTHANC_PLUGIN_INLINE void OrthancPluginLogWarning(
 OrthancPluginContext* context,
-const char* str)
+const char* message)
 {
-context->InvokeService(context, OrthancPluginService_LogWarning, str);
+context->InvokeService(context, _OrthancPluginService_LogWarning, message);
 }
+/**
+* @brief Log an information.
+*
+* Log an information message using the Orthanc logging system.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param message The message to be logged.
+**/
 ORTHANC_PLUGIN_INLINE void OrthancPluginLogInfo(
 OrthancPluginContext* context,
-const char* str)
+const char* message)
 {
-context->InvokeService(context, OrthancPluginService_LogInfo, str);
+context->InvokeService(context, _OrthancPluginService_LogInfo, message);
 }
 typedef struct
 {
 const char* pathRegularExpression;
 OrthancPluginRestCallback callback;
 } _OrthancPluginRestCallback;
+/**
+* @brief Register a REST callback.
+*
+* This function registers a REST callback against a regular
+* expression for a URI. This function must be called during the
+* initialization of the plugin, i.e. inside the
+* OrthancPluginInitialize() public function.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param pathRegularExpression Regular expression for the URI. May contain groups.
+* @param callback The callback function to handle the REST call.
+**/
 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback(
 OrthancPluginContext*     context,
 const char*               pathRegularExpression,
 OrthancPluginRestCallback callback)
 {
 _OrthancPluginRestCallback params;
 params.pathRegularExpression = pathRegularExpression;
 params.callback = callback;
-context->InvokeService(context, OrthancPluginService_RegisterRestCallback, &params);
+context->InvokeService(context, _OrthancPluginService_RegisterRestCallback, &params);
 }
 typedef struct
 {
 const char*              answer;
 uint32_t                 answerSize;
 const char*              mimeType;
 } _OrthancPluginAnswerBuffer;
+/**
+* @brief Answer to a REST request.
+*
+* This function answers to a REST request with the content of a memory buffer.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param output The HTTP connection to the client application.
+* @param answer Pointer to the memory buffer containing the answer.
+* @param answerSize Number of bytes of the answer.
+* @param mimeType The MIME type of the answer.
+**/
 ORTHANC_PLUGIN_INLINE void OrthancPluginAnswerBuffer(
 OrthancPluginContext*    context,
 OrthancPluginRestOutput* output,
 const char*              answer,
 uint32_t                 answerSize,
 _OrthancPluginAnswerBuffer params;
 params.output = output;
 params.answer = answer;
 params.answerSize = answerSize;
 params.mimeType = mimeType;
-context->InvokeService(context, OrthancPluginService_AnswerBuffer, &params);
+context->InvokeService(context, _OrthancPluginService_AnswerBuffer, &params);
 }
 typedef struct
 {
 uint32_t                  height;
 uint32_t                  pitch;
 const void*               buffer;
 } _OrthancPluginCompressAndAnswerPngImage;
+/**
+* @brief Answer to a REST request with a PNG image.
+*
+* This function answers to a REST request with a PNG image. The
+* parameters of this function describe a memory buffer that
+* contains an uncompressed image. The image will be automatically compressed
+* as a PNG image by the core system of Orthanc.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param output The HTTP connection to the client application.
+* @param format The memory layout of the uncompressed image.
+* @param width The width of the image.
+* @param height The height of the image.
+* @param pitch The pitch of the image (i.e. the number of bytes
+* between 2 successive lines of the image in the memory buffer.
+* @param buffer The memory buffer containing the uncompressed image.
+**/
 ORTHANC_PLUGIN_INLINE void OrthancPluginCompressAndAnswerPngImage(
 OrthancPluginContext*     context,
 OrthancPluginRestOutput*  output,
 OrthancPluginPixelFormat  format,
 uint32_t                  width,
 params.format = format;
 params.width = width;
 params.height = height;
 params.pitch = pitch;
 params.buffer = buffer;
-context->InvokeService(context, OrthancPluginService_CompressAndAnswerPngImage, &params);
+context->InvokeService(context, _OrthancPluginService_CompressAndAnswerPngImage, &params);
 }
 typedef struct
 {
 OrthancPluginMemoryBuffer*  target;
 const char*                 instanceId;
 } _OrthancPluginGetDicomForInstance;
+/**
+* @brief Retrieve a DICOM instance using its Orthanc identifier.
+*
+* Retrieve a DICOM instance using its Orthanc identifier. The DICOM
+* file is stored into a newly allocated memory buffer.
+*
+* @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+* @param target The target memory buffer.
+* @param instanceId The Orthanc identifier of the DICOM instance of interest.
+* @return 0 if success, other value if error.
+**/
 ORTHANC_PLUGIN_INLINE int  OrthancPluginGetDicomForInstance(
 OrthancPluginContext*       context,
 OrthancPluginMemoryBuffer*  target,
 const char*                 instanceId)
 {
 _OrthancPluginGetDicomForInstance params;
 params.target = target;
 params.instanceId = instanceId;
-return context->InvokeService(context, OrthancPluginService_GetDicomForInstance, &params);
+return context->InvokeService(context, _OrthancPluginService_GetDicomForInstance, &params);
 }
 #ifdef  __cplusplus
 }

Mercurial > hg > orthanc

comparison Plugins/OrthancCPlugin/OrthancCPlugin.h @ 907:9b8298234254 plugins