IDCXELM Interface Reference

This inteface is used to get and set DICOM Elements and their value. More...

Inherits IDispatch.

Public Member Functions
HRESULT	Init ([in] DICOM_TAG tag)
	Initalize from a DICOM Tag. More...
HRESULT	SetValueFromFile ([in] BSTR filename, [in] int offset, [in] int length)
	Set the value from the content of a file. More...
HRESULT	SetRawData ([in] int newVal, [in] long newLen)
HRESULT	GetRawData ([out] int *Val, [out] long *Len)
	see SetRawData
HRESULT	SetValueFromFileEx ([in] BSTR filename, [in] __int64 offset, [in] unsigned int length)
HRESULT	SetRawDataEx ([in] __int64 newVal, [in] long newLen)
HRESULT	GetRawDataEx ([out] __int64 *Val, [out] long *Len)
	see SetRawData More...

Properties
DICOM_TAG	Tag [get]
	Get the Elemenmt TAG.
VR_CODE	ValueRepresentation [get, set]
	Get/Set The Value Representation (VR) Code. More...
long	Length [get, set]
	Get The value length. More...
VARIANT	Value [get, set]
	Get/Set the element value. More...
__int3264	CStringPtr [get, set]
	Get/Set a string value element from a value pointer (C/C++ optimization). More...
long	ValueMultiplicity [get]
	Get the element's value multiplicity (VM).
VARIANT	ValueArray [get]
	Get/Set a multivalue tag as an array object (safearray). More...

Detailed Description

This inteface is used to get and set DICOM Elements and their value.

The DICOM Element can either be created directly or extracted from a DICOM Object using getElementByTag or [Element Iterator] (IDCXELMIterator). An element can be added to a DICOM Object using the IDCXOBJ insertElement method. For an example of using the DICOM Element Object see CPPDicomObjectExample.cpp

Member Function Documentation

GetRawDataEx()

HRESULT IDCXELM::GetRawDataEx	(	[out] __int64 *	Val,
		[out] long *	Len
	)

see SetRawData

Length of data in bytes

Init()

HRESULT IDCXELM::Init

(

[in] DICOM_TAG

tag

)

Initalize from a DICOM Tag.

Use this method to create a new element and then insert it to a IDCXOBJ. The DICOM Tag must be a valid one from the internal or extended Dictionary. This call also resets the Length to 0

SetRawData()

HRESULT IDCXELM::SetRawData	(	[in] int	newVal,
		[in] long	newLen
	)

Set/Get raw data into element, overriding all validation checks. The getter returns a pointer to the actual data and setter takes a pointer of buffer to copy into the elements data. Try avoiding this method and use it only for very specific cases when pusing or getting raw data is required. Using this method may cause competibility issues with other toolkits trying to read the brutaly inserted data. After setting this element, avoid calling any other methods of the element.

SetRawDataEx()

HRESULT IDCXELM::SetRawDataEx	(	[in] __int64	newVal,
		[in] long	newLen
	)

Set/Get raw data into OB/OW element, overriding all validation checks. The getter returns a pointer to the actual data and setter takes a pointer of buffer to copy into the elements data. Try avoiding this method and use it only for very specific cases when pusing or getting raw data is required. Using this method may cause competibility issues with other toolkits trying to read the brutaly inserted data. After setting this element, avoid calling any other methods of the element.

Parameters

newLen

8 byte Pointer to data casted to int

SetValueFromFile()

HRESULT IDCXELM::SetValueFromFile	(	[in] BSTR	filename,
		[in] int	offset,
		[in] int	length
	)

Set the value from the content of a file.

Use only with little endian transfer syntax. Use only for byte streams (i.e. for binaries VR OB, not OW). This method is provided in order to enable setting large buffers to elements like for example pixel data of large images or long sequeneces of multiframe objects. Length must be pair.

Precondition

File must exist prior to calling the method and throught the lifetime of the element and any object it is added to.

Returns

If the file doesn't exist, return E_FAIL with description "File not found" If the file doesn't exist, return E_FAIL with description "File not found" If length is not in range return E_INVALIDARG with description "Invalid length. Length must be Pair [0 - 2^32-2]"

Parameters

filename	The name of the data file
offset	The offset from the begining of the file in bytes, to start reading from
length	The number of bytes to read from the file

SetValueFromFileEx()

HRESULT IDCXELM::SetValueFromFileEx	(	[in] BSTR	filename,
		[in] __int64	offset,
		[in] unsigned int	length
	)

Same as SetValueFromFile but allows using input files larger than 4GB (2^32)

See also

SetValueFromFile

Parameters

filename	The name of the data file
offset	The offset from the begining of the file in bytes, to start reading from
length	The number of bytes to read from the file

Property Documentation

CStringPtr

__int3264 IDCXELM::CStringPtr

getsetproperty

Get/Set a string value element from a value pointer (C/C++ optimization).

This is an unsafe optimization method that is useful mainly for C++ programming. It bypasses the Double/Single byte characters conversions and thus is more efficient.

Length

long IDCXELM::Length

getsetproperty

Get The value length.

DICOM Data Element max size is 4GB (uint.maxvalue)

Note

the change made after v 2.0.8.7 that adds unsigned. See: https://docs.microsoft.com/en-us/windows/desktop/Midl/unsigned The value was always a Uint32 but the property signature was without the unsigned keyword

Caution!!!Use the Set method with special care! The Property set of value length is used only for special cases when the the value representation is OB or OW (e.g. Pixel Data) In these cases only the value is actually a pointer to the data and the Length property set is used.

Value

VARIANT IDCXELM::Value

getsetproperty

Get/Set the element value.

Type conversions are supported for string and basic types. The get method may change string values for specific VR's.
The following conversion apply:

• DA and DT: When getting the value of a DA (date) or DT (date-time) elements the return value is YYYY-MM-DD [HH:MM:SS.TTT]

ValueArray

VARIANT IDCXELM::ValueArray

getproperty

Get/Set a multivalue tag as an array object (safearray).

Note

set Not Implemented

ValueRepresentation

VR_CODE IDCXELM::ValueRepresentation

getsetproperty

Get/Set The Value Representation (VR) Code.

Use the Set property of VR code carefully! This method is intended to override the VR of the element that is set by default according to internal dictionary. It should be used for example to change the VR of Pixel Data element from OW (Default) to OB when creating 8 bit or Color image object. This method also enables VR changes for PRIVATE tags (not defined in the standard tags, characterized by ODD group number)