C/C++ Plugin: ReceivedInstanceFilter

[Luiz Eduardo Guida Valmont]

Hi all!

I'd like to ask for comments and/or constructive criticism on a patch/wip for 1.3.2 I've been working on these past couple of days. Files and instructions on how to run it shall follow at the end of this message.

[please, a thousand appologies because this e-mail ended up being way longer than I anticipated]

As per Sébastien's suggestion in this post, we're looking into possibly developing a polling system so failed steps of our routing can be tried again. It'll basically register images as they come and make sure they follow the transcode/transmit steps.

Its very first interface, the one that registers images locally, is exposed as a Rest API and will be accessed by a plugin. To avoid further complications, OnStoredInstance was dropped in favour of the ReceivedInstanceFilter callback. This way, if Orthanc cannot communicate with the polling system (eg. it's offline for whatever reason), it simply returns false. We won't have to worry about deleting the incoming image from Orthanc then, as would be the case with OnStoredInstance.

We're coding it in C/C++ because of the available libraries and how we can leverage its power in the context of the solution.

But, as of 1.3.2 (and latest on bitbucket), there's no way to code a plugin for that. OrhtancPlugins::FilterIncomingInstance simply returns true. Or maybe I failed miserably at finding the right hooks.

That's where the whole patching comes into play. Because there's a TODO ("Enable filtering of instances from plugins"), I've taken the liberty to try and do it myself.

So basically the OnStoredInstance related functions, hooks, reinterpret_cast's, etc... they were taken as a starting point and a new callback was created:

  typedef OrthancPluginErrorCode (*OrthancPluginReceivedInstanceFilterCallback) (
    const OrthancPluginDicomInstance* instance,
    const char* originName,
    bool& isAcceptedInstance);

Images are accepted by default. To reject an image, set isAcceptedInstance to false. You should return OrthancPluginErrorCode_Success if nothing goes wrong. As with other callbacks, the new ones are registered through the OrthancPluginRegisterReceivedInstanceFilterCallback(context, callback) function.

[insert grin] I know the originName parameter is more complex then that and I'll be coding a small hierarchy to support the origin parameter in a more object oriented way in the coming days. I just wanted to get a POC going quickly. Oh, and there's formatting to be standardized as well.

Hopefully nothing wrong was done and I was clear on what was done (and why). But since this is my very first serious patch on an open source project, I'd like to hear from the more experienced (that's basically everyone). What are your opinions? What would you do differently? Is it supposed to be done some other way?

Thanks in advance!

--- INSTRUCTIONS ON HOW TO COMPILE AND RUN ---

Please download file Orthanc-1.3.2-FilterIncomingInstance.tar.bz2 at: https://drive.google.com/file/d/1OPj7GKOZzoBIoMdTR_dcLn0bjIQr34rA/view?usp=sharing

# sample configuration was written to point to /tmp

# to make things easier

# that's why we unpack it to /tmp

$ cd /tmp

$ tar xvf <PATH-TO>/Orthanc-1.3.2-FilterIncomingInstance.tar.gz
$ zcat cplugin-FilterIncomingInstance-1.3.2.patch.gz | patch -p0
$ cd Orthanc-1.3.2/
$ mkdir build
$ cd build

# this is how I compile, YMMV, so hit me an email should you need help

#

$ cmake -DUSE_GOOGLE_TEST_DEBIAN_PACKAGE=ON -DSYSTEM_MONGOOSE_USE_CALLBACKS=OFF ..

$ make

# the sample plugin that's configured in the provided orthanc.json

#

$ cd ../Plugins/Samples/RejectIncomingInstances/
$ mkdir build
$ cd build
$ cmake ..
$ make

# run Orthanc

#

$ cd /tmp/Orthanc-1.3.2/build
$ ./Orthanc /tmp/orthanc.json

---

By this point you'll have a running Orthanc on port 8042 that will not accept any image because of a C/C++ plugin. Username/password for the web / rest interface is orthanc/orthanc.

Have a good one!

Luiz

[Sébastien Jodogne]

Dear Luiz,

I'm really sorry, but I don't understand this thread.

The only difference between your "Orthanc-1.3.2-FilterIncomingInstance.tar.bz2" and the Orthanc 1.3.2 source distribution is a new folder "./Plugins/Sample/RejectIncomingInstances".

You are visibly trying to contribute by creating a new plugin, which is great. However, there is no need to embed your plugin inside the Orthanc source distribution. Just create a separate repository (e.g. on GitHub or BitBucket), place your code there, warn other users on this discussion group once it's ready, and we'll update the dedicated section of the Orthanc Book:

http://book.orthanc-server.com/plugins.html#plugins-contributed

HTH,

Sébastien-

[Luiz Eduardo Guida Valmont]

Good afternoon, Sébastien!

It's ok. The other e-mail was fairly extensive and I probably failed at being clear.

In the referenced tar.bz2 is a patch which I'm attaching to this e-mail. Its changes are centered in the following file, referenced from Orthanc's bitbucket:

https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Engine/OrthancPlugins.h

Lines 226-230:

virtual bool FilterIncomingInstance(const DicomInstanceToStore& instance,

const Json::Value& simplified)

{

return true; // TODO Enable filtering of instances from plugins

}

It all started when I found this file while studying the source code. Because of this, one cannot create a C/C++ ReceivedInstanceFilter just like you can in Lua.

But by patching 1.3.2 with the attached file, you can. Well, I came to change the function signature, but that's for another day.

Hopefully, the confusion has been cleared by now. Let me know if there's anything else I can do to further clarify things.

Thanks! =)

--

Luiz Valmont

http://luizvalmont.com