# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1448034169 -3600
# Node ID d093f998a83b48c981631843ed169b20df71a2c4
# Parent  138664eb59debbcf9022e23bad27b36ddcd2ca91
documentation

diff -r 138664eb59de -r d093f998a83b Plugins/Include/orthanc/OrthancCPlugin.h
--- a/Plugins/Include/orthanc/OrthancCPlugin.h	Fri Nov 20 15:54:07 2015 +0100
+++ b/Plugins/Include/orthanc/OrthancCPlugin.h	Fri Nov 20 16:42:49 2015 +0100
@@ -18,6 +18,7 @@
  *    - 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 OrthancPluginRegisterDatabaseBackendV2().
+ *    - Possibly register a handler for C-Find SCP against DICOM worklists using OrthancPluginRegisterWorklistCallback().
  * -# <tt>void OrthancPluginFinalize()</tt>:
  *    This function is invoked by Orthanc during its shutdown. The plugin
  *    must free all its memory.
@@ -878,7 +879,8 @@
   /**
    * @brief Callback to handle the C-Find SCP requests received by Orthanc.
    *
-   * Signature of a callback function that is triggered when Orthanc receives a C-Find SCP request.
+   * Signature of a callback function that is triggered when Orthanc
+   * receives a C-Find SCP request against modality worklists.
    *
    * @param answers The target structure where answers must be stored.
    * @param query The worklist query.
@@ -4109,6 +4111,21 @@
     uint32_t                           size;
   } _OrthancPluginWorklistAnswersOperation;
 
+  /**
+   * @brief Add one answer to some modality worklist request.
+   *
+   * This function adds one worklist (encoded as a DICOM file) to the
+   * set of answers corresponding to some C-Find SCP request against
+   * modality worklists.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param answers The set of answers.
+   * @param query The worklist query, as received by the callback.
+   * @param dicom The worklist to answer, encoded as a DICOM file.
+   * @param size The size of the DICOM file.
+   * @return 0 if success, other value if error.
+   * @ingroup Worklists
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode  OrthancPluginWorklistAddWorklistAnswer(
     OrthancPluginContext*             context,
     OrthancPluginWorklistAnswers*     answers,
@@ -4126,6 +4143,19 @@
   }
 
 
+  /**
+   * @brief Mark the set of worklist answers as incomplete.
+   *
+   * This function marks as incomplete the set of answers
+   * corresponding to some C-Find SCP request against modality
+   * worklists. This must be used if canceling the handling of a
+   * request when too many answers are to be returned.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param answers The set of answers.
+   * @return 0 if success, other value if error.
+   * @ingroup Worklists
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode  OrthancPluginMarkWorklistAnswersIncomplete(
     OrthancPluginContext*          context,
     OrthancPluginWorklistAnswers*  answers)
@@ -4149,6 +4179,22 @@
     OrthancPluginMemoryBuffer*         target;
   } _OrthancPluginWorklistQueryOperation;
 
+  /**
+   * @brief Test whether a worklist matches the query.
+   *
+   * This function checks whether one worklist (encoded as a DICOM
+   * file) matches the C-Find SCP query against modality
+   * worklists. This function must be called before adding the
+   * worklist as an answer through
+   * OrthancPluginWorklistAddWorklistAnswer().
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param query The worklist query, as received by the callback.
+   * @param dicom The worklist to answer, encoded as a DICOM file.
+   * @param size The size of the DICOM file.
+   * @return 1 if the worklist matches the query, 0 otherwise.
+   * @ingroup Worklists
+   **/
   ORTHANC_PLUGIN_INLINE int32_t  OrthancPluginIsWorklistMatch(
     OrthancPluginContext*              context,
     const OrthancPluginWorklistQuery*  query,
@@ -4176,6 +4222,18 @@
   }
 
 
+  /**
+   * @brief Retrieve the worklist query as a DICOM file.
+   *
+   * This function retrieves the DICOM file that underlies a C-Find
+   * SCP query against modality worklists.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param target Memory buffer where to store the DICOM file. It must be freed with OrthancPluginFreeMemoryBuffer().
+   * @param query The worklist query, as received by the callback.
+   * @return 0 if success, other value if error.
+   * @ingroup Worklists
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode  OrthancPluginGetWorklistQueryDicom(
     OrthancPluginContext*              context,
     OrthancPluginMemoryBuffer*         target,