Loading...
Searching...
No Matches
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.
virtual | ~DcmJsonFormat ()
| Virtual destructor, does nothing.
virtual OFString | newline ()=0
| Method to return line break(s).
virtual OFString | space ()=0
| Method to return whitespace(s).
Indention | indent ()
| Method to return an indention proxy object for increasing, decreasing or printing indention.
virtual OFBool | asBulkDataURI (const DcmTagKey &tag, Uint32 len) const
| Check if an attribute should be exported as BulkDataURI.
virtual void | getBulkDataDirectory (OFString &directory) const
| return path of bulk data directory
virtual void | getBulkDataURIPrefix (OFString &prefix) const
| return the current bulk data URI prefix
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.
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.
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.
virtual void | printInlineBinaryPrefix (STD_NAMESPACE ostream &out)
| Print the Prefix which for JSON InlineBinary needed with indention and newlines as the format specifies.
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.
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.
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.
virtual void | setMinBulkSize (ssize_t min_bulk_size)
| set the minimum size of binary attributes stored as bulk data.
virtual void | setBulkURIPrefix (const char *bulk_uri_prefix)
| set the prefix for URIs generated for bulk data
virtual void | setBulkDir (const char *bulk_dir)
| set the directory to which bulk data files should be written
virtual OFCondition | writeBulkData (STD_NAMESPACE ostream &out, const DcmTagKey &tagkey, Uint32 len, Uint8 *byteValues, const char *extension=".bin")
| write an attribute as BulkDataURI.
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.

## Static Public Member Functions

static void | escapeControlCharacters (STD_NAMESPACE ostream &out, OFString const &value)
| Escapes all forbidden control characters in JSON.
static void | normalizeDecimalString (OFString &value)
| Normalize Decimal String to specific JSON format.
static void | normalizeIntegerString (OFString &value)
| Normalize Integer String to specific JSON format.
static void | printString (STD_NAMESPACE ostream &out, const OFString &value)
| Prints either null if empty or the string value (with all illegal characters escaped).
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).
static void | printNumberInteger (STD_NAMESPACE ostream &out, OFString &value)
| Print either null if empty or a Number as normalized IntegerString.
static void | printNumberDecimal (STD_NAMESPACE ostream &out, OFString &value)
| Print either null if empty or a Number as normalized IntegerDecimal.

## 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.
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".
NumStringPolicy | numStringPolicy
| Option that defines how IS/DS elements will be converted to JSON, as number or string.
ssize_t | minBulkDataSize
| minimum size of binary attributes to be written as bulk data, in kBytes.
OFString | bulkDataURIPrefix
| prefix for bulk data URIs to be generated.
OFString | bulkDataDirectory
| directory to which files for bulk data will be written.

## 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

References bulkDataDirectory, bulkDataURIPrefix, enableJsonExtension, minBulkDataSize, NSP_auto, numStringPolicy, and printMetaheaderInformation.

## 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()

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()

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()

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()

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()

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()

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()

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.

Referenced by DcmJsonFormat().

## bulkDataURIPrefix

OFString DcmJsonFormat::bulkDataURIPrefix

private

prefix for bulk data URIs to be generated.

The filename will be appended to this prefix.

Referenced by DcmJsonFormat().

## 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 DcmJsonFormat(), 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.

Referenced by DcmJsonFormat().

## 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 DcmJsonFormat(), getJsonNumStringPolicy(), and setJsonNumStringPolicy().

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

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

Generated on for DCMTK Version 3.7.0 by Doxygen 1.15.0