Added helper function OFstub_main.

Added a helper function for an command line application stub that
calls another command line tool in the same directory and forwards
all environment variables, command line parameters and standard I/O streams
and returns the return code of the called tool. This can be used to
easily implement forwarding stubs for deprecated tools that have been
replaced by a tool that supports the same command line options.

COPYRIGHT

@@ -847,6 +847,41 @@ WTFPL v2 and MIT licenses. The MIT license is reproduced here:
 
 ---------------------------------------------------------------------------
 
+The implementation of the argvToCommandLine() function in ofstub.cc
+is derived from an implementation with the following license:
+
+// The function argvToCommandLine() is derived from an implementation
+// with the following copyright statement:
+//
+// Copyright (c) 2011-2015 Ryan Prichard
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+
+
+---------------------------------------------------------------------------
+
+The implementation of the getLastErrorString() function in ofstub.cc
+is derived from an implementation by Orjan Westin published under
+the BSD license (without further specification).
+
+---------------------------------------------------------------------------
+
 Finally, DCMTK can be configured and compiled to make use of a number of
 optional external libraries that, when available, provide added functionality
 such as compression, encryption, or support for certain image formats.

config/docs/macros.txt

@@ -130,6 +130,16 @@ DCMTK_MERGE_STDERR_TO_STDOUT
     compiling with this macro.  In this case, DICOM files should never be
     written to stdout as this will be unreliable.
 
+DCMTK_USE_OFLOG_LOGGER_IN_STUB
+  Affected: ofstd
+  Type of modification: Selects implementation variant
+  Explanation: The command line application stub defined in ofstub.h that
+    calls another command line tool and forwards the command line option
+    by default prints error messages and warnings to stderr. When compiling
+    with this macro defined, the messages are printed to the oflog logger
+    instead, which, however, increases the executable size and slows down
+    execution a bit.
+
 DCMTK_USE_UNIX_SOCKET_QUEUE
   Affected: ofstd
   Type of modification: Selects implementation variant

ofstd/include/dcmtk/ofstd/ofstub.h

@@ -0,0 +1,47 @@
+/*
+ *
+ *  Copyright (C) 2024, OFFIS e.V.
+ *  All rights reserved.  See COPYRIGHT file for details.
+ *
+ *  This software and supporting documentation were developed by
+ *
+ *    OFFIS e.V.
+ *    R&D Division Health
+ *    Escherweg 2
+ *    D-26121 Oldenburg, Germany
+ *
+ *
+ *  Module:  dcmimage
+ *
+ *  Authors: Marco Eichelberg
+ *
+ *  Purpose: Main function for a proxy stub that simply calls another
+ *   command line tool and forwards environment, command line arguments,
+ *   standard I/O streams, and return code.
+ *
+ */
+
+#ifndef OFSTUB_H
+#define OFSTUB_H
+
+#include "dcmtk/config/osconfig.h"   /* make sure OS specific configuration is included first */
+#include "dcmtk/ofstd/ofdefine.h"    /* for DCMTK_OFSTD_EXPORT */
+
+/** main function to be called in a command line stub application that
+ *  calls another command line tool located in the same directory
+ *  and forwards all command line parameters, all environment variables,
+ *  and the standard I/O stream to that command line tool.
+ *  @param argc number of command line parameters as passed to main(), must be > 0
+ *  @param argv array of command line parameters as passed to main()
+ *  @param stubName name of the stub command line tool
+ *  @param appName name of the real command line tool to be called
+ *  @return value to be returned from main(). If the command line tool given as appName
+ *    cannot be executed, returns an error code. Otherwise, on Posix platform, this
+ *    function will never returns, as it calls execve(). The calling process will instead
+ *    receive the return code of the callled tool. On Windows, the function will wait
+ *    until the child process terminates and will then return the child process's
+ *    return code. In any case, the stub can simply return the result of this function.
+ */
+DCMTK_OFSTD_EXPORT int OFstub_main(int argc, char** argv, const char *stubName, const char *appName);
+
+#endif // #ifndef OFSTUB_H

ofstd/libsrc/CMakeLists.txt

@@ -28,6 +28,7 @@ DCMTK_ADD_LIBRARY(ofstd
   ofsockad.cc
   ofrand.cc
   ofwhere.c
+  ofstub.cc
 )
 
 DCMTK_TARGET_LINK_LIBRARIES(ofstd config ${CHARSET_CONVERSION_LIBS} ${SOCKET_LIBS} ${THREAD_LIBS} ${WIN32_STD_LIBRARIES})

ofstd/libsrc/Makefile.in

@@ -20,7 +20,8 @@ LOCALDEFS =
 objs = oflist.o ofstring.o ofcmdln.o ofconapp.o offname.o ofconsol.o ofthread.o \
 	ofcond.o ofstd.o ofcrc32.o ofdate.o oftime.o ofdatime.o oftimer.o \
 	ofconfig.o ofchrenc.o oftempf.o ofxml.o ofuuid.o offile.o offilsys.o \
-	ofmath.o oferror.o ofsockad.o ofrand.o ofstrutl.o ofipc.o ofwhere.o
+	ofmath.o oferror.o ofsockad.o ofrand.o ofstrutl.o ofipc.o ofwhere.o \
+    ofstub.o
 
 library = libofstd.$(LIBEXT)
 
@@ -46,6 +47,6 @@ distclean:
 
 
 dependencies:
-	$(CXX) -MM $(defines) $(includes) $(CPPFLAGS) $(CXXFLAGS) *.cc *.c > $(DEP)
+	$(CXX) -MM $(defines) $(includes) $(CPPFLAGS) $(CXXFLAGS) *.cc  > $(DEP)
 
 include $(DEP)