DICOM dataSet & tags classes

Introduction

This section describes the classes and methods responsible for storing, retrieving and setting the information that composes the DICOM structure, represented by the class DataSet.

The following classes are described in this chapter:

C++ class	Objective-C/Swift class	Description
imebra::DataSet	ImebraDataSet	An immutable DICOM structure
imebra::MutableDataSet	ImebraMutableDataSet	Mutable DICOM structure
imebra::Tag	ImebraTag	A single immutable DICOM tag
imebra::MutableTag	ImebraMutableTag	A single mutable DICOM tag
imebra::TagId	ImebraTagId	Identifies a tag
imebra::ReadingDataHandler	ImebraReadingDataHandler	Read data from a tag
imebra::ReadingDataHandlerNumeric	ImebraReadingDataHandlerNumeric	Read data from a numeric tag
imebra::WritingDataHandler	ImebraWritingDataHandler	Write into a tag
imebra::WritingDataHandlerNumeric	ImebraWritingDataHandlerNumeric	Write into a numeric tag
imebra::Date	ImebraDate	Stores a DICOM date/time
imebra::Age	ImebraAge	Stores a DICOM Age
imebra::PatientName	ImebraPatientName	Stores a patient name
imebra::UnicodePatientName		Stores a patient name (unicode)

Class diagram of the data related classes

DataSet is a collection of Tag objects. Each Tag is identified by a TagId.

DataSet and MutableDataSet supply several functions that allow to easily read and write the value of the tags. However when advanced functionalities are needed (e.g. when writing several items in one tag that accepts more than one value) then the classes ReadingDataHandler, ReadingDataHandlerNumeric, WritingDataHandler and WritingDataHandlerNumeric should be used.

The difference between ReadingDataHandlerNumeric and ReadingDataHandler (and between WritingDataHandlerNumeric and WritingDataHandler) is that the ‘XXXNumeric’ counterpart supplies functions to access the underlying memory buffer that stores the data, allowing fast processing when dealing with images and large collections of data.

Data storage

DataSet

C++

class DataSet

This class represents a DICOM dataset.

The information it contains is organized into groups and each group may contain several tags.

You can create a DataSet from a DICOM file by using the CodecFactory::load() function:

In C++:

using namespace imebra;
DataSet dataSet = CodecFactory::load("/path/to/file");

In Java:

com.imebra.DataSet dataSet = com.imebra.CodecFactory.load("/path/to/file");

To retrieve the DataSet’s content, use one of the following methods which give direct access to the tags’ values:

• getImage()

• getImageApplyModalityTransform()

• getSequenceItem()

• getInt64()

• getUInt64()

• getInt32()

• getUint32()

• getInt16()

• getUint16()

• getInt8()

• getUint8()

• getDouble()

• getFloat()

• getString()

• getUnicodeString()

• getAge()

• getDate()

In alternative, you can first retrieve a ReadingDataHandler with getReadingDataHandler() and then access the tag’s content via the handler.

If you want to modify the dataset, use MutableDataSet instead.

Subclassed by imebra::MutableDataSet

Public Functions

DataSet(const DataSet &source)

Copy constructor.

Parameters

• source: the source data set

virtual ~DataSet()

Destructor.

tagsIds_t getTags() const

Returns a list of all the tags stored in the DataSet, ordered by group and tag ID.

Return

an ordered list of the stored Tags

const Tag getTag(const TagId &tagId) const

Retrieve the Tag with the specified ID.

Return

the Tag with the specified ID

Parameters

• tagId: the ID of the tag to retrieve

const Image getImage(size_t frameNumber) const

Retrieve an image from the dataset.

Images should be retrieved in order (first frame 0, then frame 1, then frame 2 and so on). Images can be retrieved also in random order but this introduces performance penalties.

Throws DataSetImageDoesntExistError if the requested frame does not exist.

Note

Images retrieved from the DataSet should be processed by the ModalityVOILUT transform, which converts the modality-specific pixel values to values that the application can understand. Consider using getImageApplyModalityTransform() to retrieve the image already processed by ModalityVOILUT.

Return

an Image object containing the decompressed image

Parameters

• frameNumber: the frame to retrieve (the first frame is 0)

const Overlay getOverlay(size_t overlayNumber) const

Retrieve one of the DICOM overlays.

Throws MissingGroupError if the requested overlay does not exist.

Return

the requested overlay

Parameters

• overlayNumber: the number of the overlay to retrieve (0…127)

const Image getImageApplyModalityTransform(size_t frameNumber) const

Retrieve an image from the dataset and if necessary process it with ModalityVOILUT before returning it.

Images should be retrieved in order (first frame 0, then frame 1, then frame 2 and so on). Images can be retrieved also in random order but this introduces performance penalties.

Throws DataSetImageDoesntExistError if the requested frame does not exist.

Return

an image object containing the decompressed image processed with ModalityVOILUT

Parameters

• frameNumber: the frame to retrieve (the first frame is 0)

vois_t getVOIs() const

Return the list of VOI settings stored in the DataSet.

Each VOI setting includes the center & width values that can be used with the VOILUT transform to highlight different parts of an Image.

If the VOI/LUT information is stored in a functional group, then first use getFunctionalGroupDataSet() to retrieve the sequence item containing the VOI/LUT information, then call getVOIs() on the returned dataset.

Return

a list of VOIDescription objects defined in the DataSet

const DataSet getFunctionalGroupDataSet(size_t frameNumber) const

In case the dataset uses functional groups to store imaging information, then this method returns the sequence item containing imaging information for a specific frame.

The method looks first for a frame specific functional group sequence item, then for a common functional group sequence item if the specific one is missing.

Throws MissingTagError or MissingGroupError or MissingItemError if the functional group sequence item is not present.

Return

the functional group sequence item for the requested frame.

Parameters

• frameNumber: the frame number for which the functional group sequence item is required

StreamReader getStreamReader(const TagId &tagId, size_t bufferId) const

Get a StreamReader connected to a tag buffer’s data.

Return

the StreamReader connected to the buffer’s data.

Parameters

• tagId: the tag’s id for which the StreamReader is requested

• bufferId: the id of the buffer for which the StreamReader is required. This parameter is usually 0

const DataSet getSequenceItem(const TagId &tagId, size_t itemId) const

Retrieve a sequence item stored in a tag.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the DataSet does not contain the specified sequence item then throws MissingGroupError, MissingTagError or MissingItemError.

Return

the requested sequence item

Parameters

• tagId: the tag’s id containing the sequence item

• itemId: the sequence item to retrieve. The first item has an Id = 0

const LUT getLUT(const TagId &tagId, size_t itemId) const

Retrieve a LUT stored in a sequence item.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the DataSet does not contain the specified sequence item then throws MissingGroupError, MissingTagError or MissingItemError.

Return

the LUT stored in the requested sequence item

Parameters

• tagId: the tag’s id containing the sequence that stores the LUTs

• itemId: the sequence item to retrieve. The first item has an Id = 0

ReadingDataHandler getReadingDataHandler(const TagId &tagId, size_t bufferId) const

Retrieve a ReadingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified buffer item then throws MissingBufferError.

Return

a ReadingDataHandler object connected to the requested Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

ReadingDataHandlerNumeric getReadingDataHandlerNumeric(const TagId &tagId, size_t bufferId) const

Retrieve a getReadingDataHandlerNumeric object connected to a specific tag’s numeric buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified buffer item then throws MissingBufferError.

Return

a ReadingDataHandlerNumeric object connected to the requested Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

ReadingDataHandlerNumeric getReadingDataHandlerRaw(const TagId &tagId, size_t bufferId) const

Retrieve a getReadingDataHandlerNumeric object connected to a specific tag’s buffer, no matter what the tag’s data type.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then throws MissingTagError or MissingGroupError.

If the specified Tag does not contain the specified buffer item then throws MissingBufferError.

Return

a ReadingDataHandlerNumeric object connected to the requested Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

bool bufferExists(const TagId &tagId, size_t bufferId) const

Check if the specified tag and tag’s buffer exist.

Return

true if the specified tag and tag’s buffer exist, false otherwise

std::int64_t getInt64(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as signed long integer (64 bit).

If the tag’s value cannot be converted to a signed integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a signed 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::int32_t getInt32(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as signed integer (32 bit).

If the tag’s value cannot be converted to a signed integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a signed 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::int32_t getSignedLong(const TagId &tagId, size_t elementNumber) const

Deprecated. Use getInt32() instead.

std::int64_t getInt64(const TagId &tagId, size_t elementNumber, std::int64_t defaultValue) const

Retrieve a tag’s value as signed long integer (64 bit).

If the tag’s value cannot be converted to a signed integer then throws DataHandlerConversionError.

If the specified Tag does not exist or it does not contain the specified buffer then returns the default value specified in the parameter.

Return

the tag’s value as a signed 32 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::int32_t getInt32(const TagId &tagId, size_t elementNumber, std::int32_t defaultValue) const

Retrieve a tag’s value as signed integer (32 bit).

If the tag’s value cannot be converted to a signed integer then throws DataHandlerConversionError.

If the specified Tag does not exist or it does not contain the specified buffer then returns the default value specified in the parameter.

Return

the tag’s value as a signed 32 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::int32_t getSignedLong(const TagId &tagId, size_t elementNumber, std::int32_t defaultValue) const

Deprecated. Use getInt32() instead.

std::uint64_t getUint64(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as unsigned long integer (64 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::uint32_t getUint32(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as unsigned integer (32 bit).

When calling getUint32() on an AT tag (Attribute Tag) then the tag group is always in the high word of the returned value.

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::uint32_t getUnsignedLong(const TagId &tagId, size_t elementNumber) const

Deprecated. Use getUint32() instead.

std::uint64_t getUint64(const TagId &tagId, size_t elementNumber, std::uint64_t defaultValue) const

Retrieve a tag’s value as unsigned long integer (64 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as an unsigned 32 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::uint32_t getUint32(const TagId &tagId, size_t elementNumber, std::uint32_t defaultValue) const

Retrieve a tag’s value as unsigned integer (32 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as an unsigned 32 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::uint32_t getUnsignedLong(const TagId &tagId, size_t elementNumber, std::uint32_t defaultValue) const

Deprecated. Use getUint32() instead.

std::int16_t getInt16(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as signed integer (16 bit).

If the tag’s value cannot be converted to a signed integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a signed 16 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::int16_t getInt16(const TagId &tagId, size_t elementNumber, std::int16_t defaultValue) const

Retrieve a tag’s value as signed integer (16 bit).

If the tag’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

If the specified Tag does not exist or it does not contain the specified buffer then returns the default value specified in the parameter.

Return

the tag’s value as a signed 16 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::uint16_t getUint16(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as unsigned integer (16 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as an unsigned 16 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::uint16_t getUint16(const TagId &tagId, size_t elementNumber, std::uint16_t defaultValue) const

Retrieve a tag’s value as unsigned integer (16 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as an unsigned 16 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::int8_t getInt8(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as signed integer (8 bit).

If the tag’s value cannot be converted to a signed integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a signed 8 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::int8_t getInt8(const TagId &tagId, size_t elementNumber, std::int8_t defaultValue) const

Retrieve a tag’s value as signed integer (8 bit).

If the tag’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

If the specified Tag does not exist or it does not contain the specified buffer then returns the default value specified in the parameter.

Return

the tag’s value as a signed 8 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::uint8_t getUint8(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as unsigned integer (8 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as an unsigned 8 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::uint8_t getUint8(const TagId &tagId, size_t elementNumber, std::uint8_t defaultValue) const

Retrieve a tag’s value as unsigned integer (8 bit).

If the tag’s value cannot be converted to an unsigned integer then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as an unsigned 8 bit integer, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

double getDouble(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a 64 bit floating point.

If the tag’s value cannot be converted to a floating point value then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a 64 bit floating point

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

float getFloat(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a 32 bit floating point.

If the tag’s value cannot be converted to a floating point value then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a 32 bit floating point

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

double getDouble(const TagId &tagId, size_t elementNumber, double defaultValue) const

Retrieve a tag’s value as a 64 bit floating point.

If the tag’s value cannot be converted to a floating point value then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as a 64 bit floating point, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

float getFloat(const TagId &tagId, size_t elementNumber, float defaultValue) const

Retrieve a tag’s value as a 32 bit floating point.

If the tag’s value cannot be converted to a floating point value then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as a 32 bit floating point, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::string getString(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a UTF8 string.

If the tag’s value cannot be converted to a string then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

If the conversion to UTF8 fails then throws CharsetConversionCannotConvert, CharsetConversionNoSupportedTableError, CharsetConversionNoTableError.

Return

the tag’s value as a string

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::string getString(const TagId &tagId, size_t elementNumber, const std::string &defaultValue) const

Retrieve a tag’s value as a UTF8 string.

If the tag’s value cannot be converted to a string then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as a string, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

std::wstring getUnicodeString(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as an Unicode string.

If the tag’s value cannot be converted to a Unicode string then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as an unicode string

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

std::wstring getUnicodeString(const TagId &tagId, size_t elementNumber, const std::wstring &defaultValue) const

Retrieve a tag’s value as an unicode string.

If the tag’s value cannot be converted to a Unicode string then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as an unicode string, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

const Age getAge(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as Age.

If the tag’s value cannot be converted to Age then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as Age

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

const Age getAge(const TagId &tagId, size_t elementNumber, const Age &defaultValue) const

Retrieve a tag’s value as Age.

If the tag’s value cannot be converted to Age then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as Age, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer 0

• defaultValue: the value to return if the tag doesn’t exist

const Date getDate(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a Date.

If the tag’s value cannot be converted to a Date then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a Date

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer 0

const Date getDate(const TagId &tagId, size_t elementNumber, const Date &defaultValue) const

Retrieve a tag’s value as a Date.

If the tag’s value cannot be converted to a date then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as a Date, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

const PatientName getPatientName(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a Patient Name.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a Patient Name

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

const PatientName getPatientName(const TagId &tagId, size_t elementNumber, const PatientName &defaultValue) const

Retrieve a tag’s value as a Patient Name.

If the tag’s value cannot be converted to a patient name then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as a Patient Name, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

const UnicodePatientName getUnicodePatientName(const TagId &tagId, size_t elementNumber) const

Retrieve a tag’s value as a Unicode Patient Name.

If the tag’s value cannot be converted to a patient name then throws DataHandlerConversionError.

If the value does not exist then throws MissingTagError or MissingGroupError or MissingBufferError or MissingItemError.

Return

the tag’s value as a Unicode Patient Name

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

const UnicodePatientName getUnicodePatientName(const TagId &tagId, size_t elementNumber, const UnicodePatientName &defaultValue) const

Retrieve a tag’s value as a Unicode Patient Name.

If the tag’s value cannot be converted to a patient name then throws DataHandlerConversionError.

If the specified Tag does not exist then returns the default value specified in the parameter.

Return

the tag’s value as a Unicode Patient Name, or defaultValue if the tag doesn’t exist

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

tagVR_t getDataType(const TagId &tagId) const

Return the 2 chars data type (VR) of the specified tag.

If the tag not exist then throws MissingTagError or MissingGroupError.

Return

the tag’s data type (VR)

Parameters

• tagId: the id of the tag

Objective-C/Swift

class ImebraDataSet : public NSObject

This class represents an immutable DICOM dataset.

The information it contains is organized into groups and each group may contain several tags.

You can create a ImebraDataSet from a DICOM file by using the ImebraCodecFactory::load() function:

NSError* error = nil;
ImebraDataSet* pDataSet = [ImebraCodecFactory load:@"dicomFile.dcm" error:&error];

To retrieve the DataSet’s content, use one of the following methods which give direct access to the tags’ values:

• getImage()

• getImageApplyModalityTransform()

• getSequenceItem()

• getInt64()

• getInt32()

• getInt16()

• getInt8()

• getUint64()

• getUint32()

• getUint16()

• getUint8()

• getDouble()

• getFloat()

• getString()

• getUnicodeString()

• getAge()

• getDate()

• getPatient()

In alternative, you can first retrieve a ImebraReadingDataHandler with getReadingDataHandler() and then access the tag’s content via the handler.

Subclassed by ImebraMutableDataSet

Public Functions

NSArray *getTags()

Returns a list of all the tags stored in the DataSet, ordered by group and tag ID.

Return

an NSArray containing an ordered list of ImebraTagId objects

ImebraTag* ImebraDataSet::getTag:error:(ImebraTagId * tagId, NSError ** pError)

Retrieve the Tag with the specified ID.

Return

the Tag with the specified ID

Parameters

• tagId: the ID of the tag to retrieve

• pError: set if an error occurs

ImebraImage* ImebraDataSet::getImage:error:(unsigned int frameNumber, NSError ** pError)

Retrieve an image from the dataset.

Images should be retrieved in order (first frame 0, then frame 1, then frame 2 and so on). Images can be retrieved also in random order but this introduces performance penalties.

Set pError and returns nil if the requested image does not exist.

Note

Images retrieved from the ImebraDataSet should be processed by the ImebraModalityVOILUT transform, which converts the modality-specific pixel values to values that the application can understand. Consider using getImageApplyModalityTransform() to retrieve the image already processed by ImebraModalityVOILUT.

Return

an ImebraImage object containing the decompressed image

Parameters

• frameNumber: the frame to retrieve (the first frame is 0)

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraOverlay* ImebraDataSet::getOverlay:error:(unsigned int overlayNumber, NSError ** pError)

Retrieve one of the DICOM overlays.

Set pError to ImebraMissingGroupError if the requested overlay does not exist.

Return

the requested overlay

Parameters

• overlayNumber: the number of the overlay to retrieve (0…127)

ImebraImage* ImebraDataSet::getImageApplyModalityTransform:error:(unsigned int frameNumber, NSError ** pError)

Retrieve an image from the dataset and if necessary process it with ImebraModalityVOILUT before returning it.

Images should be retrieved in order (first frame 0, then frame 1, then frame 2 and so on). Images can be retrieved also in random order but this introduces performance penalties.

Set pError and returns nil if the requested image does not exist.

Return

an ImebraImage object containing the decompressed image processed by ImebraModalityVOILUT (if present)

Parameters

• frameNumber: the frame to retrieve (the first frame is 0)

• pError: a pointer to a NSError pointer which is set when an error occurs

NSArray* ImebraDataSet::getVOIs:(NSError ** pError)

Return the list of VOI settings stored in the DataSet.

Each VOI setting includes the center & width values that can be used with the VOILUT transform to highlight different parts of an Image.

If the VOI/LUT information is stored in a functional group, then first use getFunctionalGroupDataSet() to retrieve the sequence item containing the VOI/LUT information, then call getVOIs() on the returned dataset.

Return

an NSArray containing a list of ImebraVOIDescription objects

Parameters

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraDataSet* ImebraDataSet::getFunctionalGroupDataSet:error:(unsigned int frameNumber, NSError ** pError)

In case the dataset uses functional groups to store imaging information, then this method returns the sequence item containing imaging information for a specific frame.

The method looks first for a frame specific functional group sequence item, then for a common functional group sequence item if the specific one is missing.

Throws MissingTagError is the dataset does not contain a functional group sequence.

Return

the functional group sequence item for the requested frame.

Parameters

• frameNumber: the frame number for which the functional group sequence item is required

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraStreamReader* ImebraDataSet::getStreamReader:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Get a StreamReader connected to a buffer’s data.

Return

the streamReader connected to the buffer’s data.

Parameters

• pTagId: the tag’s id for which the StreamReader is required

• bufferId: the id of the buffer for which the StreamReader is required. This parameter is usually 0

• pError: set to a NSError derived class in case of error

ImebraDataSet* ImebraDataSet::getSequenceItem:item:error:(ImebraTagId * pTagId, unsigned int itemId, NSError ** pError)

Retrieve a sequence item stored in a tag.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified sequence item then set pError to ImebraMissingItemError.

Return

the requested sequence item

Parameters

• pTagId: the tag’s id containing the sequence item

• itemId: the sequence item to retrieve. The first item has an Id = 0

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraLUT* ImebraDataSet::getLUT:item:error:(ImebraTagId * pTagId, unsigned int itemId, NSError ** pError)

Retrieve a ImebraLUT stored in a sequence item.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified sequence item then set pError to ImebraMissingItemError.

Return

the LUT stored in the requested sequence item

Parameters

• pTagId: the tag’s id containing the sequence that stores the LUTs

• itemId: the sequence item to retrieve. The first item has an Id = 0

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraReadingDataHandler* ImebraDataSet::getReadingDataHandler:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve an ImebraReadingDataHandler object connected to a specific tag’s buffer.

If the specified tag does not exist then sets pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified buffer item then sets pError to ImebraMissingBufferError.

Return

an ImebraReadingDataHandler object connected to the requested tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraReadingDataHandlerNumeric* ImebraDataSet::getReadingDataHandlerNumeric:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandlerNumeric object connected to a specific tag’s numeric buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified buffer item then set pError to ImebraMissingItemError.

Return

a ImebraReadingDataHandlerNumeric object connected to the requested tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraReadingDataHandlerNumeric* ImebraDataSet::getReadingDataHandlerRaw:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandlerNumeric object connected to a specific tag’s buffer, no matter what the tag’s data type.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

If the specified tag does not contain the specified buffer item then set pError to ImebraMissingItemError.

Return

a ImebraReadingDataHandlerNumeric object connected to the requested tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

• pError: a pointer to a NSError pointer which is set when an error occurs

signed long long ImebraDataSet::getInt64:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed very long integer (64 bit).

If the tag’s value cannot be converted to a signed very long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a signed 64 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

signed int ImebraDataSet::getInt32:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed long integer (32 bit).

If the tag’s value cannot be converted to a signed long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a signed 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

signed int ImebraDataSet::getSignedLong:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use getInt32() instead.

signed short ImebraDataSet::getInt16:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed short integer (16 bit).

If the tag’s value cannot be converted to a signed long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a signed 16 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

signed char ImebraDataSet::getInt8:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed char integer (8 bit).

If the tag’s value cannot be converted to a signed long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a signed 8 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

signed long long ImebraDataSet::getInt64:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, signed long long defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed very long integer (64 bit).

If the tag’s value cannot be converted to a signed very long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a signed 64 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

signed int ImebraDataSet::getInt32:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, signed int defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed long integer (32 bit).

If the tag’s value cannot be converted to a signed long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a signed 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

signed int ImebraDataSet::getSignedLong:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, signed int defaultValue, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use getInt32() instead.

signed short ImebraDataSet::getInt16:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, signed short defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed short integer (16 bit).

If the tag’s value cannot be converted to a signed long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a signed 16 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

signed char ImebraDataSet::getInt8:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, signed char defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as signed char integer (8 bit).

If the tag’s value cannot be converted to a signed long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a signed 8 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned long long ImebraDataSet::getUint64:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned very long integer (64 bit).

If the tag’s value cannot be converted to an unsigned very long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an unsigned 64 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned int ImebraDataSet::getUint32:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned long integer (32 bit).

When calling getUint32() on an AT tag (Attribute Tag) then the tag group is always in the high word of the returned value.

If the tag’s value cannot be converted to an unsigned long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned int ImebraDataSet::getUnsignedLong:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use getUint32() instead.

unsigned short ImebraDataSet::getUint16:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned long integer (16 bit).

If the tag’s value cannot be converted to an unsigned long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an unsigned 16 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned char ImebraDataSet::getUint8:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned long integer (8 bit).

If the tag’s value cannot be converted to an unsigned long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an unsigned 8 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned long long ImebraDataSet::getUint64:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, unsigned long long defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned very long integer (64 bit).

If the tag’s value cannot be converted to an unsigned very long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an unsigned 64 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned int ImebraDataSet::getUint32:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, unsigned int defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned long integer (32 bit).

When calling getUint32() on an AT tag (Attribute Tag) then the tag group is always in the high word of the returned value.

If the tag’s value cannot be converted to an unsigned long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned int ImebraDataSet::getUnsignedLong:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, unsigned int defaultValue, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use getUint32() instead.

unsigned short ImebraDataSet::getUint16:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, unsigned short defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned long integer (16 bit).

If the tag’s value cannot be converted to an unsigned long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an unsigned 16 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

unsigned char ImebraDataSet::getUint8:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, unsigned char defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as unsigned long integer (8 bit).

If the tag’s value cannot be converted to an unsigned long integer then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an unsigned 8 bit integer

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

double ImebraDataSet::getDouble:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as a double floating point.

If the tag’s value cannot be converted to double floating point then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a double floating point

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

float ImebraDataSet::getFloat:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as a floating point value.

If the tag’s value cannot be converted to double floating point then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a floating point

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

double ImebraDataSet::getDouble:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, double defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as a double floating point.

If the tag’s value cannot be converted to double floating point then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a double floating point

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

float ImebraDataSet::getFloat:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, float defaultValue, (swift_error(nonnull_error)) __attribute__)

Retrieve a tag’s value as a floating point value.

If the tag’s value cannot be converted to double floating point then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a floating point

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

NSString* ImebraDataSet::getString:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as a string.

If the tag’s value cannot be converted to a string then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as a string

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

NSString* ImebraDataSet::getString:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, NSString * defaultValue, NSError ** pError)

Retrieve a tag’s value as a string.

If the tag’s value cannot be converted to a string then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as a string

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraAge* ImebraDataSet::getAge:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as an ImebraAge object.

If the tag’s value cannot be converted to an ImebraAge object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an ImebraAge object

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraAge* ImebraDataSet::getAge:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, ImebraAge * defaultValue, NSError ** pError)

Retrieve a tag’s value as an ImebraAge object.

If the tag’s value cannot be converted to an ImebraAge object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an ImebraAge object

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraDate* ImebraDataSet::getDate:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as an ImebraDate object.

If the tag’s value cannot be converted to an ImebraDate object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an ImebraDate object

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraDate* ImebraDataSet::getDate:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, ImebraDate * defaultValue, NSError ** pError)

Retrieve a tag’s value as an ImebraDate object.

If the tag’s value cannot be converted to an ImebraDate object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an ImebraDate object

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraPatientName* ImebraDataSet::getPatientName:elementNumber:error:(ImebraTagId * tagId, unsigned int elementNumber, NSError ** pError)

Retrieve a tag’s value as an ImebraPatientName object.

If the tag’s value cannot be converted to an ImebraPatientName object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s value as an ImebraDate object

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraPatientName* ImebraDataSet::getPatientName:elementNumber:defaultValue:error:(ImebraTagId * tagId, unsigned int elementNumber, ImebraPatientName * defaultValue, NSError ** pError)

Retrieve a tag’s value as an ImebraPatientName object.

If the tag’s value cannot be converted to an ImebraPatientName object then sets pError to ImebraDataHandlerConversionError.

If the specified tag does not exist then returns the default value set in the defaultValue parameter.

Return

the tag’s value as an ImebraDate object

Parameters

• tagId: the tag’s id

• elementNumber: the element number within the buffer

• defaultValue: the value to return if the tag doesn’t exist

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraTagType ImebraDataSet::getDataType:error:(ImebraTagId * tagId, (swift_error(nonnull_error)) __attribute__)

Return the data type (VR) of the specified tag.

If the specified tag does not exist then set pError to ImebraMissingTagError or ImebraMissingGroupError.

Return

the tag’s data type (VR)

Parameters

• tagId: the id of the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

MutableDataSet

C++

class MutableDataSet : public imebra::DataSet

This class represents a mutable DICOM dataset.

The information it contains is organized into groups and each group may contain several tags.

You can create an empty DataSet that can be filled with data and images and then saved to a DICOM file via CodecFactory::save().

When creating an empty DataSet you should specify the proper transfer syntax in the DataSet constructor.

To set the DataSet’s content, use one of the following methods:

• setImage()

• appendSequenceItem()

• setInt64()

• setUInt64()

• setUint32()

• setInt16()

• setUint16()

• setInt8()

• setUint8()

• setDouble()

• setFloat()

• setString()

• setUnicodeString()

• setAge()

• setDate()

The previous methods allow to write just the first item in the tag’s content and before writing wipe out the old tag’s content (all the items). If you have to write more than one item in a tag, retrieve a WritingDataHandler with getWritingDataHandler() and then modify all the tag’s items using the WritingDataHandler.

Public Functions

MutableDataSet(const MutableDataSet &source)

Copy constructor.

Parameters

• source: the source data set

MutableDataSet()

Construct an empty DICOM dataset with unspecified transfer syntax (which represents the default value “1.2.840.10008.1.2” or “Implicit VR little endian”) and default charset (“ISO 2022 IR 6”).

MutableDataSet(const std::string &transferSyntax)

Construct an empty DICOM dataset with charset “ISO 2022 IR 6” and the desidered transfer syntax.

Parameters

• transferSyntax: the dataSet’s transfer syntax. The following transfer syntaxes are supported:

  • ”1.2.840.10008.1.2” (Implicit VR little endian)

  • ”1.2.840.10008.1.2.1” (Explicit VR little endian)

  • ”1.2.840.10008.1.2.2” (Explicit VR big endian)

  • ”1.2.840.10008.1.2.5” (RLE compression)

  • ”1.2.840.10008.1.2.4.50” (Jpeg baseline 8 bit lossy)

  • ”1.2.840.10008.1.2.4.51” (Jpeg extended 12 bit lossy)

  • ”1.2.840.10008.1.2.4.57” (Jpeg lossless NH)

  • ”1.2.840.10008.1.2.4.70” (Jpeg lossless NH first order prediction)

MutableDataSet(const std::string &transferSyntax, const charsetsList_t &charsets)

Construct an empty DICOM dataset and specifies the default charsets.

Parameters

• transferSyntax: the dataSet’s transfer syntax. The following transfer syntaxes are supported:

  • ”1.2.840.10008.1.2” (Implicit VR little endian)

  • ”1.2.840.10008.1.2.1” (Explicit VR little endian)

  • ”1.2.840.10008.1.2.2” (Explicit VR big endian)

  • ”1.2.840.10008.1.2.5” (RLE compression)

  • ”1.2.840.10008.1.2.4.50” (Jpeg baseline 8 bit lossy)

  • ”1.2.840.10008.1.2.4.51” (Jpeg extended 12 bit lossy)

  • ”1.2.840.10008.1.2.4.57” (Jpeg lossless NH)

  • ”1.2.840.10008.1.2.4.70” (Jpeg lossless NH first order prediction)

• charsets: a list of charsets supported by the DataSet

MutableTag getTagCreate(const TagId &tagId, tagVR_t tagVR)

Retrieve the Tag with the specified ID or create it if it doesn’t exist.

Return

the Tag with the specified ID

Parameters

• tagId: the ID of the tag to retrieve

• tagVR: the VR to use for the new tag if one doesn’t exist already

MutableTag getTagCreate(const TagId &tagId)

Retrieve the Tag with the specified ID or create it if it doesn’t exist.

Return

the Tag with the specified ID

Parameters

• tagId: the ID of the tag to retrieve

void setImage(size_t frameNumber, const Image &image, imageQuality_t quality)

Insert an image into the dataset.

In multi-frame datasets the images must be inserted in order: first, insert the frame 0, then the frame 1, then the frame 2 and so on.

All the inserted images must have the same transfer syntax and the same properties (size, color space, high bit, bits allocated).

If the images are inserted in the wrong order then the DataSetWrongFrameError exception is thrown.

If the image being inserted has different properties than the ones of the images already in the dataset then the exception DataSetDifferentFormatError is thrown.

Parameters

• frameNumber: the frame number (the first frame is 0)

• image: the image

• quality: the quality to use for lossy compression. Ignored if lossless compression is used

StreamWriter getStreamWriter(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Get a StreamWriter connected to a tag buffer’s data.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

Return

the StreamWriter connected to the buffer’s data.

Parameters

• tagId: the tag’s id for which the StreamWriter is required

• bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

• tagVR: the tag’s VR

StreamWriter getStreamWriter(const TagId &tagId, size_t bufferId)

Get a StreamWriter connected to a tag buffer’s data.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Return

the StreamWriter connected to the buffer’s data.

Parameters

• tagId: the tag’s id for which the StreamWriter is required

• bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

MutableDataSet appendSequenceItem(const TagId &tagId)

Append a sequence item.

If the specified Tag does not exist then creates a new one with VR tagVR_t::SQ.

Return

the MutableDataSet representing the added sequence item

Parameters

• tagId: the tag’s id in which the sequence must be stored

WritingDataHandler getWritingDataHandler(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Retrieve a WritingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandler is connected to a new buffer which is updated and stored into the tag when WritingDataHandler is destroyed.

Return

a WritingDataHandler object connected to a new Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• tagVR: the tag’s VR

WritingDataHandler getWritingDataHandler(const TagId &tagId, size_t bufferId)

Retrieve a WritingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

The returned WritingDataHandler is connected to a new buffer which is updated and stored into the tag when WritingDataHandler is destroyed.

Return

a WritingDataHandler object connected to a new Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

WritingDataHandlerNumeric getWritingDataHandlerNumeric(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• tagVR: the tag’s VR

WritingDataHandlerNumeric getWritingDataHandlerNumeric(const TagId &tagId, size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

WritingDataHandlerNumeric getWritingDataHandlerRaw(const TagId &tagId, size_t bufferId, tagVR_t tagVR)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer. The handler content is cast to bytes.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• tagVR: the tag’s VR

WritingDataHandlerNumeric getWritingDataHandlerRaw(const TagId &tagId, size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to a specific tag’s buffer. The handler content is cast to bytes.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

void setInt64(const TagId &tagId, std::int64_t newValue, tagVR_t tagVR)

Write a new signed 64 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setInt32(const TagId &tagId, std::int32_t newValue, tagVR_t tagVR)

Write a new signed 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setSignedLong(const TagId &tagId, std::int32_t newValue, tagVR_t tagVR)

Deprecated. Use setInt32() instead.

void setInt64(const TagId &tagId, std::int64_t newValue)

Write a new signed 64 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setInt32(const TagId &tagId, std::int32_t newValue)

Write a new signed 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setSignedLong(const TagId &tagId, std::int32_t newValue)

Deprecated. Use setInt32() instead.

void setUint64(const TagId &tagId, std::uint64_t newValue, tagVR_t tagVR)

Write a new unsigned 64 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setUint32(const TagId &tagId, std::uint32_t newValue, tagVR_t tagVR)

Write a new unsigned 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

When setting a value for an AT tag (Attribute Tag) then the tag’s group must always be in the higher 16 bits of the value.

If the specified Tag doesn’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setUnsignedLong(const TagId &tagId, std::uint32_t newValue, tagVR_t tagVR)

Deprecated. Use setUint32() instead.

void setUint64(const TagId &tagId, std::uint64_t newValue)

Write a new unsigned 64 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setUint32(const TagId &tagId, std::uint32_t newValue)

Write a new unsigned 32 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setUnsignedLong(const TagId &tagId, std::uint32_t newValue)

Deprecated. Use setUint32() instead.

void setInt16(const TagId &tagId, std::int16_t newValue, tagVR_t tagVR)

Write a new signed 16 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setInt16(const TagId &tagId, std::int16_t newValue)

Write a new signed 16 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setUint16(const TagId &tagId, std::uint16_t newValue, tagVR_t tagVR)

Write a new unsigned 16 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setUint16(const TagId &tagId, std::uint16_t newValue)

Write a new unsigned 16 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setInt8(const TagId &tagId, std::int8_t newValue, tagVR_t tagVR)

Write a new signed 8 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setInt8(const TagId &tagId, std::int8_t newValue)

Write a new signed 8 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setUint8(const TagId &tagId, std::uint8_t newValue, tagVR_t tagVR)

Write a new unsigned 8 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setUint8(const TagId &tagId, std::uint8_t newValue)

Write a new unsigned 8 bit integer value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setDouble(const TagId &tagId, double newValue, tagVR_t tagVR)

Write a 64 bit floating point value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setDouble(const TagId &tagId, double newValue)

Write a 64 bit floating point value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setFloat(const TagId &tagId, float newValue, tagVR_t tagVR)

Write a 32 bit floating point value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag is created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setFloat(const TagId &tagId, float newValue)

Write a 32 bit floating point value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

void setString(const TagId &tagId, const std::string &newString, tagVR_t tagVR)

Write a UTF8 string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a specific VR.

Parameters

• tagId: the tag’s id

• newString: the string to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setString(const TagId &tagId, const std::string &newString)

Write a UTF8 string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newString: the string to write into the tag

void setUnicodeString(const TagId &tagId, const std::wstring &newString, tagVR_t tagVR)

Write an unicode string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag is created using the specified VR.

Parameters

• tagId: the tag’s id

• newString: the string to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setUnicodeString(const TagId &tagId, const std::wstring &newString)

Write an unicode string value into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• newString: the string to write into the tag

void setAge(const TagId &tagId, const Age &age)

Write an Age string into the element 0 of the specified Tag’s buffer 0.

If the specified Tag doesn’t exist then a new tag and is created using the VR tagVR_t::AS.

Parameters

• tagId: the tag’s id

• age: the Age to write into the tag

void setDate(const TagId &tagId, const Date &date, tagVR_t tagVR)

Write a Date string into the element 0 of the specified Tag’s buffer 0.

If the specified Tag or buffer don’t exist then a new tag and/or buffer are created using the specified data type (VR).

Parameters

• tagId: the tag’s id

• date: the Date to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

void setDate(const TagId &tagId, const Date &date)

Write a Date string into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a default VR retrieved from the DicomDictionary.

Parameters

• tagId: the tag’s id

• date: the Date to write into the tag

void setPatientName(const TagId &tagId, const PatientName &patientName)

Write a Patient Name into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a VR PN.

Parameters

• tagId: the tag’s id

• date: the Patient Name to write into the tag

void setUnicodePatientName(const TagId &tagId, const UnicodePatientName &patientName)

Write a Unicode Patient Name into the element 0 of the specified Tag’s buffer 0.

If the specified Tag does not exist then it creates a new tag with a VR PN.

Parameters

• tagId: the tag’s id

• date: the Unicode Patient Name to write into the tag

Objective-C/Swift

class ImebraMutableDataSet : public ImebraDataSet

This class represents a mutableDICOM dataset.

The information it contains is organized into groups and each group may contain several tags.

You can create an empty ImebraMutableDataSet that can be filled with data and images and then saved to a DICOM file via ImebraCodecFactory::save().

When creating an empty ImebraMutableDataSet you should specify the proper transfer syntax in the init method.

To set the ImebraMutableDataSet’s content, use one of the following methods:

• setImage()

• appendSequenceItem()

• setInt64()

• setInt32()

• setInt16()

• setInt8()

• setUint64()

• setUint32()

• setUint16()

• setUint8()

• setDouble()

• setFloat()

• setString()

• setUnicodeString()

• setAge()

• setDate()

• setPatientName()

The previous methods allow to write just the first item in the tag’s content and before writing wipe out the old tag’s content (all the items). If you have to write more than one item in a tag, retrieve a ImebraWritingDataHandler with getWritingDataHandler() and then modify all the tag’s items using the ImebraWritingDataHandler.

Public Functions

id init()

Construct an empty DICOM dataset with unspecified transfer syntax (e.g. to be used in a sequence) charset “ISO 2022 IR 6”.

Use this method when creating a DataSet that will be embedded in a sequence item.

id ImebraMutableDataSet::initWithTransferSyntax:(NSString * transferSyntax)

Construct an empty DICOM dataset with charset “ISO 2022 IR 6” and the desidered transfer syntax.

Parameters

• transferSyntax: the dataSet’s transfer syntax. The following transfer syntaxes are supported:

  • ”1.2.840.10008.1.2” (Implicit VR little endian)

  • ”1.2.840.10008.1.2.1” (Explicit VR little endian)

  • ”1.2.840.10008.1.2.2” (Explicit VR big endian)

  • ”1.2.840.10008.1.2.5” (RLE compression)

  • ”1.2.840.10008.1.2.4.50” (Jpeg baseline 8 bit lossy)

  • ”1.2.840.10008.1.2.4.51” (Jpeg extended 12 bit lossy)

  • ”1.2.840.10008.1.2.4.57” (Jpeg lossless NH)

  • ”1.2.840.10008.1.2.4.70” (Jpeg lossless NH first order prediction)

id ImebraMutableDataSet::initWithTransferSyntax:charsets:(NSString * transferSyntax, NSArray * pCharsets)

Construct an empty DICOM dataset and specifies the default charsets.

Parameters

• transferSyntax: the dataSet’s transfer syntax. The following transfer syntaxes are supported:

  • ”1.2.840.10008.1.2” (Implicit VR little endian)

  • ”1.2.840.10008.1.2.1” (Explicit VR little endian)

  • ”1.2.840.10008.1.2.2” (Explicit VR big endian)

  • ”1.2.840.10008.1.2.5” (RLE compression)

  • ”1.2.840.10008.1.2.4.50” (Jpeg baseline 8 bit lossy)

  • ”1.2.840.10008.1.2.4.51” (Jpeg extended 12 bit lossy)

  • ”1.2.840.10008.1.2.4.57” (Jpeg lossless NH)

  • ”1.2.840.10008.1.2.4.70” (Jpeg lossless NH first order prediction)

• pCharsets: a NSArray of NSString specifying the charsets supported by the DataSet

ImebraMutableTag* ImebraMutableDataSet::getTagCreate:tagVR:error:(ImebraTagId * tagId, ImebraTagType tagVR, NSError ** pError)

Retrieve the ImebraTag with the specified ID or create it if it doesn’t exist.

Return

the Tag with the specified ID

Parameters

• tagId: the ID of the tag to retrieve

• tagVR: the VR to use for the new tag if one doesn’t exist already

• pError: set if an error occurs

ImebraMutableTag* ImebraMutableDataSet::getTagCreate:error:(ImebraTagId * tagId, NSError ** pError)

Retrieve the ImebraTag with the specified ID or create it if it doesn’t exist. Set the proper VR according to the tag ID.

Return

the Tag with the specified ID

Parameters

• tagId: the ID of the tag to retrieve

• pError: set if an error occurs

void ImebraMutableDataSet::setImage:image:quality:error:(unsigned int frameNumber, ImebraImage * image, ImebraImageQuality quality, (swift_error(nonnull_error)) __attribute__)

Insert an image into the dataset.

In multi-frame datasets the images must be inserted in order: first insert the frame 0, then the frame 1, then the frame 2 and so on.

All the inserted images must have the same transfer syntax and the same properties (size, color space, high bit, bits allocated).

If the images are inserted in the wrong order then the ImebraDataSetWrongFrameError is set in pError.

If the image being inserted has different properties than the ones of the images already in the dataset then the exception ImebraDataSetDifferentFormatError is set in pError.

Parameters

• frameNumber: the frame number (the first frame is 0)

• image: the image

• quality: the quality to use for lossy compression. Ignored if lossless compression is used

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setOverlay:overlay:error:(unsigned int overlayNumber, ImebraOverlay * overlay, (swift_error(nonnull_error)) __attribute__)

Insert an overlay into the dataset.

Parameters

• overlayNumber: the overlay number (0…127)

• overlay: the overlay to insert into the dataset

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraStreamWriter* ImebraMutableDataSet::getStreamWriter:bufferId:error:(ImebraTagId * pTagId, unsigned int bufferId, NSError ** pError)

Get a StreamWriter connected to a buffer’s data.

If the specified tag does not exist then it creates a new tag with the VR specified in DICOM dictionary

Return

the StreamWriter connected to the buffer’s data.

Parameters

• pTagId: the tag’s id for which the StreamWriter is required

• bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

• pError: set to a NSError derived class in case of error

ImebraStreamWriter* ImebraMutableDataSet::getStreamWriter:bufferId:tagVR:error:(ImebraTagId * pTagId, unsigned int bufferId, ImebraTagType tagVR, NSError ** pError)

Get a StreamWriter connected to a buffer’s data.

If the specified tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

Return

the StreamWriter connected to the buffer’s data.

Parameters

• pTagId: the tag’s id for which the StreamWriter is required

• bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

• pError: set to a NSError derived class in case of error

ImebraMutableDataSet* ImebraMutableDataSet::appendSequenceItem:error:(ImebraTagId * pTagId, NSError ** pError)

Append a sequence item.

If the specified tag does not exist then creates a new one with VR ImebraTagTypeSQ.

Return

the dataset representing the appended sequence item

Parameters

• pTagId: the tag’s id in which the sequence must be stored

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandler* ImebraMutableDataSet::getWritingDataHandler:bufferId:tagVR:error:(ImebraTagId * tagId, unsigned int bufferId, ImebraTagType tagVR, NSError ** pError)

Retrieve an ImebraWritingDataHandler object connected to a specific tag’s buffer and sets its data type (VR).

If the specified tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned ImebraWritingDataHandler is connected to a new buffer which is updated and stored into the tag when the ImebraWritingDataHandler object is destroyed.

Return

a ImebraWritingDataHandler object connected to a new tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• tagVR: the tag’s VR

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandler* ImebraMutableDataSet::getWritingDataHandler:bufferId:error:(ImebraTagId * tagId, unsigned int bufferId, NSError ** pError)

Retrieve a ImebraWritingDataHandler object connected to a specific tag’s buffer.

If the specified tag does not exist then it creates a new tag with a default VR retrieved from the ImebraDicomDictionary.

The returned ImebraWritingDataHandler is connected to a new buffer which is updated and stored into the tag when the ImebraWritingDataHandler object is destroyed.

Return

a ImebraWritingDataHandler object connected to a new tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandlerNumeric* ImebraMutableDataSet::getWritingDataHandlerNumeric:bufferId:tagVR:error:(ImebraTagId * tagId, unsigned long bufferId, ImebraTagType tagVR, NSError ** pError)

Retrieve a ImebraWritingDataHandlerNumeric object connected to a specific tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned ImebraWritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when ImebraWritingDataHandlerNumeric is destroyed.

Return

a ImebraWritingDataHandlerNumeric object connected to a new tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• tagVR: the tag’s VR

• pError: a pointer to a NSError pointer which is set when an error occurs

ImebraWritingDataHandlerNumeric* ImebraMutableDataSet::getWritingDataHandlerNumeric:bufferId:error:(ImebraTagId * tagId, unsigned long bufferId, NSError ** pError)

Retrieve a ImebraWritingDataHandlerNumeric object connected to a specific tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified tag does not exist then it creates a new tag with a default VR retrieved from the ImebraDicomDictionary.

The returned ImebraWritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when ImebraWritingDataHandlerNumeric is destroyed.

Return

a ImebraWritingDataHandlerNumeric object connected to a new tag’s buffer

Parameters

• tagId: the tag’s id containing the requested buffer

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setInt64:newValue:tagVR:error:(ImebraTagId * tagId, signed long long newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new signed 64 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setInt32:newValue:tagVR:error:(ImebraTagId * tagId, signed int newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new signed 32 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setSignedLong:newValue:tagVR:error:(ImebraTagId * tagId, signed int newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

\bried Deprecated. Use setInt32() instead.

void ImebraMutableDataSet::setInt16:newValue:tagVR:error:(ImebraTagId * tagId, signed short newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new signed 16 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setInt8:newValue:tagVR:error:(ImebraTagId * tagId, signed char newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new signed 8 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setInt64:newValue:error:(ImebraTagId * tagId, signed long long newValue, (swift_error(nonnull_error)) __attribute__)

Write a new signed 64 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setInt32:newValue:error:(ImebraTagId * tagId, signed int newValue, (swift_error(nonnull_error)) __attribute__)

Write a new signed 32 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setSignedLong:newValue:error:(ImebraTagId * tagId, signed int newValue, (swift_error(nonnull_error)) __attribute__)

\bried Deprecated. Use setInt32() instead.

void ImebraMutableDataSet::setInt16:newValue:error:(ImebraTagId * tagId, signed short newValue, (swift_error(nonnull_error)) __attribute__)

Write a new signed 16 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setInt8:newValue:error:(ImebraTagId * tagId, signed char newValue, (swift_error(nonnull_error)) __attribute__)

Write a new signed 8 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUint64:newValue:tagVR:error:(ImebraTagId * tagId, unsigned long long newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 64 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUint32:newValue:tagVR:error:(ImebraTagId * tagId, unsigned int newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 32 bit integer value into the element 0 of the specified tag’s buffer 0.

When setting a value for an AT tag (Attribute Tag) then the tag’s group must always be in the higher 16 bits of the value.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUnsignedLong:newValue:tagVR:error:(ImebraTagId * tagId, unsigned int newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use setUint32() instead.

void ImebraMutableDataSet::setUint16:newValue:tagVR:error:(ImebraTagId * tagId, unsigned short newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 16 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUint8:newValue:tagVR:error:(ImebraTagId * tagId, unsigned char newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 8 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUint64:newValue:error:(ImebraTagId * tagId, unsigned long long newValue, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 64 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUint32:newValue:error:(ImebraTagId * tagId, unsigned int newValue, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 32 bit integer value into the element 0 of the specified tag’s buffer 0.

When setting a value for an AT tag (Attribute Tag) then the tag’s group must always be in the higher 16 bits of the value.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUnsignedLong:newValue:error:(ImebraTagId * tagId, unsigned int newValue, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use setUint32() instead.

void ImebraMutableDataSet::setUint16:newValue:error:(ImebraTagId * tagId, unsigned short newValue, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 16 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setUint8:newValue:error:(ImebraTagId * tagId, unsigned char newValue, (swift_error(nonnull_error)) __attribute__)

Write a new unsigned 8 bit integer value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setDouble:newValue:tagVR:error:(ImebraTagId * tagId, double newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new double floating point value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setFloat:newValue:tagVR:error:(ImebraTagId * tagId, float newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new floating point value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setDouble:newValue:error:(ImebraTagId * tagId, double newValue, (swift_error(nonnull_error)) __attribute__)

Write a new double floating point value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setFloat:newValue:error:(ImebraTagId * tagId, float newValue, (swift_error(nonnull_error)) __attribute__)

Write a new floating point value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setString:newValue:tagVR:error:(ImebraTagId * tagId, NSString * newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new string value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setString:newValue:error:(ImebraTagId * tagId, NSString * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new string value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setAge:newValue:error:(ImebraTagId * tagId, ImebraAge * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraAge value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) AS.

If the new value cannot be converted to the VR “AS” then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setDate:newValue:tagVR:error:(ImebraTagId * tagId, ImebraDate * newValue, ImebraTagType tagVR, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraDate value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the specified data type (VR).

If the new value cannot be converted to the specified VR then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• tagVR: the tag’s type to use when a new tag is created.

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setDate:newValue:error:(ImebraTagId * tagId, ImebraDate * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraDate value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) retrieved from the ImebraDicomDictionary.

If the new value cannot be converted to the VR returned by the ImebraDicomDictionary then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

void ImebraMutableDataSet::setPatientName:newValue:error:(ImebraTagId * tagId, ImebraPatientName * newValue, (swift_error(nonnull_error)) __attribute__)

Write a new ImebraPatientName value into the element 0 of the specified tag’s buffer 0.

If the specified tag doesn’t exist then a new tag is created using the data type (VR) PN.

If the new value cannot be converted to a patient name then sets pError to ImebraDataHandlerConversionError.

Parameters

• tagId: the tag’s id

• newValue: the value to write into the tag

• pError: a pointer to a NSError pointer which is set when an error occurs

Tag

C++

class Tag

This class represents an immutable DICOM tag.

Subclassed by imebra::MutableTag

Public Functions

Tag(const Tag &source)

Copy constructor.

Parameters

• source: source Tag object

size_t getBuffersCount() const

Returns the number of buffers in the tag.

Return

the number of buffers in the tag

bool bufferExists(size_t bufferId) const

Returns true if the specified buffer exists, otherwise it returns false.

Return

true if the buffer exists, false otherwise

Parameters

• bufferId: the zero-based buffer’s id the function has to check for

size_t getBufferSize(size_t bufferId) const

Returns the size of a buffer, in bytes.

If the buffer doesn’t exist then throws MissingBufferError.

Return

the buffer’s size in bytes

Parameters

• bufferId: the zero-based buffer’s id the function has to check for

ReadingDataHandler getReadingDataHandler(size_t bufferId) const

Retrieve a ReadingDataHandler object connected to a specific buffer.

If the specified buffer does not exist then throws or MissingBufferError.

Return

a ReadingDataHandler object connected to the requested buffer

Parameters

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

ReadingDataHandlerNumeric getReadingDataHandlerNumeric(size_t bufferId) const

Retrieve a ReadingDataHandlerNumeric object connected to the Tag’s numeric buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not contain the specified buffer then throws MissingBufferError.

Return

a ReadingDataHandlerNumeric object connected to the Tag’s buffer

Parameters

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

ReadingDataHandlerNumeric getReadingDataHandlerRaw(size_t bufferId) const

Retrieve a ReadingDataHandlerNumeric object connected to the Tag’s raw data buffer (8 bit unsigned integers).

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not contain the specified buffer then throws MissingBufferError.

Return

a ReadingDataHandlerNumeric object connected to the Tag’s buffer (raw content represented by 8 bit unsigned integers)

Parameters

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

StreamReader getStreamReader(size_t bufferId) const

Get a StreamReader connected to a buffer’s data.

Return

the StreamReader connected to the buffer’s data.

Parameters

• bufferId: the id of the buffer for which the StreamReader is required. This parameter is usually 0

const DataSet getSequenceItem(size_t dataSetId) const

Retrieve an embedded DataSet.

Sequence tags (VR=SQ) store embedded dicom structures.

Return

the sequence DataSet

Parameters

• dataSetId: the ID of the sequence item to retrieve. Several sequence items can be embedded in one tag.

bool sequenceItemExists(size_t dataSetId) const

Check for the existance of a sequence item.

Return

true if the sequence item exists, false otherwise

Parameters

• dataSetId: the ID of the sequence item to check for

tagVR_t getDataType() const

Get the tag’s data type.

Return

the tag’s data type

Objective-C/Swift

class ImebraTag : public NSObject

This class represents a DICOM tag.

Subclassed by ImebraMutableTag

Public Functions

unsigned int getBuffersCount()

Returns the number of buffers in the tag.

Return

the number of buffers in the tag

BOOL ImebraTag::bufferExists:(unsigned int bufferId)

Returns true if the specified buffer exists, otherwise it returns false.

Return

true if the buffer exists, false otherwise

Parameters

• bufferId: the zero-based buffer’s id the function has to check for

unsigned int ImebraTag::getBufferSize:error:(unsigned int bufferId, (swift_error(nonnull_error)) __attribute__)

Returns the size of a buffer, in bytes.

If the buffer doesn’t exist then set pError to ImebraMissingBufferError.

Return

the buffer’s size in bytes

Parameters

• bufferId: the zero-based buffer’s id the function has to check for

• pError: set to a NSError derived class in case of error

ImebraReadingDataHandler* ImebraTag::getReadingDataHandler:error:(unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandler object connected to a specific buffer.

If the buffer doesn’t exist then set pError to ImebraMissingBufferError.

Return

a ImebraReadingDataHandler object connected to the requested buffer

Parameters

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

• pError: set to a NSError derived class in case of error

ImebraReadingDataHandlerNumeric* ImebraTag::getReadingDataHandlerNumeric:error:(unsigned int bufferId, NSError ** pError)

Retrieve a ImebraReadingDataHandlerNumeric object connected to the Tag’s numeric buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the tag does not contain the specified buffer then set pError to ImebraMissingBufferError.

Return

a ImebraReadingDataHandlerNumeric object connected to the Tag’s buffer

Parameters

• bufferId: the buffer to connect to the ImebraReadingDataHandler object. The first buffer has an Id = 0

• pError: set to a NSError derived class in case of error

ImebraReadingDataHandlerNumeric* ImebraTag::getReadingDataHandlerRaw:error:(unsigned int bufferId, NSError ** pError)

Retrieve a ReadingDataHandlerNumeric object connected to the Tag’s raw data buffer (8 bit unsigned integers).

If the tag’s VR is not a numeric type then throws std::bad_cast.

If the specified Tag does not contain the specified buffer then throws MissingBufferError.

Return

a ReadingDataHandlerNumeric object connected to the Tag’s buffer (raw content represented by 8 bit unsigned integers)

Parameters

• bufferId: the buffer to connect to the ReadingDataHandler object. The first buffer has an Id = 0

• pError: set to a NSError derived class in case of error

ImebraStreamReader* ImebraTag::getStreamReader:error:(unsigned int bufferId, NSError ** pError)

Get a StreamReader connected to a buffer’s data.

Return

the streamReader connected to the buffer’s data.

Parameters

• bufferId: the id of the buffer for which the StreamReader is required. This parameter is usually 0

• pError: set to a NSError derived class in case of error

ImebraDataSet* ImebraTag::getSequenceItem:error:(unsigned int dataSetId, NSError ** pError)

Retrieve an embedded DataSet.

Sequence tags (VR=SQ) store embedded dicom structures.

Return

the sequence DataSet

Parameters

• dataSetId: the ID of the sequence item to retrieve. Several sequence items can be embedded in one tag.

• pError: set to a NSError derived class in case of error

BOOL ImebraTag::sequenceItemExists:(unsigned int dataSetId)

Check for the existance of a sequence item.

Return

true if the sequence item exists, false otherwise

Parameters

• dataSetId: the ID of the sequence item to check for

Property

property ImebraTag::dataType

Get the tag’s data type.

Return

the tag’s data type

MutableTag

C++

class MutableTag : public imebra::Tag

This class represents a mutable DICOM tag.

Public Functions

MutableTag(const MutableTag &source)

Copy constructor.

Parameters

• source: source MutableTag object

WritingDataHandler getWritingDataHandler(size_t bufferId)

Retrieve a WritingDataHandler object connected to a specific tag’s buffer.

If the specified Tag does not exist then it creates a new tag with the VR specified in the tagVR parameter

The returned WritingDataHandler is connected to a new buffer which is updated and stored in the tag when WritingDataHandler is destroyed.

Return

a WritingDataHandler object connected to a new Tag’s buffer

Parameters

• bufferId: the position where the new buffer has to be stored into the tag. The first buffer position is 0

WritingDataHandlerNumeric getWritingDataHandlerNumeric(size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to the Tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer

Parameters

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

WritingDataHandlerNumeric getWritingDataHandlerRaw(size_t bufferId)

Retrieve a WritingDataHandlerNumeric object connected to the Tag’s raw data buffer (8 bit unsigned integers).

If the tag’s VR is not a numeric type then throws std::bad_cast.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer (the buffer contains raw data of 8 bit integers)

Parameters

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

StreamWriter getStreamWriter(size_t bufferId)

Get a StreamWriter connected to a buffer’s data.

Return

the StreamWriter connected to the buffer’s data.

Parameters

• bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

MutableDataSet appendSequenceItem()

Append a sequence item into the Tag.

Several sequence items can be nested one inside each other. When a sequence item is embedded into a Tag, then the tag will have a sequence VR (VR = SQ).

Return

the MutableDataSet representing the added sequence item

void setStream(size_t bufferId, FileStreamInput &streamInput)

Set the tag’s content to the content of a file.

The tag will just keep a reference to the file content.

This is useful when embedding large objects into a dataset (e.g. a MPEG file acquired by the device).

Parameters

• bufferId: the id of the buffer to which the content is added

• streamInput: the file into which the tag’s content is stored

Objective-C/Swift

class ImebraMutableTag : public ImebraTag

This class represents a DICOM tag.

Public Functions

ImebraWritingDataHandler* ImebraMutableTag::getWritingDataHandler:error:(unsigned int bufferId, NSError ** pError)

Retrieve a ImebraWritingDataHandler object connected to a specific tag’s buffer.

If the specified buffer does not exist then it creates a new buffer.

Return

a ImebraWritingDataHandler object connected to a new tag’s buffer

Parameters

• bufferId: the position where the new buffer has to be stored into the tag. The first buffer position is 0

• pError: set to a NSError derived class in case of error

ImebraWritingDataHandlerNumeric* ImebraMutableTag::getWritingDataHandlerNumeric:error:(unsigned int bufferId, NSError ** pError)

Retrieve a WritingDataHandlerNumeric object connected to the Tag’s buffer.

If the tag’s VR is not a numeric type then throws std::bad_cast.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer

Parameters

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• pError: set to a NSError derived class in case of error

ImebraWritingDataHandlerNumeric* ImebraMutableTag::getWritingDataHandlerRaw:error:(unsigned int bufferId, NSError ** pError)

Retrieve a WritingDataHandlerNumeric object connected to the Tag’s raw data buffer (8 bit unsigned integers).

If the tag’s VR is not a numeric type then throws std::bad_cast.

The returned WritingDataHandlerNumeric is connected to a new buffer which is updated and stored into the tag when WritingDataHandlerNumeric is destroyed.

Return

a WritingDataHandlerNumeric object connected to a new Tag’s buffer (the buffer contains raw data of 8 bit integers)

Parameters

• bufferId: the position where the new buffer has to be stored in the tag. The first buffer position is 0

• pError: set to a NSError derived class in case of error

ImebraStreamWriter* ImebraMutableTag::getStreamWriter:error:(unsigned int bufferId, NSError ** pError)

Get a StreamWriter connected to a buffer’s data.

Return

the StreamWriter connected to the buffer’s data.

Parameters

• bufferId: the id of the buffer for which the StreamWriter is required. This parameter is usually 0

• pError: set to a NSError derived class in case of error

ImebraMutableDataSet* ImebraMutableTag::appendSequenceItem:((swift_error(nonnull_error)) __attribute__)

Append a sequence item into the Tag.

Several sequence items can be nested one inside each other. When a sequence item is embedded into a Tag, then the tag will have a sequence VR (VR = SQ).

Return

a MutableDataSet representing the added sequence item

Parameters

• pError: set to a NSError derived class in case of error

void ImebraMutableTag::setStream:stream:error:(unsigned int bufferId, ImebraFileStreamInput * pStream, NSError ** pError)

Set the tag’s content to the content of a file.

The tag will just keep a reference to the file content.

This is useful when embedding large objects into a dataset (e.g. a MPEG file acquired by the device).

Parameters

• bufferId: the id of the buffer to which the content is added

• streamInput: the file into which the tag’s content is stored

Data access

The data handler allow to read and write the data stored in the tags.

In order to write data into a tag you can:

• use the helper methods in DataSet

• obtain a WritingDataHandler for the desidered tag and use it to write the data.

The WritingDataHandler has the advantage of being able to write multiple elements in the Tag, while the helper methods in the DataSet can write only the first element.

The WritingDataHandler writes all the data into a new buffer, which replaces the old buffer in the Tag only when the data handler is deleted.

Sequence diagram showing how to use a WritingDataHandler

TagId

C++

class TagId

Represents a Dicom tag’s identification.

Public Functions

TagId()

Default constructor.

Initializes the group id and the tag id to 0.

TagId(std::uint16_t groupId, std::uint16_t tagId)

Constructor.

Parameters

• groupId: the group id

• tagId: the tag id

TagId(std::uint16_t groupId, std::uint32_t groupOrder, std::uint16_t tagId)

Constructor.

Parameters

• groupId: the group id

• groupOrder: old DICOM files may have several groups with the same id. This parameter specifies which of the groups with the same id must be taken into consideration

• tagId: the tag id

TagId(tagId_t id)

Constructor.

Warning

Very large enumeration classes cause an error in Java, therefore the tagId_t enumeration is not supported in Java.

Parameters

• id: an enumeration representing a tag group and id

TagId(tagId_t id, std::uint32_t groupOrder)

Constructor.

Parameters

• id: an enumeration representing a tag group and id

• groupOrder: old DICOM files may have several groups with the same id. This parameter specifies which of the groups with the same id must be taken into consideration

std::uint16_t getGroupId() const

Retrieve the group id.

Return

the group id

std::uint32_t getGroupOrder() const

Return the group order. Old DICOM files may have several groups with the same id. This value specifies which of the groups with the same id has been taken into consideration.

Return

the group order

std::uint16_t getTagId() const

Retrieve the tag id.

Return

the tag id

Objective-C/Swift

class ImebraTagId : public NSObject

Represents a Dicom tag’s identification.

Public Functions

id ImebraTagId::initWithGroup:tag:(unsigned short groupId, unsigned short tagId)

Initializer.

Parameters

• groupId: the group id

• tagId: the tag id

id ImebraTagId::initWithId:(ImebraTagEnum tagId)

Initializer.

Parameters

• id: an enumeration representing a tag group and id

id ImebraTagId::initWithGroup:groupOrder:tag:(unsigned short groupId, unsigned int groupOrder, unsigned short tagId)

Initializer.

Parameters

• groupId: the group id

• groupOrder: old DICOM files may have several groups with the same id. This parameter specifies which of the groups with the same id must be taken into consideration

• tagId: the tag id

Property

property ImebraTagId::groupId

Retrieve the group id.

property ImebraTagId::groupOrder

Return the group order. Old DICOM files may have several groups with the same id. This value specifies which of the groups with the same id has been taken into consideration.

property ImebraTagId::tagId

Retrieve the tag id.

ReadingDataHandler

C++

class ReadingDataHandler

The ReadingDataHandler class allows reading the content of a Dicom Tag.

ReadingDataHandler is able to return the Tag’s content as a string, a number, a date/time or an age.

In order to obtain a ReadingDataHandler object for a specific Tag stored in a DataSet, call DataSet::getReadingDataHandler() or Tag::getReadingDataHandler().

The ReadingDataHandler object keeps a reference to the buffer’s memory: the buffer’s memory is never modified but only replaced by a new memory area, therefore the ReadingDataHandler client does not need to worry about other clients modifying the memory being read.

Subclassed by imebra::ReadingDataHandlerNumeric

Public Functions

ReadingDataHandler(const ReadingDataHandler &source)

Copy constructor.

Parameters

• source: source ReadingDataHandler object

size_t getSize() const

Returns the number of elements in the Tag’s buffer handled by the data handler.

If the ReadingDataHandler object is related to a buffer that contains strings then it returns the number of strings stored in the buffer. Multiple strings are separated by a separator char.

Return

the number of elements stored in the handled Dicom buffer

tagVR_t getDataType() const

Returns the data type (VR) of the data handled by the data handler.

Return

the data type of the handled data

std::int64_t getInt64(size_t index) const

Retrieve a buffer’s value as signed 64 bit integer.

If the buffer’s value cannot be converted to a signed 64 bit integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a signed 64 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::int32_t getInt32(size_t index) const

Retrieve a buffer’s value as signed long integer (32 bit).

If the buffer’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a signed 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::int32_t getSignedLong(size_t index) const

Deprecated. Use getInt32() instead.

std::uint64_t getUint64(size_t index) const

Retrieve a buffer’s value as an unsigned 64 bit integer.

If the buffer’s value cannot be converted to an unsigned 64 bit integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as an unsigned 64 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::uint32_t getUint32(size_t index) const

Retrieve a buffer’s value as an unsigned long integer (32 bit).

When calling getUint32() on an AT tag (Attribute Tag) then the tag group is always in the high word of the returned value.

If the buffer’s value cannot be converted to an unsigned long integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::uint32_t getUnsignedLong(size_t index) const

Deprecated. Use getUint32() instead.

std::int16_t getInt16(size_t index) const

Retrieve a buffer’s value as signed long integer (16 bit).

If the buffer’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a signed 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::uint16_t getUint16(size_t index) const

Retrieve a buffer’s value as an unsigned long integer (16 bit).

If the buffer’s value cannot be converted to an unsigned long integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::int8_t getInt8(size_t index) const

Retrieve a buffer’s value as signed long integer (8 bit).

If the buffer’s value cannot be converted to a signed long integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a signed 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::uint8_t getUint8(size_t index) const

Retrieve a buffer’s value as an unsigned long integer (8 bit).

If the buffer’s value cannot be converted to an unsigned long integer then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

double getDouble(size_t index) const

Retrieve a buffer’s value as a double floating point value (64 bit).

If the buffer’s value cannot be converted to a double value then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a double floating point value (64 bit)

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

float getFloat(size_t index) const

Retrieve a buffer’s value as a floating point value (32 bit).

If the buffer’s value cannot be converted to a float value then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a floating point value (32 bit)

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::string getString(size_t index) const

Retrieve a buffer’s value as a UTF8 string.

If the buffer’s value cannot be converted to a string then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as an ASCII string

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

std::wstring getUnicodeString(size_t index) const

Retrieve a buffer’s value as a Unicode string.

If the buffer’s value cannot be converted to a string then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a Unicode string

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

const Date getDate(size_t index) const

Retrieve a buffer’s value a date or time.

If the buffer’s value cannot be converted to a date or time then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a date or time

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

const Age getAge(size_t index) const

Retrieve a buffer’s value as an Age.

If the buffer’s value cannot be converted to an Age then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as an Age

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

const PatientName getPatientName(size_t index) const

Retrieve a tag’s value as a Patient Name.

If the tag’s value cannot be converted to a patient name then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a Patient Name

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

const UnicodePatientName getUnicodePatientName(size_t index) const

Retrieve a tag’s value as a Unicode Patient Name.

If the tag’s value cannot be converted to a patient name then throws DataHandlerConversionError.

Throws MissingItemError if the requested index does not exist.

Return

the tag’s value as a Unicode Patient Name

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

Objective-C/Swift

class ImebraReadingDataHandler : public NSObject

ImebraReadingDataHandler allows reading the content of a Dicom Tag.

ImebraReadingDataHandler is able to return the Tag’s content as a string, a number, a date/time or an age.

In order to obtain a ImebraReadingDataHandler object for a specific ImebraTag stored in a ImebraDataSet, call ImebraDataSet::getReadingDataHandler() or ImebraTag::getReadingDataHandler().

ImebraReadingDataHandler keeps a reference to the buffer’s memory: the buffer’s memory is never modified but only replaced by a new memory area, therefore the ReadingDataHandler client does not need to worry about other clients modifying the memory being read.

Subclassed by ImebraReadingDataHandlerNumeric

Public Functions

signed long long ImebraReadingDataHandler::getInt64:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as signed very long integer (64 bit).

If the buffer’s value cannot be converted to a signed very long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a signed 364 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

signed int ImebraReadingDataHandler::getInt32:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as signed long integer (32 bit).

If the buffer’s value cannot be converted to a signed long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a signed 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

signed int ImebraReadingDataHandler::getSignedLong:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use getInt32() instead.

signed short ImebraReadingDataHandler::getInt16:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as signed short integer (16 bit).

If the buffer’s value cannot be converted to a signed long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a signed 16 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

signed char ImebraReadingDataHandler::getInt8:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as signed char integer (8 bit).

If the buffer’s value cannot be converted to a signed long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a signed 8 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

unsigned long long ImebraReadingDataHandler::getUint64:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as an unsigned very long integer (64 bit).

If the buffer’s value cannot be converted to a unsigned very long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as an unsigned 64 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

unsigned int ImebraReadingDataHandler::getUint32:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as an unsigned long integer (32 bit).

When calling getUint32() on an AT tag (Attribute Tag) then the tag group is always in the high word of the returned value.

If the buffer’s value cannot be converted to a unsigned long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as an unsigned 32 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

unsigned int ImebraReadingDataHandler::getUnsignedLong:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use getUint32() instead.

unsigned short ImebraReadingDataHandler::getUint16:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as an unsigned short integer (16 bit).

If the buffer’s value cannot be converted to a unsigned long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as an unsigned 16 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

unsigned char ImebraReadingDataHandler::getUint8:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as an unsigned char integer (8 bit).

If the buffer’s value cannot be converted to a unsigned long integer then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as an unsigned 8 bit integer

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

double ImebraReadingDataHandler::getDouble:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as a double floating point value (64 bit).

If the buffer’s value cannot be converted to a double floating point then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a double floating point value (64 bit)

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

float ImebraReadingDataHandler::getFloat:error:(unsigned int index, (swift_error(nonnull_error)) __attribute__)

Retrieve a buffer’s value as a floating point value (32 bit).

If the buffer’s value cannot be converted to a double floating point then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a floating point value (32 bit)

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

NSString* ImebraReadingDataHandler::getString:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as a string.

If the buffer’s value cannot be converted to a string then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a string

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

ImebraDate* ImebraReadingDataHandler::getDate:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as date or time.

If the buffer’s value cannot be converted to a date or time then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a date or time

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

ImebraPatientName* ImebraReadingDataHandler::getPatientName:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as patient name.

If the buffer’s value cannot be converted to a patient name then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as a date or time

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

ImebraAge* ImebraReadingDataHandler::getAge:error:(unsigned int index, NSError ** pError)

Retrieve a buffer’s value as an age.

If the buffer’s value cannot be converted to an age then set pError to ImebraDataHandlerConversionError.

Return

the tag’s value as an Age

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• pError: set to a NSError derived class in case of error

Property

property ImebraReadingDataHandler::size

Returns the number of elements in the tag’s buffer handled by the data handler.

If the ImebraReadingDataHandler object is related to a buffer that contains strings then it returns the number of strings stored in the buffer. Multiple strings are separated by a separator char.

ReadingDataHandlerNumeric

C++

class ReadingDataHandlerNumeric : public imebra::ReadingDataHandler

Specialized ReadingDataHandler for numeric data types.

Includes few methods that allow accessing the raw memory containing the buffer’s data.

Public Functions

ReadingDataHandlerNumeric(const ReadingDataHandlerNumeric &source)

Copy constructor.

Parameters

• source: source ReadingDataHandlerNumeric object

const Memory getMemory() const

Return a Memory object referencing the raw buffer’s data.

Return

a Memory object referencing the raw buffer’s data

size_t data(char *destination, size_t destinationSize) const

Copies the buffer’s raw memory content into the specified buffer.

If the allocated buffer is not large enough then the method doesn’t copy any data and just returns the required buffer’ size.

Java

In Java this method accepts a single parameter (a byte array). The size of the byte array must be equal or greater than the number of bytes stored by the data handler.

Return

the number of bytes copied into the pre-allocated buffer, or the desired size of destination if destinationSize is smaller than the return value

Parameters

• destination: a pointer to the allocated buffer

• destinationSize: the size of the allocated buffer

const char *data(size_t *pDataSize) const

Returns a pointer to the buffer’s raw memory content.

The referenced buffer is owned by the ReadingDataHandlerNumeric object and must not be freed by the client.

Return

a pointer to the buffer’s raw memory. The referenced buffer is owned by the ReadingDataHandlerNumeric object and must not be freed by the client.

Parameters

• pDataSize: a variable that will contain the raw memory’s size in bytes

size_t getUnitSize() const

Returns the number of bytes occupied by the numbers handled by the data handler.

Return

the number of bytes occupied by the numbers handled by the data handler

bool isSigned() const

Returns true if the numbers stored in the buffer are signed, false otherwise.

Return

true if the numbers stored in the buffer are signed, false otherwise

bool isFloat() const

Returns true if the numbers stored in the buffer are floating point numbers, false otherwise.

Return

true if the numbers stored in the buffer are floating point numbers, false otherwise

void copyTo(const WritingDataHandlerNumeric &destination)

Copies the content of the data handler into another data handler, converting the data to the destination handler data type.

Warning

the size of the destination data handler stays unchanged: if the destination is too small to contain all the data to be copied then only a part of the data will be copied.

Parameters

• destination: the destination data handler

Objective-C/Swift

class ImebraReadingDataHandlerNumeric : public ImebraReadingDataHandler

Specialized ImebraReadingDataHandler for numeric data types.

Includes few methods that allow accessing the raw memory containing the buffer’s data.

Public Functions

ImebraMemory* ImebraReadingDataHandlerNumeric::getMemory:((swift_error(nonnull_error)) __attribute__)

Return a ReadMemory object referencing the raw buffer’s data.

Return

a ReadMemory object referencing the raw buffer’s data

Parameters

• pError: set to a NSError derived class in case of error

void ImebraReadingDataHandlerNumeric::copyTo:error:(ImebraWritingDataHandlerNumeric * destination, (swift_error(nonnull_error)) __attribute__)

Copies the content of the data handler into another data handler, converting the data to the destination handler data type.

Warning

the size of the destination data handler stays unchanged: if the destination too small to contain all the data to be copied then only a part of the data will be copied.

Parameters

• pError: set to a NSError derived class in case of error

• destination: the destination data handler

Property

property ImebraReadingDataHandlerNumeric::unitSize

Returns the number of bytes occupied by the numbers handled by the data handler.

property ImebraReadingDataHandlerNumeric::isSigned

Returns true if the numbers stored in the buffer are signed, false otherwise.

property ImebraReadingDataHandlerNumeric::isFloat

Returns true if the numbers stored in the buffer are floating point numbers, false otherwise.

WritingDataHandler

C++

class WritingDataHandler

The WritingDataHandler class allows to write the content of a Dicom tag’s buffer.

WritingDataHandler is able to write into the buffer’s content strings, numbers, date/time or ages.

In order to obtain a WritingDataHandler object for a specific tag stored in a DataSet, call DataSet::getWritingDataHandler() or Tag::getWritingDataHandler().

The WritingDataHandler object always works on a new and clean memory area. The buffer’s memory is replaced by the WritingDataHandler memory when the data handler is destroyed.

Subclassed by imebra::WritingDataHandlerNumeric

Public Functions

WritingDataHandler(const WritingDataHandler &source)

Copy constructor.

Parameters

• source: source WritingDataHandler object

virtual ~WritingDataHandler()

Destructor: replaces the tag buffer’s memory with the memory created by this WritingDataHandler.

void setSize(size_t elementsNumber)

Resize the memory to contain the specified number of elements.

By default, the WritingDataHandler buffer allocates an empty memory block that must be resized in order to be filled with data.

The type of the contained elements depends on the tag’s VR. The VR can be retrieved with getDataType().

Parameters

• elementsNumber: the number of elements to store in the buffer.

size_t getSize() const

Retrieve the number of elements that can be stored in the buffer controlled by WritingDataHandler.

The memory size can be changed with setSize().

The type of the contained elements depends on the tag’s VR. The VR can be retrieved with getDataType().

Return

the number of elements that can be stored in the buffer

tagVR_t getDataType() const

Returns the data type (VR) of the data handled by the data handler.

Return

the data type of the handled data

void setInt64(size_t index, std::int64_t value)

Write a 64 bit signed integer.

If the value cannot be converted from a 64 bit signed integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setInt32(size_t index, std::int32_t value)

Write a signed long integer (32 bit).

If the value cannot be converted from a signed long integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setSignedLong(size_t index, std::int32_t value)

Deprecated. Use setInt32() instead.

void setUint64(size_t index, std::uint64_t value)

Write an unsigned 64 bit integer.

If the value cannot be converted from an unsigned 64 bit integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setUint32(size_t index, std::uint32_t value)

Write an unsigned long integer (32 bit).

When setting a value for an AT tag (Attribute Tag) then the tag’s group must always be in the higher 16 bits of the value.

If the value cannot be converted from an unsigned long integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setUnsignedLong(size_t index, std::uint32_t value)

Deprecated. Use setUint32() instead.

void setInt16(size_t index, std::int16_t value)

Write a signed long integer (16 bit).

If the value cannot be converted from a signed long integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setUint16(size_t index, std::uint16_t value)

Write an unsigned long integer (16 bit).

If the value cannot be converted from an unsigned long integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setInt8(size_t index, std::int8_t value)

Write a signed long integer (8 bit).

If the value cannot be converted from a signed long integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setUint8(size_t index, std::uint8_t value)

Write an unsigned long integer (8 bit).

If the value cannot be converted from an unsigned long integer then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setDouble(size_t index, double value)

Write a double floating point value (64 bit).

If the value cannot be converted from a double floating point then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setFloat(size_t index, float value)

Write a floating point value (32 bit).

If the value cannot be converted from a floating point then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setString(size_t index, const std::string &value)

Write a UTF8 string.

If the value cannot be converted from a string then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setUnicodeString(size_t index, const std::wstring &value)

Write an Unicode string.

If the value cannot be converted from a Unicode string then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• value: the value to write

void setDate(size_t index, const Date &date)

Write a date and/or a time.

If the value cannot be converted from a Date then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• date: the value to write

void setAge(size_t index, const Age &age)

Write an Age value.

If the value cannot be converted from an Age then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• age: the value to write

void setPatientName(size_t index, const PatientName &patientName)

Write a PatientName value.

If the value cannot be converted from a PatientName value then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• age: the value to write

void setUnicodePatientName(size_t index, const UnicodePatientName &patientName)

Write a UnicodePatientName value.

If the value cannot be converted from a PatientName value then throws DataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than getSize()

• age: the value to write

Objective-C/Swift

class ImebraWritingDataHandler : public NSObject

ImebraWritingDataHandler allows to write the content of a Dicom tag’s buffer.

ImebraWritingDataHandler is able to write strings, numbers, date/time or ages.

In order to obtain a ImebraWritingDataHandler object for a specific tag call ImebraDataSet::getWritingDataHandler() or ImebraTag::getWritingDataHandler().

The ImebraWritingDataHandler object always works on a new and clean memory area. Once the data has been written into the data handler then call commit (ImebraWritingDataHandler) in order to commit the data. The data is committed also when the data handler is deallocated.

Once the data has been committed then the data handler does not respond to further data modifications.

Subclassed by ImebraWritingDataHandlerNumeric

Public Functions

void ImebraWritingDataHandler::setInt64:newValue:error:(unsigned int index, signed long long value, (swift_error(nonnull_error)) __attribute__)

Write a signed very long integer (64 bit).

If the value cannot be converted from a signed very long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setInt32:newValue:error:(unsigned int index, signed int value, (swift_error(nonnull_error)) __attribute__)

Write a signed long integer (32 bit).

If the value cannot be converted from a signed long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setSignedLong:newValue:error:(unsigned int index, signed int value, (swift_error(nonnull_error)) __attribute__)

\bried Deprecated. Use setInt32() instead.

void ImebraWritingDataHandler::setInt16:newValue:error:(unsigned int index, signed short value, (swift_error(nonnull_error)) __attribute__)

Write a signed short integer (16 bit).

If the value cannot be converted from a signed long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setInt8:newValue:error:(unsigned int index, signed char value, (swift_error(nonnull_error)) __attribute__)

Write a signed char integer (8 bit).

If the value cannot be converted from a signed long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setUint64:newValue:error:(unsigned int index, unsigned long long value, (swift_error(nonnull_error)) __attribute__)

Write an unsigned very long integer (64 bit).

If the value cannot be converted from an unsigned very long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setUint32:newValue:error:(unsigned int index, unsigned int value, (swift_error(nonnull_error)) __attribute__)

Write an unsigned long integer (32 bit).

When setting a value for an AT tag (Attribute Tag) then the tag’s group must always be in the higher 16 bits of the value.

If the value cannot be converted from an unsigned long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setUnsignedLong:newValue:error:(unsigned int index, unsigned int value, (swift_error(nonnull_error)) __attribute__)

Deprecated. Use setUint32() instead.

void ImebraWritingDataHandler::setUint16:newValue:error:(unsigned int index, unsigned short value, (swift_error(nonnull_error)) __attribute__)

Write an unsigned short integer (16 bit).

If the value cannot be converted from an unsigned long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setUint8:newValue:error:(unsigned int index, unsigned char value, (swift_error(nonnull_error)) __attribute__)

Write an unsigned char integer (8 bit).

If the value cannot be converted from an unsigned long integer then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setDouble:newValue:error:(unsigned int index, double value, (swift_error(nonnull_error)) __attribute__)

Write a double floating point value (64 bit).

If the value cannot be converted from a double floating point then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setFloat:newValue:error:(unsigned int index, float value, (swift_error(nonnull_error)) __attribute__)

Write a floating point value (32 bit).

If the value cannot be converted from a double floating point then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setString:newValue:error:(unsigned int index, NSString * value, (swift_error(nonnull_error)) __attribute__)

Write a string.

If the value cannot be converted from a string then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setDate:newValue:error:(unsigned int index, ImebraDate * value, (swift_error(nonnull_error)) __attribute__)

Write a date and/or a time.

If the value cannot be converted from a Date then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setAge:newValue:error:(unsigned int index, ImebraAge * value, (swift_error(nonnull_error)) __attribute__)

Write an Age value.

If the value cannot be converted from an Age then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandler::setPatientName:newValue:error:(unsigned int index, ImebraPatientName * value, (swift_error(nonnull_error)) __attribute__)

Write a patient name.

If the value cannot be converted to a patient name then set pError to ImebraDataHandlerConversionError.

Parameters

• index: the element number within the buffer. Must be smaller than size()

• value: the value to write

• pError: set to a NSError derived class in case of error

void commit()

Commit the changes to the handler’s memory.

Property

property ImebraWritingDataHandler::size

Resize the memory to contain the specified number of elements or return the current number of elements when read.

By default, ImebraWritingDataHandler allocates an empty memory block that must be resized in order to be filled with data.

WritingDataHandlerNumeric

C++

class WritingDataHandlerNumeric : public imebra::WritingDataHandler

Specialized WritingDataHandler for numeric data types.

Includes few methods that allow accessing the raw memory containing the buffer’s data.

Public Functions

WritingDataHandlerNumeric(const WritingDataHandlerNumeric &source)

Copy constructor.

Parameters

• source: source WritingDataHandlerNumeric object

MutableMemory getMemory() const

Return a MutableMemory object referencing the raw buffer’s data.

Return

a MutableMemory object referencing the raw buffer’s data

void assign(const char *source, size_t sourceSize)

Copy the content of the specified buffer into the content managed by data handler.

Java

In Java this method accepts a single parameter (a byte array).

Parameters

• source: a pointer to the source memory buffer

• sourceSize: the number of bytes to copy and the new memory size

char *data(size_t *pDataSize) const

Returns a pointer to the buffer’s raw memory content.

The referenced buffer is owned by the WritingDataHandlerNumeric object and must not be freed by the client.

Return

a pointer to the buffer’s raw memory. The referenced buffer is owned by the WritingDataHandlerNumeric object and must not be freed by the client

Parameters

• pDataSize: a variable that will contain the raw memory’s size in bytes

size_t data(char *destination, size_t destinationSize) const

Copies the raw memory content into the specified buffer.

If the allocated buffer is not large enough then the method doesn’t copy any data and just returns the required buffer’ size.

Return

the number of bytes to be copied into the pre-allocated buffer

Parameters

• destination: a pointer to the allocated buffer

• destinationSize: the size of the allocated buffer, in bytes

size_t getUnitSize() const

Returns the number of bytes occupied by the numbers handled by the data handler.

Return

the number of bytes occupied by the numbers handled by the data handler

bool isSigned() const

Returns true if the numbers handled by the data handler are signed, false otherwise.

Return

true if the numbers handled by the data handler are signed, false otherwise

bool isFloat() const

Returns true if the numbers stored in the buffer are floating point numbers, false otherwise.

Return

true if the numbers stored in the buffer are floating point numbers, false otherwise

void copyFrom(const ReadingDataHandlerNumeric &source)

Copies data from another data handler, converting the data type if necessary.

The data handler is resized to the same size of the source data handler.

Parameters

• source: the data handler from which the data must be copied

Objective-C/Swift

class ImebraWritingDataHandlerNumeric : public ImebraWritingDataHandler

Specialized ImebraWritingDataHandler for numeric data types.

Includes few methods that allow accessing the raw memory containing the buffer’s data.

Public Functions

ImebraMutableMemory* ImebraWritingDataHandlerNumeric::getMemory:(NSError ** pError)

Return a ImebraMutableMemory object referencing the raw buffer’s data.

Return

a ImebraMutableMemory object referencing the raw buffer’s data

Parameters

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandlerNumeric::assign:error:(NSData * pSource, (swift_error(nonnull_error)) __attribute__)

Copy the content of the specified buffer into the content managed by data handler.

Parameters

• pSource: a pointer to the source memory buffer

• pError: set to a NSError derived class in case of error

void ImebraWritingDataHandlerNumeric::copyFrom:error:(ImebraReadingDataHandlerNumeric * pSource, (swift_error(nonnull_error)) __attribute__)

Copies data from another data handler, converting the data type if necessary.

The data handler is resized to the same size of the source data handler.

Parameters

• pSource: the data handler from which the data must be copied

• pError: set to a NSError derived class in case of error

Property

property ImebraWritingDataHandlerNumeric::unitSize

Returns the number of bytes occupied by each number handled by the data handler.

property ImebraWritingDataHandlerNumeric::isSigned

Returns true if the numbers handled by the data handler are signed, false otherwise.

property ImebraWritingDataHandlerNumeric::isFloat

Returns true if the numbers stored in the buffer are floating point numbers, false otherwise.

Date

C++

class Date

Stores a Date, Time or Date/Time value.

Public Functions

Date(const Date &source)

Copy constructor.

Parameters

• source: source Date object

Date(const std::uint32_t initialYear, const std::uint32_t initialMonth, const std::uint32_t initialDay, const std::uint32_t initialHour, const std::uint32_t initialMinutes, const std::uint32_t initialSeconds, const std::uint32_t initialNanoseconds, const std::int32_t initialOffsetHours, const std::int32_t initialOffsetMinutes)

Constructor.

Initialize the Date structure with the specified values.

Parameters

• initialYear: year (0 = unused)

• initialMonth: month (1…12, 0 = unused)

• initialDay: day of the month (1…31, 0 = unused)

• initialHour: hour (0…23)

• initialMinutes: minutes (0…59)

• initialSeconds: seconds (0…59)

• initialNanoseconds: nanoseconds

• initialOffsetHours: hours offset from UTC

• initialOffsetMinutes: minutes offset from UTC

Objective-C/Swift

class ImebraDate : public NSObject

Public Functions

id ImebraDate::initWithYear:month:day:hour:minutes:seconds:nanoseconds:offsetHours:offsetMinutes:(unsigned int initialYear, unsigned int initialMonth, unsigned int initialDay, unsigned int initialHour, unsigned int initialMinutes, unsigned int initialSeconds, unsigned int initialNanoseconds, int initialOffsetHours, int initialOffsetMinutes)

Constructor.

Initialize the Date structure with the specified values.

Parameters

• initialYear: year (0 = unused)

• initialMonth: month (1…12, 0 = unused)

• initialDay: day of the month (1…31, 0 = unused)

• initialHour: hour (0…23)

• initialMinutes: minutes (0…59)

• initialSeconds: seconds (0…59)

• initialNanoseconds: nanoseconds

• initialOffsetHours: hours offset from UTC

• initialOffsetMinutes: minutes offset from UTC

Property

property ImebraDate::year

Year (0 = unused)

property ImebraDate::month

Month (1…12, 0 = unused)

property ImebraDate::day

Day (1…12, 0 = unused)

property ImebraDate::hour

Hours.

property ImebraDate::minutes

Minutes.

property ImebraDate::seconds

Seconds.

property ImebraDate::nanoseconds

Nanoseconds.

property ImebraDate::offsetHours

Offset hours from UTC.

property ImebraDate::offsetMinutes

Offset minutes from UTC.

Age

C++

class Age

Specifies an age, in days, weeks, months or years.

Public Functions

Age(const Age &source)

Copy constructor.

Parameters

• source: source Date object

Age(std::uint32_t initialAge, ageUnit_t initialUnits)

Constructor.

Parameters

• initialAge: the initial age to assign to the object, in days, weeks, months or years, depending on the parameter initialUnits

• initialUnits: the units of the value in initialAge

double getYears() const

Return the age in years.

Return

the stored age converted to years.

Objective-C/Swift

class ImebraAge : public NSObject

Specifies an age, in days, weeks, months or years.

Public Functions

id ImebraAge::initWithAge:units:(unsigned int initialAge, ImebraAgeUnit initialUnits)

Constructor.

Parameters

• initialAge: the initial age to assign to the object, in days, weeks, months or years, depending on the parameter initialUnits

• initialUnits: the units of the value in initialAge

Property

property ImebraAge::years

Return the age in years.

Return

the stored age converted to years.

property ImebraAge::age

Return the age in the units returned by the property units.

Return

the stored age, speficied using the stored units.

property ImebraAge::units

Return the age’s units.

Return

the age’s units

PatientName

C++

class PatientName

Stores a patient name (in alphabetic, ideographic and phonetic forms).

Public Functions

PatientName(const PatientName &source)

Copy constructor.

Parameters

• source: source PatientName object

PatientName(const std::string &alphabeticRepresentation, const std::string &ideographicRepresentation, const std::string &phoneticRepresentation)

Constructor.

Parameters

• alphabeticRepresentation: the alphabetic representation of the patient name (UTF8 encoded)

• ideographicRepresentation: the ideographic representation of the patient name (UTF8 encoded)

• phoneticRepresentation: the phonetic representation of the patient name (UTF8 encoded)

std::string getAlphabeticRepresentation() const

Returns the alphabetic form of the patient name (UTF8 encoded).

Return

alphabetic representation of the patient name

std::string getIdeographicRepresentation() const

Returns the ideographic form of the patient name (UTF8 encoded).

Return

ideographic representation of the patient name

std::string getPhoneticRepresentation() const

Returns the phonetic form of the patient name (UTF8 encoded).

Return

phonetic representation of the patient name

Objective-C/Swift

class ImebraPatientName : public NSObject

Public Functions

id ImebraPatientName::initWithAlphabeticRepresentation:ideographicRepresentation:phoneticRepresentation:(NSString * alphabeticRepresentation, NSString * ideographicRepresentation, NSString * phoneticRepresentation)

Constructor.

Initialize the PatientName structure with the specified values.

Parameters

• alphabeticRepresentation: The alphabetic representation of the patient name

• ideographicRepresentation: The ideographic representation of the patient name. Can be left empty

• phoneticRepresentation: The phonetic representation of the patient name. Can be left empty

Property

property ImebraPatientName::alphabeticRepresentation

The alphabetic representation of the Patient Name.

property ImebraPatientName::ideographicRepresentation

The ideographic representation of the Patient Name.

property ImebraPatientName::phoneticRepresentation

The phonetic representation of the Patient Name.

UnicodePatientName

C++

class UnicodePatientName

Stores a patient name with Unicode chars (in alphabetic, ideographic and phonetic forms).

Public Functions

UnicodePatientName(const UnicodePatientName &source)

Copy constructor.

Parameters

• source: source PatientName object

UnicodePatientName(const std::wstring &alphabeticRepresentation, const std::wstring &ideographicRepresentation, const std::wstring &phoneticRepresentation)

Constructor.

Parameters

• alphabeticRepresentation: the alphabetic representation of the patient name

• ideographicRepresentation: the ideographic representation of the patient name

• phoneticRepresentation: the phonetic representation of the patient name

std::wstring getAlphabeticRepresentation() const

Returns the alphabetic form of the patient name.

Return

alphabetic representation of the patient name

std::wstring getIdeographicRepresentation() const

Returns the ideographic form of the patient name.

Return

ideographic representation of the patient name

std::wstring getPhoneticRepresentation() const

Returns the phonetic form of the patient name.

Return

phonetic representation of the patient name

Objective-C/Swift

Not available (ImebraPatientName uses Unicode on Objective-C/Swift)