# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1747756394 -7200
# Node ID 79e9fa2872cf1cb9030651a3e2d8c2ca06aa1e4b
# Parent  0ff96222e46100469fc43ab9170ebf80007a7693
cleaning the sdk

diff -r 0ff96222e461 -r 79e9fa2872cf OrthancServer/Plugins/Engine/OrthancPlugins.cpp
--- a/OrthancServer/Plugins/Engine/OrthancPlugins.cpp	Tue May 20 16:48:12 2025 +0200
+++ b/OrthancServer/Plugins/Engine/OrthancPlugins.cpp	Tue May 20 17:53:14 2025 +0200
@@ -4732,7 +4732,7 @@
   void OrthancPlugins::ApplyStoreKeyValue(const _OrthancPluginStoreKeyValue& parameters)
   {
     PImpl::ServerContextReference lock(*pimpl_);
-    std::string value(parameters.value, parameters.valueSize);
+    std::string value(reinterpret_cast<const char*>(parameters.value), parameters.valueSize);
 
     lock.GetContext().GetIndex().StoreKeyValue(parameters.storeId, parameters.key, value);
   }
@@ -4752,7 +4752,12 @@
 
     if (lock.GetContext().GetIndex().GetKeyValue(value, parameters.storeId, parameters.key))
     {
-      CopyToMemoryBuffer(*parameters.value, value.size() > 0 ? value.c_str() : NULL, value.size());
+      CopyToMemoryBuffer(*parameters.target, value.size() > 0 ? value.c_str() : NULL, value.size());
+      *parameters.isExisting = true;
+    }
+    else
+    {
+      *parameters.isExisting = false;
     }
   }
 
@@ -4776,7 +4781,7 @@
   void OrthancPlugins::ApplyEnqueueValue(const _OrthancPluginEnqueueValue& parameters)
   {
     PImpl::ServerContextReference lock(*pimpl_);
-    std::string value(parameters.value, parameters.valueSize);
+    std::string value(reinterpret_cast<const char*>(parameters.value), parameters.valueSize);
 
     lock.GetContext().GetIndex().EnqueueValue(parameters.queueId, value);
   }
@@ -4789,7 +4794,12 @@
 
     if (lock.GetContext().GetIndex().DequeueValue(value, parameters.queueId, Plugins::Convert(parameters.origin)))
     {
-      CopyToMemoryBuffer(*parameters.value, value.size() > 0 ? value.c_str() : NULL, value.size());
+      CopyToMemoryBuffer(*parameters.target, value.size() > 0 ? value.c_str() : NULL, value.size());
+      *parameters.isExisting = true;
+    }
+    else
+    {
+      *parameters.isExisting = false;
     }
   }
 
@@ -5969,11 +5979,13 @@
           LOG(ERROR) << "The DB engine does not support Queues";
           return false;
         }
-
-        const _OrthancPluginDequeueValue& p =
-          *reinterpret_cast<const _OrthancPluginDequeueValue*>(parameters);
-        ApplyDequeueValue(p);
-        return true;
+        else
+        {
+          const _OrthancPluginDequeueValue& p =
+            *reinterpret_cast<const _OrthancPluginDequeueValue*>(parameters);
+          ApplyDequeueValue(p);
+          return true;
+        }
       }
 
       case _OrthancPluginService_GetQueueSize:
diff -r 0ff96222e461 -r 79e9fa2872cf OrthancServer/Plugins/Include/orthanc/OrthancCDatabasePlugin.h
--- a/OrthancServer/Plugins/Include/orthanc/OrthancCDatabasePlugin.h	Tue May 20 16:48:12 2025 +0200
+++ b/OrthancServer/Plugins/Include/orthanc/OrthancCDatabasePlugin.h	Tue May 20 17:53:14 2025 +0200
@@ -1327,8 +1327,6 @@
 
   } OrthancPluginDatabaseBackendV3;
 
-/*<! @endcond */
-  
 
   typedef struct
   {
@@ -1362,6 +1360,9 @@
     return context->InvokeService(context, _OrthancPluginService_RegisterDatabaseBackendV3, &params);
   }
 
+/*<! @endcond */
+
+
 #ifdef  __cplusplus
 }
 #endif
diff -r 0ff96222e461 -r 79e9fa2872cf OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h
--- a/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h	Tue May 20 16:48:12 2025 +0200
+++ b/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h	Tue May 20 17:53:14 2025 +0200
@@ -1519,9 +1519,10 @@
    * The memory buffer is allocated and freed by Orthanc. The length of the range
    * of interest corresponds to the size of this buffer.
    * @param uuid The UUID of the file of interest.
-   * @param customData The custom data of the file of interest.
    * @param type The content type corresponding to this file.
    * @param rangeStart Start position of the requested range in the file.
+   * @param customData The custom data of the file of interest.
+   * @param customDataSize The size of the custom data.
    * @return 0 if success, other value if error.
    * @ingroup Callbacks
    **/
@@ -1541,8 +1542,9 @@
    * Signature of a callback function that is triggered when Orthanc deletes a file from the storage area.
    *
    * @param uuid The UUID of the file to be removed.
+   * @param type The content type corresponding to this file.
    * @param customData The custom data of the file to be removed.
-   * @param type The content type corresponding to this file.
+   * @param customDataSize The size of the custom data.
    * @return 0 if success, other value if error.
    * @ingroup Callbacks
    **/
@@ -9503,7 +9505,6 @@
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param create The callback function to store a file on the custom storage area.
-   * @param readWhole The callback function to read a whole file from the custom storage area.
    * @param readRange The callback function to read some range of a file from the custom storage area.
    * If this feature is not supported by the plugin, this value can be set to NULL.
    * @param remove The callback function to remove a file from the custom storage area.
@@ -9907,7 +9908,7 @@
   {
     const char*                   storeId;
     const char*                   key;
-    const char*                   value;
+    const void*                   value;
     uint64_t                      valueSize;
   } _OrthancPluginStoreKeyValue;
   
@@ -9916,15 +9917,16 @@
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param storeId A unique identifier identifying both the plugin and the store
-   * @param key The key of the value to store (Note: storeId + key must be unique)
+   * @param key The key of the value to store (note: storeId + key must be unique)
    * @param value The value to store
    * @param valueSize The lenght of the value to store
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginStoreKeyValue(
     OrthancPluginContext*         context,
     const char*                   storeId, /* in */
     const char*                   key, /* in */
-    const char*                   value, /* in */
+    const void*                   value, /* in */
     uint64_t                      valueSize /* in */)
   {
     _OrthancPluginStoreKeyValue params;
@@ -9947,7 +9949,8 @@
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param storeId A unique identifier identifying both the plugin and the store
-   * @param key The key of the value to store (Note: storeId + key must be unique)
+   * @param key The key of the value to store (note: storeId + key must be unique)
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginDeleteKeyValue(
     OrthancPluginContext*         context,
@@ -9963,29 +9966,34 @@
 
   typedef struct
   {
+    uint8_t*                      isExisting;
+    OrthancPluginMemoryBuffer*    target;
     const char*                   storeId;
     const char*                   key;
-    OrthancPluginMemoryBuffer*    value;
   } _OrthancPluginGetKeyValue;
   
   /**
    * @brief Get the value associated to this key in the key-value store.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param isExisting Pointer to a Boolean that is set to "true" iff. the key exists in the store
+   * @param target Memory buffer where to store the retrieved value
    * @param storeId A unique identifier identifying both the plugin and the store
-   * @param key The key of the value to retrieve from the store (Note: storeId + key must be unique)
-   * @param value The value retrieved from the store
+   * @param key The key of the value to retrieve from the store (note: storeId + key must be unique)
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginGetKeyValue(
     OrthancPluginContext*         context,
+    uint8_t*                      isExisting,
+    OrthancPluginMemoryBuffer*    target, /* out */
     const char*                   storeId, /* in */
-    const char*                   key, /* in */
-    OrthancPluginMemoryBuffer*    value /* out */)
+    const char*                   key /* in */)
   {
     _OrthancPluginGetKeyValue params;
+    params.isExisting = isExisting;
+    params.target = target;
     params.storeId = storeId;
     params.key = key;
-    params.value = value;
 
     return context->InvokeService(context, _OrthancPluginService_GetKeyValue, &params);
   }
@@ -10000,13 +10008,14 @@
 
 
   /**
-   * @brief List the keys from a key-value store.
+   * @brief Create an iterator over the keys and values stored in a key-value store.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param storeId A unique identifier identifying both the plugin and the store
    * @param since The index of the first key to return when sorted alphabetically
    * @param limit The number of keys to return (0 for no limit)
    * @param keys The keys serialized in a json string
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginListKeys(
     OrthancPluginContext*         context,
@@ -10028,23 +10037,24 @@
   typedef struct
   {
     const char*                   queueId;
-    const char*                   value;
-    uint64_t                      valueSize;
+    const void*                   value;
+    uint32_t                      valueSize;
   } _OrthancPluginEnqueueValue;
 
   /**
-   * @brief Tell Orthanc to store a value in a queue.
+   * @brief Append a value to the back of a queue.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param queueId A unique identifier identifying both the plugin and the queue
    * @param value The value to store
-   * @param valueSize The lenght of the value to store
+   * @param valueSize The size of the value to store
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginEnqueueValue(
     OrthancPluginContext*         context,
-    const char*                   queueId, /* in */
-    const char*                   value, /* in */
-    uint64_t                      valueSize /* in */)
+    const char*                   queueId,  /* in */
+    const void*                   value,    /* in */
+    uint32_t                      valueSize /* in */)
   {
     _OrthancPluginEnqueueValue params;
     params.queueId = queueId;
@@ -10056,29 +10066,34 @@
 
   typedef struct
   {
+    uint8_t*                      isExisting;
+    OrthancPluginMemoryBuffer*    target;
     const char*                   queueId;
     OrthancPluginQueueOrigin      origin;
-    OrthancPluginMemoryBuffer*    value;
   } _OrthancPluginDequeueValue;
   
   /**
    * @brief Dequeue a value from a queue.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param isExisting Pointer to a Boolean that is set to "true" iff. a value has been dequeued
+   * @param target Memory buffer where to store the value that has been retrieved from the queue
    * @param queueId A unique identifier identifying both the plugin and the queue
-   * @param origin The extremity of the queue the value is dequeue from (back for LIFO or front for FIFO)
-   * @param value The value retrieved from the queue
+   * @param origin The queue position where the value is removed (back for LIFO, front for FIFO)
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginDequeueValue(
     OrthancPluginContext*         context,
-    const char*                   queueId, /* in */
-    OrthancPluginQueueOrigin      origin, /* in */
-    OrthancPluginMemoryBuffer*    value /* out */)
+    uint8_t*                      isExisting,  /* out */
+    OrthancPluginMemoryBuffer*    target,      /* out */
+    const char*                   queueId,     /* in */
+    OrthancPluginQueueOrigin      origin       /* in */)
   {
     _OrthancPluginDequeueValue params;
+    params.isExisting = isExisting;
+    params.target = target;
     params.queueId = queueId;
     params.origin = origin;
-    params.value = value;
 
     return context->InvokeService(context, _OrthancPluginService_DequeueValue, &params);
   }
@@ -10093,8 +10108,9 @@
    * @brief Get the number of elements in a queue.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
-   * @param queueId A unique identifier identifying both the plugin and the queue
-   * @param size The number of elements in the queue
+   * @param queueId A unique identifier identifying both the plugin and the queue.
+   * @param size The number of elements in the queue.
+   * @return 0 if success, other value if error.
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginGetQueueSize(
     OrthancPluginContext*         context,
diff -r 0ff96222e461 -r 79e9fa2872cf OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp
--- a/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp	Tue May 20 16:48:12 2025 +0200
+++ b/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp	Tue May 20 17:53:14 2025 +0200
@@ -4348,61 +4348,67 @@
   }
 #endif
 
-#if ORTHANC_PLUGINS_VERSION_IS_ABOVE(1, 12, 99)
-
-  KeyValueStore::KeyValueStore(const std::string& storeId)
-  : storeId_(storeId)
-  {
+
+#if HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES == 1
+  void KeyValueStore::Store(const std::string& key,
+                            const std::string& value)
+  {
+    OrthancPluginErrorCode code = OrthancPluginStoreKeyValue(OrthancPlugins::GetGlobalContext(), storeId_.c_str(),
+                                                             key.c_str(), value.c_str(), value.size());
+    if (code == OrthancPluginErrorCode_Success)
+    {
+      ORTHANC_PLUGINS_THROW_PLUGIN_ERROR_CODE(code);
+    }
   }
-
-  void KeyValueStore::Store(const std::string& key, const std::string& value)
-  {
-    OrthancPluginStoreKeyValue(OrthancPlugins::GetGlobalContext(),
-                               storeId_.c_str(),
-                               key.c_str(),
-                               value.c_str(),
-                               value.size());
-  }
-
-  bool KeyValueStore::Get(std::string& value, const std::string& key)
-  {
+#endif
+
+
+#if HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES == 1
+  bool KeyValueStore::Get(std::string& value,
+                          const std::string& key)
+  {
+    uint8_t isExisting = false;
     OrthancPlugins::MemoryBuffer valueBuffer;
-    OrthancPluginErrorCode ret = OrthancPluginGetKeyValue(OrthancPlugins::GetGlobalContext(),
-                                                          storeId_.c_str(),
-                                                          key.c_str(),
-                                                          *valueBuffer);
-
-    if (ret == OrthancPluginErrorCode_Success)
-    {
-      if (!valueBuffer.IsEmpty())
-      {
-        value.assign(valueBuffer.GetData(), valueBuffer.GetSize());
-        return true;
-      }
-      else
-      {
-        return false;
-      }
-    }
-    
-    return false;
+    OrthancPluginErrorCode code = OrthancPluginGetKeyValue(OrthancPlugins::GetGlobalContext(), &isExisting,
+                                                           *valueBuffer, storeId_.c_str(), key.c_str());
+
+    if (code != OrthancPluginErrorCode_Success)
+    {
+      ORTHANC_PLUGINS_THROW_PLUGIN_ERROR_CODE(code);
+    }
+    else if (isExisting)
+    {
+      valueBuffer.ToString(value);
+      return true;
+    }
+    else
+    {
+      return false;
+    }
   }
-
+#endif
+
+
+#if HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES == 1
   void KeyValueStore::Delete(const std::string& key)
   {
-    OrthancPluginDeleteKeyValue(OrthancPlugins::GetGlobalContext(),
-                                storeId_.c_str(),
-                                key.c_str());
+    OrthancPluginErrorCode code = OrthancPluginDeleteKeyValue(OrthancPlugins::GetGlobalContext(),
+                                                              storeId_.c_str(), key.c_str());
+
+    if (code != OrthancPluginErrorCode_Success)
+    {
+      ORTHANC_PLUGINS_THROW_PLUGIN_ERROR_CODE(code);
+    }
   }
-
+#endif
+
+
+#if HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES == 1
   bool KeyValueStore::GetAllKeys(std::list<std::string>& keys, uint64_t since, uint64_t limit)
   {
     OrthancPlugins::MemoryBuffer keysListBuffer;
-    OrthancPluginErrorCode ret = OrthancPluginListKeys(OrthancPlugins::GetGlobalContext(),
-                                                       storeId_.c_str(),
-                                                       since,
-                                                       limit,
-                                                       *keysListBuffer);
+    OrthancPluginErrorCode ret = OrthancPluginListKeys(OrthancPlugins::GetGlobalContext(), storeId_.c_str(),
+                                                       since, limit, *keysListBuffer);
 
     if (ret == OrthancPluginErrorCode_Success)
     {
@@ -4425,72 +4431,64 @@
     ORTHANC_PLUGINS_THROW_EXCEPTION(InternalError);
 #endif
   }
-
-  Queue::Queue(const std::string& queueId)
-  : queueId_(queueId)
-  {
-  }
-
+#endif
+
+
+#if HAS_ORTHANC_PLUGIN_QUEUES == 1
   void Queue::PushBack(const std::string& value)
   {
-    OrthancPluginEnqueueValue(OrthancPlugins::GetGlobalContext(),
-                              queueId_.c_str(),
-                              value.c_str(),
-                              value.size());
+    OrthancPluginErrorCode code = OrthancPluginEnqueueValue(OrthancPlugins::GetGlobalContext(),
+                                                            queueId_.c_str(), value.c_str(), value.size());
+
+    if (code != OrthancPluginErrorCode_Success)
+    {
+      ORTHANC_PLUGINS_THROW_PLUGIN_ERROR_CODE(code);
+    }
   }
-
-  bool Queue::PopInternal(std::string& value, OrthancPluginQueueOrigin origin)
-  {
+#endif
+
+
+#if HAS_ORTHANC_PLUGIN_QUEUES == 1
+  bool Queue::PopInternal(std::string& value,
+                          OrthancPluginQueueOrigin origin)
+  {
+    uint8_t isExisting = false;
     OrthancPlugins::MemoryBuffer valueBuffer;
-    OrthancPluginErrorCode ret = OrthancPluginDequeueValue(OrthancPlugins::GetGlobalContext(),
-                                                           queueId_.c_str(),
-                                                           origin,
-                                                           *valueBuffer);
-
-    if (ret == OrthancPluginErrorCode_Success)
-    {
-      if (!valueBuffer.IsEmpty())
-      {
-        value.assign(valueBuffer.GetData(), valueBuffer.GetSize());
-        return true;
-      }
-      else
-      {
-        return false;
-      }
-    }
-    
-    return false;
+
+    OrthancPluginErrorCode code = OrthancPluginDequeueValue(OrthancPlugins::GetGlobalContext(), &isExisting,
+                                                            *valueBuffer, queueId_.c_str(), origin);
+
+    if (code != OrthancPluginErrorCode_Success)
+    {
+      ORTHANC_PLUGINS_THROW_PLUGIN_ERROR_CODE(code);
+    }
+    else if (isExisting)
+    {
+      valueBuffer.ToString(value);
+      return true;
+    }
+    else
+    {
+      return false;
+    }
   }
-
-  bool Queue::PopBack(std::string& value)
-  {
-    return PopInternal(value, OrthancPluginQueueOrigin_Back);
-  }
-
-  bool Queue::PopFront(std::string& value)
-  {
-    return PopInternal(value, OrthancPluginQueueOrigin_Front);
-  }
-
+#endif
+
+
+#if HAS_ORTHANC_PLUGIN_QUEUES == 1
   uint64_t Queue::GetSize()
   {
     uint64_t size = 0;
-    OrthancPluginErrorCode ret = OrthancPluginGetQueueSize(OrthancPlugins::GetGlobalContext(),
-                                                           queueId_.c_str(),
-                                                           &size);
-    if (ret != OrthancPluginErrorCode_Success)
-    {
-#if HAS_ORTHANC_EXCEPTION == 1
-      throw Orthanc::OrthancException(Orthanc::ErrorCode_InternalError, "Unable get queue size");
-#else
-      ORTHANC_PLUGINS_LOG_ERROR("Unable get queue size");
-      ORTHANC_PLUGINS_THROW_EXCEPTION(InternalError);
-#endif
-    }
-
-    return size;
+    OrthancPluginErrorCode code = OrthancPluginGetQueueSize(OrthancPlugins::GetGlobalContext(), queueId_.c_str(), &size);
+
+    if (code != OrthancPluginErrorCode_Success)
+    {
+      ORTHANC_PLUGINS_THROW_PLUGIN_ERROR_CODE(code);
+    }
+    else
+    {
+      return size;
+    }
   }
 #endif
-
 }
diff -r 0ff96222e461 -r 79e9fa2872cf OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h
--- a/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h	Tue May 20 16:48:12 2025 +0200
+++ b/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h	Tue May 20 17:53:14 2025 +0200
@@ -134,6 +134,14 @@
 #  define HAS_ORTHANC_PLUGIN_LOG_MESSAGE  0
 #endif
 
+#if ORTHANC_PLUGINS_VERSION_IS_ABOVE(1, 12, 99)
+#  define HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES  1
+#  define HAS_ORTHANC_PLUGIN_QUEUES            1
+#else
+#  define HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES  0
+#  define HAS_ORTHANC_PLUGIN_QUEUES            0
+#endif
+
 
 // Macro to tag a function as having been deprecated
 #if (__cplusplus >= 201402L)  // C++14
@@ -1619,25 +1627,33 @@
   };
 #endif
 
-#if ORTHANC_PLUGINS_VERSION_IS_ABOVE(1, 12, 99)
 
+#if HAS_ORTHANC_PLUGIN_KEY_VALUE_STORES == 1
   class KeyValueStore : public boost::noncopyable
   {
   private:
     std::string storeId_;
 
   public:
-    KeyValueStore(const std::string& storeId);
+    explicit KeyValueStore(const std::string& storeId) :
+      storeId_(storeId)
+    {
+    }
 
-    void Store(const std::string& key, const std::string& value);
+    void Store(const std::string& key,
+               const std::string& value);
 
-    bool Get(std::string& value, const std::string& key);
+    bool Get(std::string& value,
+             const std::string& key);
 
     void Delete(const std::string& key);
 
     bool GetAllKeys(std::list<std::string>& keys, uint64_t since, uint64_t limit);
   };
+#endif
 
+
+#if HAS_ORTHANC_PLUGIN_QUEUES == 1
   class Queue : public boost::noncopyable
   {
   private:
@@ -1646,17 +1662,24 @@
     bool PopInternal(std::string& value, OrthancPluginQueueOrigin origin);
 
   public:
-    Queue(const std::string& queueId);
+    explicit Queue(const std::string& queueId) :
+      queueId_(queueId)
+    {
+    }
 
     void PushBack(const std::string& value);
 
-    bool PopFront(std::string& value);
+    bool PopBack(std::string& value)
+    {
+      return PopInternal(value, OrthancPluginQueueOrigin_Back);
+    }
 
-    bool PopBack(std::string& value);
+    bool PopFront(std::string& value)
+    {
+      return PopInternal(value, OrthancPluginQueueOrigin_Front);
+    }
 
     uint64_t GetSize();
   };
-
 #endif
-
 }