DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Private Attributes | List of all members
DcmJsonFormat Class Referenceabstract

Class for handling JSON format options. More...

Inheritance diagram for DcmJsonFormat:

## Classes
class | Indention
| A class to create small proxy objects that ease indention handling. More...

## Public Types
enum | NumStringPolicy { NSP_auto , NSP_always_number , NSP_always_string }
| an enumeration defining how to convert IS/DS elements to JSON More...

## Public Member Functions
| DcmJsonFormat (const OFBool printMetaInfo)
| Constructor. More...
virtual | ~DcmJsonFormat ()
| Virtual destructor, does nothing.
virtual OFString | newline ()=0
| Method to return line break(s) More...
virtual OFString | space ()=0
| Method to return whitespace(s) More...
Indention | indent ()
| Method to return an indention proxy object for increasing, decreasing or printing indention. More...
virtual OFBool | asBulkDataURI (const DcmTagKey &tag, Uint32 len) const
| Check if an attribute should be exported as BulkDataURI. More...
virtual void | getBulkDataDirectory (OFString &directory) const
| return path of bulk data directory More...
virtual void | getBulkDataURIPrefix (OFString &prefix) const
| return the current bulk data URI prefix More...
virtual void | printValuePrefix (STD_NAMESPACE ostream &out)
| Print the Prefix which for JSON Values needed with indention and newlines as in the format Variable given. More...
virtual void | printValueSuffix (STD_NAMESPACE ostream &out)
| Print the Suffix which for JSON Values needed with indention and newlines as in the format Variable given. More...
virtual void | printBulkDataURIPrefix (STD_NAMESPACE ostream &out)
| Print the Prefix which for JSON BulkDataURI needed with indention and newlines as in the format Variable given. More...
virtual void | printInlineBinaryPrefix (STD_NAMESPACE ostream &out)
| Print the Prefix which for JSON InlineBinary needed with indention and newlines as the format specifies. More...
virtual void | printNextArrayElementPrefix (STD_NAMESPACE ostream &out)
| Print the prefix for array elements (except the first one), with indention and newlines as the format specifies. More...
virtual OFBool | getJsonExtensionEnabled () const
| return the flag indicating whether extended JSON number encoding is enabled.
virtual void | setJsonExtensionEnabled (OFBool enabled)
| set the flag indicating whether extended JSON number encoding is enabled. More...
virtual NumStringPolicy | getJsonNumStringPolicy () const
| return the flag defining how IS/DS elements should be converted to JSON.
virtual void | setJsonNumStringPolicy (NumStringPolicy policy)
| set the flag defining how IS/DS elements should be converted to JSON. More...
virtual void | setMinBulkSize (ssize_t min_bulk_size)
| set the minimum size of binary attributes stored as bulk data. More...
virtual void | setBulkURIPrefix (const char *bulk_uri_prefix)
| set the prefix for URIs generated for bulk data More...
virtual void | setBulkDir (const char *bulk_dir)
| set the directory to which bulk data files should be written More...
virtual OFCondition | writeBulkData (STD_NAMESPACE ostream &out, const DcmTagKey &tagkey, Uint32 len, Uint8 *byteValues, const char *extension=".bin")
| write an attribute as BulkDataURI. More...
virtual OFCondition | writeBinaryAttribute (STD_NAMESPACE ostream &out, const DcmTagKey &tagkey, Uint32 len, Uint8 *byteValues, const char *extension=".bin")
| write a binary attribute either as InlineBinary or as BulkDataURI. More...

## Static Public Member Functions
static void | escapeControlCharacters (STD_NAMESPACE ostream &out, OFString const &value)
| Escapes all forbidden control characters in JSON. More...
static void | normalizeDecimalString (OFString &value)
| Normalize Decimal String to specific JSON format. More...
static void | normalizeIntegerString (OFString &value)
| Normalize Integer String to specific JSON format. More...
static void | printString (STD_NAMESPACE ostream &out, const OFString &value)
| Prints either null if empty or the string value (with all illegal characters escaped). More...
static void | printValueString (STD_NAMESPACE ostream &out, const OFString &value)
| Prints either null if empty or a quoted string (with leading and ending quotation marks and all illegal characters escaped). More...
static void | printNumberInteger (STD_NAMESPACE ostream &out, OFString &value)
| Print either null if empty or a Number as normalized IntegerString. More...
static void | printNumberDecimal (STD_NAMESPACE ostream &out, OFString &value)
| Print either null if empty or a Number as normalized IntegerDecimal. More...

## Public Attributes
const OFBool | printMetaheaderInformation
| Option that defines if metaheader information should be printed.

## Protected Member Functions
virtual void | printIndention (STD_NAMESPACE ostream &out)=0
| Indent to the specific level. More...
virtual void | increaseIndention ()=0
| Used for increasing the indention level.
virtual void | decreaseIndention ()=0
| Used for decreasing the indention level.

## Private Attributes
OFBool | enableJsonExtension
| Option that defines if the inofficial JSON extension should be permitted under which decimal numbers may have the values "-inf", "inf" or "nan". More...
NumStringPolicy | numStringPolicy
| Option that defines how IS/DS elements will be converted to JSON, as number or string. More...
ssize_t | minBulkDataSize
| minimum size of binary attributes to be written as bulk data, in kBytes. More...
OFString | bulkDataURIPrefix
| prefix for bulk data URIs to be generated. More...
OFString | bulkDataDirectory
| directory to which files for bulk data will be written. More...

## Detailed Description

Class for handling JSON format options.

Base class to implement custom formatting. Purpose:

- individual output formatting
- normalization of DecimalString and IntegerString e.g. normalization of leading zeros
- escaping of special JSON control characters
- outputting the correct indention and symbols for "Value", "BulkDataURI", etc.

### Usage Example:

#include "dcmtk/dcmdata/dcjson.h"
// ...
DcmFileFormat fileformat;
if(fileformat.loadFile("test.dcm").good())
{
// print the DICOM file in JSON format
// using the pretty format (muti-line with indention and other whitespace)
fileformat.writeJson(COUT, DcmJsonFormatPretty(OFTrue));
// using the compact (single line, without unneeded whitespace) format
fileformat.writeJson(COUT, DcmJsonFormatCompact(OFTrue));
}
DcmFileFormat
a class handling the DICOM file format (with meta header)
Definition: dcfilefo.h:42
DcmFileFormat::writeJson
virtual OFCondition writeJson(STD_NAMESPACE ostream &out, DcmJsonFormat &format)
write object in JSON format.
DcmFileFormat::loadFile
virtual OFCondition loadFile(const OFFilename &fileName, const E_TransferSyntax readXfer=EXS_Unknown, const E_GrpLenEncoding groupLength=EGL_noChange, const Uint32 maxReadLength=DCM_MaxReadLength, const E_FileReadMode readMode=ERM_autoDetect)
load object from a DICOM file.
DcmJsonFormatCompact
Subclass for handling JSON formatted output.
Definition: dcjson.h:492
DcmJsonFormatPretty
Subclass for handling JSON formatted output.
Definition: dcjson.h:452
OFCondition::good
OFBool good() const
check if the status is OK.
Definition: ofcond.h:313

### Implementing a custom formatter:

struct CustomJsonFormat : DcmJsonFormatPretty
{
CustomJsonFormat(const OFBool printMetaInfo = OFTrue)
: DcmJsonFormatPretty(printMetaInfo)
{
}
OFString OFJsonFormatExample::space()
{
// use tabstops instead of spaces for indention
return "\t";
}
}
OFString
a simple string class that implements a subset of std::string.
Definition: ofstring.h:76

## Member Enumeration Documentation

## ◆ NumStringPolicy

enum DcmJsonFormat::NumStringPolicy

an enumeration defining how to convert IS/DS elements to JSON

Enumerator
NSP_auto | write as number if possible (i.e. the value is a valid JSON number), as string otherwise.
NSP_always_number | always write as JSON number, fail with an error code if the value is not a valid JSON number
NSP_always_string | always write as JSON string

## Constructor & Destructor Documentation

## ◆ DcmJsonFormat()

DcmJsonFormat::DcmJsonFormat | ( | const OFBool | printMetaInfo | ) |
| inline

Constructor.

Parameters

  printMetaInfo | parameter that defines if meta information should be written

## Member Function Documentation

## ◆ asBulkDataURI()

virtual OFBool DcmJsonFormat::asBulkDataURI | ( | const DcmTagKey & | tag,
|  | Uint32 | len
| ) |  | const
| virtual

Check if an attribute should be exported as BulkDataURI.

Override this function to implement bulk data URI output.

Parameters

  tag | the tag of the attribute being printed, for letting the implementation decide how to handle it.
  len | the length of the attribute value, in bytes

Returns
  OFTrue if yes, OFFalse if no.

## ◆ escapeControlCharacters()

static void DcmJsonFormat::escapeControlCharacters | ( | STD_NAMESPACE ostream & | out,
|  | OFString const & | value
| ) |  |
| static

Escapes all forbidden control characters in JSON.

Parameters

  out | output stream to which the escaped String is written
  value | String that should be escaped

## ◆ getBulkDataDirectory()

virtual void DcmJsonFormat::getBulkDataDirectory | ( | OFString & | directory | ) | const
| virtual

return path of bulk data directory

Parameters

  directory | path returned in this parameter

## ◆ getBulkDataURIPrefix()

virtual void DcmJsonFormat::getBulkDataURIPrefix | ( | OFString & | prefix | ) | const
| virtual

return the current bulk data URI prefix

Returns
  prefix current bulk data URI prefix returned in this parameter

## ◆ indent()

Indention DcmJsonFormat::indent | ( |  | ) |
| inline

Method to return an indention proxy object for increasing, decreasing or printing indention.

Returns
  an indention proxy object.

## ◆ newline()

virtual OFString DcmJsonFormat::newline | ( |  | ) |
| pure virtual

Method to return line break(s)

Returns
  line break(s).

Implemented in DcmJsonFormatCompact, and DcmJsonFormatPretty.

## ◆ normalizeDecimalString()

static void DcmJsonFormat::normalizeDecimalString | ( | OFString & | value | ) |
| static

Normalize Decimal String to specific JSON format.

remove leading zeros, except before dot. Example:

00.123 --> 0.123
023.12 --> 23.12
-01.00 --> -1.00
0200 --> 200
.12 --> 0.12
000.1 --> 0.1

Parameters

  value | String that should be normalize

## ◆ normalizeIntegerString()

static void DcmJsonFormat::normalizeIntegerString | ( | OFString & | value | ) |
| static

Normalize Integer String to specific JSON format.

remove leading zeros, except before dot. Example:

000 --> 0
023 --> 23
-01 --> -1
0200 --> 200

Parameters

  value | String that should be normalize

## ◆ printBulkDataURIPrefix()

virtual void DcmJsonFormat::printBulkDataURIPrefix | ( | STD_NAMESPACE ostream & | out | ) |
| virtual

Print the Prefix which for JSON BulkDataURI needed with indention and newlines as in the format Variable given.

Example:

,"BulkDataURI":

Parameters

  out | output stream to which the Value prefix is written

## ◆ printIndention()

virtual void DcmJsonFormat::printIndention | ( | STD_NAMESPACE ostream & | out | ) |
| protected pure virtual

Indent to the specific level.

Parameters

  out | output stream to which the indention is written.

Implemented in DcmJsonFormatCompact, and DcmJsonFormatPretty.

## ◆ printInlineBinaryPrefix()

virtual void DcmJsonFormat::printInlineBinaryPrefix | ( | STD_NAMESPACE ostream & | out | ) |
| virtual

Print the Prefix which for JSON InlineBinary needed with indention and newlines as the format specifies.

Example:

,"InlineBinary":

Parameters

  out | output stream to which the Value prefix is written

## ◆ printNextArrayElementPrefix()

virtual void DcmJsonFormat::printNextArrayElementPrefix | ( | STD_NAMESPACE ostream & | out | ) |
| virtual

Print the prefix for array elements (except the first one), with indention and newlines as the format specifies.

Example:

Example,\n
Example...

Parameters

  out | output stream to which the Value prefix is written

## ◆ printNumberDecimal()

static void DcmJsonFormat::printNumberDecimal | ( | STD_NAMESPACE ostream & | out,
|  | OFString & | value
| ) |  |
| static

Print either null if empty or a Number as normalized IntegerDecimal.

Parameters

  out | output stream to which the Value prefix is written
  value | String that should be printed

## ◆ printNumberInteger()

static void DcmJsonFormat::printNumberInteger | ( | STD_NAMESPACE ostream & | out,
|  | OFString & | value
| ) |  |
| static

Print either null if empty or a Number as normalized IntegerString.

Parameters

  out | output stream to which the Value prefix is written
  value | String that should be printed

## ◆ printString()

static void DcmJsonFormat::printString | ( | STD_NAMESPACE ostream & | out,
|  | const OFString & | value
| ) |  |
| static

Prints either null if empty or the string value (with all illegal characters escaped).

Parameters

  out | output stream to which the Value prefix is written
  value | String that should be printed

## ◆ printValuePrefix()

virtual void DcmJsonFormat::printValuePrefix | ( | STD_NAMESPACE ostream & | out | ) |
| virtual

Print the Prefix which for JSON Values needed with indention and newlines as in the format Variable given.

Example:

,"Value":[

Parameters

  out | output stream to which the Value prefix is written

## ◆ printValueString()

static void DcmJsonFormat::printValueString | ( | STD_NAMESPACE ostream & | out,
|  | const OFString & | value
| ) |  |
| static

Prints either null if empty or a quoted string (with leading and ending quotation marks and all illegal characters escaped).

Parameters

  out | output stream to which the Value prefix is written
  value | String that should be printed

## ◆ printValueSuffix()

virtual void DcmJsonFormat::printValueSuffix | ( | STD_NAMESPACE ostream & | out | ) |
| virtual

Print the Suffix which for JSON Values needed with indention and newlines as in the format Variable given.

Example:

]\n

Parameters

  out | output stream to which the Value prefix is written

## ◆ setBulkDir()

virtual void DcmJsonFormat::setBulkDir | ( | const char * | bulk_dir | ) |
| virtual

set the directory to which bulk data files should be written

Parameters

  bulk_dir | directory for bulk data files, must exist and be writable

## ◆ setBulkURIPrefix()

virtual void DcmJsonFormat::setBulkURIPrefix | ( | const char * | bulk_uri_prefix | ) |
| virtual

set the prefix for URIs generated for bulk data

Parameters

  bulk_uri_prefix | URI prefix string

## ◆ setJsonExtensionEnabled()

virtual void DcmJsonFormat::setJsonExtensionEnabled | ( | OFBool | enabled | ) |
| inline virtual

set the flag indicating whether extended JSON number encoding is enabled.

Parameters

  enabled | new value of the flag

References enableJsonExtension.

## ◆ setJsonNumStringPolicy()

virtual void DcmJsonFormat::setJsonNumStringPolicy | ( | NumStringPolicy | policy | ) |
| inline virtual

set the flag defining how IS/DS elements should be converted to JSON.

Parameters

  policy | new value of the flag

References numStringPolicy.

## ◆ setMinBulkSize()

virtual void DcmJsonFormat::setMinBulkSize | ( | ssize_t | min_bulk_size | ) |
| virtual

set the minimum size of binary attributes stored as bulk data.

Parameters

  min_bulk_size | minimum bulk data size in kBytes, negative number for no bulk data

## ◆ space()

virtual OFString DcmJsonFormat::space | ( |  | ) |
| pure virtual

Method to return whitespace(s)

Returns
  whitespace(s).

Implemented in DcmJsonFormatCompact, and DcmJsonFormatPretty.

## ◆ writeBinaryAttribute()

virtual OFCondition DcmJsonFormat::writeBinaryAttribute | ( | STD_NAMESPACE ostream & | out,
|  | const DcmTagKey & | tagkey,
|  | Uint32 | len,
|  | Uint8 * | byteValues,
|  | const char * | extension = `".bin"`
| ) |  |
| virtual

write a binary attribute either as InlineBinary or as BulkDataURI.

Parameters

  out | output stream
  tagkey | tag key of the attribute
  len | length of the attribute value
  byteValues | pointer to the raw attribute value in little endian byte order
  extension | file name extension

Returns
  EC_Normal if successful, an error code otherwise

## ◆ writeBulkData()

virtual OFCondition DcmJsonFormat::writeBulkData | ( | STD_NAMESPACE ostream & | out,
|  | const DcmTagKey & | tagkey,
|  | Uint32 | len,
|  | Uint8 * | byteValues,
|  | const char * | extension = `".bin"`
| ) |  |
| virtual

write an attribute as BulkDataURI.

Parameters

  out | output stream
  tagkey | tag key of the attribute
  len | length of the attribute value
  byteValues | pointer to the raw attribute value in little endian byte order
  extension | file name extension

Returns
  EC_Normal if successful, an error code otherwise

## Member Data Documentation

## ◆ bulkDataDirectory

OFString DcmJsonFormat::bulkDataDirectory
| private

directory to which files for bulk data will be written.

Must exist and be writable.

## ◆ bulkDataURIPrefix

OFString DcmJsonFormat::bulkDataURIPrefix
| private

prefix for bulk data URIs to be generated.

The filename will be appended to this prefix.

## ◆ enableJsonExtension

OFBool DcmJsonFormat::enableJsonExtension
| private

Option that defines if the inofficial JSON extension should be permitted under which decimal numbers may have the values "-inf", "inf" or "nan".

Default is OFFalse, in which case such values will lead to an error code being returned instead.

Referenced by getJsonExtensionEnabled(), and setJsonExtensionEnabled().

## ◆ minBulkDataSize

ssize_t DcmJsonFormat::minBulkDataSize
| private

minimum size of binary attributes to be written as bulk data, in kBytes.

A negative value means that no bulk data is written.

## ◆ numStringPolicy

NumStringPolicy DcmJsonFormat::numStringPolicy
| private

Option that defines how IS/DS elements will be converted to JSON, as number or string.

Default is NSP_auto.

Referenced by getJsonNumStringPolicy(), and setJsonNumStringPolicy().

The documentation for this class was generated from the following file:

- dcmdata/include/dcmtk/dcmdata/dcjson.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1