# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1403180923 -7200
# Node ID 9b829823425411c2628657ed61f5ce642f3e0deb
# Parent  cbc0ea03dffeea736f20e48810347d0abc49b4ab
documentation

diff -r cbc0ea03dffe -r 9b8298234254 Plugins/Engine/IPluginServiceProvider.h
--- a/Plugins/Engine/IPluginServiceProvider.h	Thu Jun 19 13:37:49 2014 +0200
+++ b/Plugins/Engine/IPluginServiceProvider.h	Thu Jun 19 14:28:43 2014 +0200
@@ -45,7 +45,7 @@
     {
     }
 
-    virtual bool InvokeService(OrthancPluginService service,
+    virtual bool InvokeService(_OrthancPluginService service,
                                const void* parameters) = 0;
   };
 }
diff -r cbc0ea03dffe -r 9b8298234254 Plugins/Engine/PluginsHttpHandler.cpp
--- a/Plugins/Engine/PluginsHttpHandler.cpp	Thu Jun 19 13:37:49 2014 +0200
+++ b/Plugins/Engine/PluginsHttpHandler.cpp	Thu Jun 19 14:28:43 2014 +0200
@@ -190,12 +190,12 @@
   }
 
 
-  bool PluginsHttpHandler::InvokeService(OrthancPluginService service,
+  bool PluginsHttpHandler::InvokeService(_OrthancPluginService service,
                                          const void* parameters)
   {
     switch (service)
     {
-      case OrthancPluginService_RegisterRestCallback:
+      case _OrthancPluginService_RegisterRestCallback:
       {
         const _OrthancPluginRestCallback& p = 
           *reinterpret_cast<const _OrthancPluginRestCallback*>(parameters);
@@ -206,7 +206,7 @@
         return true;
       }
 
-      case OrthancPluginService_AnswerBuffer:
+      case _OrthancPluginService_AnswerBuffer:
       {
         const _OrthancPluginAnswerBuffer& p = 
           *reinterpret_cast<const _OrthancPluginAnswerBuffer*>(parameters);
@@ -217,7 +217,7 @@
         return true;
       }
 
-      case OrthancPluginService_CompressAndAnswerPngImage:
+      case _OrthancPluginService_CompressAndAnswerPngImage:
       {
         const _OrthancPluginCompressAndAnswerPngImage& p = 
           *reinterpret_cast<const _OrthancPluginCompressAndAnswerPngImage*>(parameters);
@@ -263,7 +263,7 @@
         return true;
       }
 
-      case OrthancPluginService_GetDicomForInstance:
+      case _OrthancPluginService_GetDicomForInstance:
       {
         const _OrthancPluginGetDicomForInstance& p = 
           *reinterpret_cast<const _OrthancPluginGetDicomForInstance*>(parameters);
diff -r cbc0ea03dffe -r 9b8298234254 Plugins/Engine/PluginsHttpHandler.h
--- a/Plugins/Engine/PluginsHttpHandler.h	Thu Jun 19 13:37:49 2014 +0200
+++ b/Plugins/Engine/PluginsHttpHandler.h	Thu Jun 19 14:28:43 2014 +0200
@@ -60,7 +60,7 @@
                         const Arguments& getArguments,
                         const std::string& postData);
 
-    virtual bool InvokeService(OrthancPluginService service,
+    virtual bool InvokeService(_OrthancPluginService service,
                                const void* parameters);
   };
 }
diff -r cbc0ea03dffe -r 9b8298234254 Plugins/Engine/PluginsManager.cpp
--- a/Plugins/Engine/PluginsManager.cpp	Thu Jun 19 13:37:49 2014 +0200
+++ b/Plugins/Engine/PluginsManager.cpp	Thu Jun 19 14:28:43 2014 +0200
@@ -133,20 +133,20 @@
 
 
   int32_t PluginsManager::InvokeService(OrthancPluginContext* context,
-                                        OrthancPluginService service, 
+                                        _OrthancPluginService service, 
                                         const void* params)
   {
     switch (service)
     {
-      case OrthancPluginService_LogError:
+      case _OrthancPluginService_LogError:
         LOG(ERROR) << reinterpret_cast<const char*>(params);
         return 0;
 
-      case OrthancPluginService_LogWarning:
+      case _OrthancPluginService_LogWarning:
         LOG(WARNING) << reinterpret_cast<const char*>(params);
         return 0;
 
-      case OrthancPluginService_LogInfo:
+      case _OrthancPluginService_LogInfo:
         LOG(INFO) << reinterpret_cast<const char*>(params);
         return 0;
 
diff -r cbc0ea03dffe -r 9b8298234254 Plugins/Engine/PluginsManager.h
--- a/Plugins/Engine/PluginsManager.h	Thu Jun 19 13:37:49 2014 +0200
+++ b/Plugins/Engine/PluginsManager.h	Thu Jun 19 14:28:43 2014 +0200
@@ -50,7 +50,7 @@
     std::list<IPluginServiceProvider*> serviceProviders_;
 
     static int32_t InvokeService(OrthancPluginContext* context,
-                                 OrthancPluginService service,
+                                 _OrthancPluginService service,
                                  const void* parameters);
 
   public:
diff -r cbc0ea03dffe -r 9b8298234254 Plugins/OrthancCPlugin/OrthancCPlugin.h
--- a/Plugins/OrthancCPlugin/OrthancCPlugin.h	Thu Jun 19 13:37:49 2014 +0200
+++ b/Plugins/OrthancCPlugin/OrthancCPlugin.h	Thu Jun 19 14:28:43 2014 +0200
@@ -1,16 +1,28 @@
 /**
  * \mainpage
  *
- * This SDK allows external developers to create plugins that can be
- * loaded into Orthanc to extend its functionality. Each Orthanc
- * plugin must expose 4 public functions with the following
+ * This C/C++ SDK allows external developers to create plugins that
+ * can be loaded into Orthanc to extend its functionality. Each
+ * Orthanc plugin must expose 4 public functions with the following
  * signatures:
  * 
- * - <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext*)</tt>:
- *   This function is invoked by Orthanc
- * - <tt>void OrthancPluginFinalize()</tt>
- * - <tt>const char* OrthancPluginGetName()</tt>
- * - <tt>const char* OrthancPluginGetVersion()</tt>
+ * -# <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext* context)</tt>:
+ *    This function is invoked by Orthanc when it loads the plugin on startup.
+ *    The plugin must store the context pointer so that it can use the plugin 
+ *    services of Orthanc. It must also register all its callbacks using
+ *    ::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.
+ * 
+ * 
  **/
 
 
@@ -106,7 +118,7 @@
 
 
 /********************************************************************
- ** Inclusion of standard libaries.
+ ** Inclusion of standard libraries.
  ********************************************************************/
 
 #ifdef _MSC_VER
@@ -130,49 +142,81 @@
 {
 #endif
 
+  /**
+   * The various HTTP methods for a REST call.
+   **/
   typedef enum
   {
-    OrthancPluginHttpMethod_Get = 1,
-    OrthancPluginHttpMethod_Post = 2,
-    OrthancPluginHttpMethod_Put = 3,
-    OrthancPluginHttpMethod_Delete = 4
+    OrthancPluginHttpMethod_Get = 1,    /*!< GET request */
+    OrthancPluginHttpMethod_Post = 2,   /*!< POST request */
+    OrthancPluginHttpMethod_Put = 3,    /*!< PUT request */
+    OrthancPluginHttpMethod_Delete = 4  /*!< DELETE request */
   } OrthancPluginHttpMethod;
 
+
+  /**
+   * @brief The parameters of a REST request.
+   **/
   typedef struct
   {
-    OrthancPluginHttpMethod method;
+    /**
+     * @brief The HTTP method.
+     **/
+    OrthancPluginHttpMethod method;    
 
-    /* Groups of the regular expression */
-    const char* const*      groups;
+    /**
+     * @brief The number of groups of the regular expression.
+     **/
     uint32_t                groupsCount;
 
-    /* For GET requests */
-    const char* const*      getKeys;
-    const char* const*      getValues;
+    /**
+     * @brief The matched values for the groups of the regular expression.
+     **/
+    const char* const*      groups;
+
+    /**
+     * @brief For a GET request, the number of GET parameters.
+     **/
     uint32_t                getCount;
 
-    /* For POST and PUT requests */
+    /**
+     * @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;
+
+    /**
+     * @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_LogWarning = 2,
-    OrthancPluginService_LogError = 3,
+    _OrthancPluginService_LogInfo = 1,
+    _OrthancPluginService_LogWarning = 2,
+    _OrthancPluginService_LogError = 3,
 
     /* Registration of callbacks */
-    OrthancPluginService_RegisterRestCallback = 1000,
+    _OrthancPluginService_RegisterRestCallback = 1000,
 
     /* Sending answers to REST calls */
-    OrthancPluginService_AnswerBuffer = 2000,
-    OrthancPluginService_CompressAndAnswerPngImage = 2001,
+    _OrthancPluginService_AnswerBuffer = 2000,
+    _OrthancPluginService_CompressAndAnswerPngImage = 2001,
 
     /* Access to the Orthanc database */
-    OrthancPluginService_GetDicomForInstance = 3000
-  } OrthancPluginService;
+    _OrthancPluginService_GetDicomForInstance = 3000
+  } _OrthancPluginService;
 
 
 
@@ -223,33 +267,67 @@
   } 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)
@@ -258,6 +336,14 @@
   }
 
 
+  /**
+   * @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)
@@ -266,27 +352,51 @@
   }
 
 
+  /**
+   * @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);
   }
 
 
@@ -297,6 +407,18 @@
   } _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,
@@ -305,7 +427,7 @@
     _OrthancPluginRestCallback params;
     params.pathRegularExpression = pathRegularExpression;
     params.callback = callback;
-    context->InvokeService(context, OrthancPluginService_RegisterRestCallback, &params);
+    context->InvokeService(context, _OrthancPluginService_RegisterRestCallback, &params);
   }
 
 
@@ -317,6 +439,18 @@
     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,
@@ -329,7 +463,7 @@
     params.answer = answer;
     params.answerSize = answerSize;
     params.mimeType = mimeType;
-    context->InvokeService(context, OrthancPluginService_AnswerBuffer, &params);
+    context->InvokeService(context, _OrthancPluginService_AnswerBuffer, &params);
   }
 
 
@@ -343,6 +477,23 @@
     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,
@@ -359,7 +510,7 @@
     params.height = height;
     params.pitch = pitch;
     params.buffer = buffer;
-    context->InvokeService(context, OrthancPluginService_CompressAndAnswerPngImage, &params);
+    context->InvokeService(context, _OrthancPluginService_CompressAndAnswerPngImage, &params);
   }
 
 
@@ -369,6 +520,18 @@
     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,
@@ -377,7 +540,7 @@
     _OrthancPluginGetDicomForInstance params;
     params.target = target;
     params.instanceId = instanceId;
-    return context->InvokeService(context, OrthancPluginService_GetDicomForInstance, &params);
+    return context->InvokeService(context, _OrthancPluginService_GetDicomForInstance, &params);
   }
 
 
diff -r cbc0ea03dffe -r 9b8298234254 Resources/OrthancPlugin.doxygen
--- a/Resources/OrthancPlugin.doxygen	Thu Jun 19 13:37:49 2014 +0200
+++ b/Resources/OrthancPlugin.doxygen	Thu Jun 19 14:28:43 2014 +0200
@@ -1475,13 +1475,13 @@
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # pointed to by INCLUDE_PATH will be searched when a #include is found.
@@ -1509,7 +1509,7 @@
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = ORTHANC_PLUGIN_INLINE=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
diff -r cbc0ea03dffe -r 9b8298234254 UnitTestsSources/PluginsTests.cpp
--- a/UnitTestsSources/PluginsTests.cpp	Thu Jun 19 13:37:49 2014 +0200
+++ b/UnitTestsSources/PluginsTests.cpp	Thu Jun 19 14:28:43 2014 +0200
@@ -59,22 +59,3 @@
 #error Support your platform here
 #endif
 }
-
-
-TEST(SharedLibrary, Development)
-{
-  PluginsManager manager;
-
-#if defined(_WIN32)
-//#error Support your platform here
-
-#elif defined(__linux)
-  manager.RegisterPlugin("./libPluginTest.so");
-  ASSERT_THROW(manager.RegisterPlugin("./libPluginTest.so"), OrthancException);
-
-  //manager.ScanFolderForPlugins(".", true);
-
-#else
-#error Support your platform here
-#endif  
-}