diff Plugins/Include/orthanc/OrthancCPlugin.h @ 1595:e1e54a73ba8b

OrthancPluginRegisterRestCallbackNoLock, documentation
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 27 Aug 2015 14:58:58 +0200
parents 2bac60a4f584
children f2e3d030ea59
line wrap: on
line diff
--- a/Plugins/Include/orthanc/OrthancCPlugin.h	Thu Aug 27 12:56:48 2015 +0200
+++ b/Plugins/Include/orthanc/OrthancCPlugin.h	Thu Aug 27 14:58:58 2015 +0200
@@ -17,7 +17,7 @@
  *    - Possibly register its callback for received DICOM instances using ::OrthancPluginRegisterOnStoredInstanceCallback().
  *    - Possibly register its callback for changes to the DICOM store using ::OrthancPluginRegisterOnChangeCallback().
  *    - Possibly register a custom storage area using ::OrthancPluginRegisterStorageArea().
- *    - Possibly register a custom database back-end area using ::OrthancPluginRegisterDatabaseBackend().
+ *    - Possibly register a custom database back-end area using OrthancPluginRegisterDatabaseBackend().
  * -# <tt>void OrthancPluginFinalize()</tt>:
  *    This function is invoked by Orthanc during its shutdown. The plugin
  *    must free all its memory.
@@ -29,8 +29,11 @@
  * The name and the version of a plugin is only used to prevent it
  * from being loaded twice.
  * 
- * The various REST callbacks are guaranteed to be executed in mutual
- * exclusion since Orthanc 0.8.5.
+ * To ensure multi-threading safety, the various REST callbacks are
+ * guaranteed to be executed in mutual exclusion since Orthanc
+ * 0.8.5. If this feature is undesired (notably when developing
+ * high-performance plugins handling simultaneous requests), use
+ * ::OrthancPluginRegisterRestCallbackNoLock().
  **/
 
 
@@ -361,6 +364,7 @@
     _OrthancPluginService_RegisterOnStoredInstanceCallback = 1001,
     _OrthancPluginService_RegisterStorageArea = 1002,
     _OrthancPluginService_RegisterOnChangeCallback = 1003,
+    _OrthancPluginService_RegisterRestCallbackNoLock = 1004,
 
     /* Sending answers to REST calls */
     _OrthancPluginService_AnswerBuffer = 2000,
@@ -857,10 +861,13 @@
    * expression for a URI. This function must be called during the
    * initialization of the plugin, i.e. inside the
    * OrthancPluginInitialize() public function.
+   *
+   * Each REST callback is guaranteed to run in mutual exclusion.
    * 
    * @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.
+   * @see OrthancPluginRegisterRestCallbackNoLock()
    **/
   ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback(
     OrthancPluginContext*     context,
@@ -875,6 +882,39 @@
 
 
 
+  /**
+   * @brief Register a REST callback, without locking.
+   *
+   * 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.
+   *
+   * Contrarily to OrthancPluginRegisterRestCallback(), the callback
+   * will NOT be invoked in mutual exclusion. This can be useful for
+   * high-performance plugins that must handle concurrent requests
+   * (Orthanc uses a pool of threads, one thread being assigned to
+   * each incoming HTTP request). Of course, it is up to the plugin to
+   * implement the required locking mechanisms.
+   * 
+   * @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.
+   * @see OrthancPluginRegisterRestCallback()
+   **/
+  ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallbackNoLock(
+    OrthancPluginContext*     context,
+    const char*               pathRegularExpression,
+    OrthancPluginRestCallback callback)
+  {
+    _OrthancPluginRestCallback params;
+    params.pathRegularExpression = pathRegularExpression;
+    params.callback = callback;
+    context->InvokeService(context, _OrthancPluginService_RegisterRestCallbackNoLock, &params);
+  }
+
+
+
   typedef struct
   {
     OrthancPluginOnStoredInstanceCallback callback;
@@ -2468,7 +2508,7 @@
    * This function returns the description of a given error code.
    * 
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
-   * @param code The error code of interest.
+   * @param error The error code of interest.
    * @return The error description. This is a statically-allocated
    * string, do not free it.
    **/
@@ -2520,6 +2560,8 @@
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param output The HTTP connection to the client application.
    * @param status The HTTP status code to be sent.
+   * @param body The body of the answer.
+   * @param bodySize The size of the body.
    * @see OrthancPluginSendHttpStatusCode()
    **/
   ORTHANC_PLUGIN_INLINE void OrthancPluginSendHttpStatus(