L_DicomInsertKey

#include "ltdic.h"

L_LTDIC_API pDICOMELEMENT L_DicomInsertKey(hDS, pParent, pszKey, bOptional)

HDICOMDS hDS;	/* a DICOM handle */
pDICOMELEMENT pParent;	/* pointer to a DICOMELEMENT structure */
L_TCHAR * pszKey;	/* type of key element to insert */
L_BOOL bOptional;	/* flag that indicates which elements to insert */

Inserts a new key element in the Dicom Dir Data Set.

Parameter	Description
hDS	A DICOM handle.
pParent	Pointer to a DICOMELEMENT structure that contains a key element in the Data Set. The new key element will be inserted as a child of this key element.
pszKey	Character string that contains the type of key element to insert. Possible values are:
	Value	Meaning
	"PATIENT"	Patient key element
	"STUDY"	Study key element
	"SERIES"	Series key element
	"IMAGE"	Image key element
	"OVERLAY"	Overlay key element
	"MODALITY LUT"	Modality-LUT key element
	"VOI LUT"	VOI-LUT key element
	"CURVE"	Curve key element
	"STORED PRINT"	Stored print key element
	"RT DOSE"	RT dose key element
	"RT STRUCTURE SET"	RT structure set key element
	"RT PLAN"	RT plan key element
	"RT TREAT RECORD"	RT treatment record key element
	"TOPIC"	Topic key element
	"VISIT"	Visit key element
	"RESULTS"	Results key element
	"INTERPRETATION"	Interpretation key element
	"STUDY COMPONENT"	Study Component key element
	"PRESENTATION"	Presentation key element
	"WAVEFORM"	Waveform key element
	"SR DOCUMENT"	Structured Reporting Document key element
	"PRIVATE"	Private key element
	"KEY OBJECT DOC"	Key Object Document key element
	"SPECTROSCOPY"	Spectroscopy key element
	"RAW DATA"	Raw Data key element
	"REGISTRATION"	Registration key element
	"FIDUCIAL"	Fiducial key element
	"HANGING PROTOCOL"	Hanging key element
	"ENCAP DOC"	Encapsulated Document key element
	"HL7 STRUC DOC"	HL7 Structured Document key element
	"VALUE MAP"	Real World Value Mapping key element
	"STEREOMETRIC"	Stereometric Relationship key element

bOptional	Flag that indicates which parts of the key element to insert. Possible values are:
	Value	Meaning
	TRUE	Insert all parts of the specified key element.
	FALSE	Insert only the mandatory parts of the specified key element.

Returns

!NULL	A pointer to a DICOMELEMENT structure containing the newly inserted item.
NULL	Not enough memory to insert the item.

Comments

The newly inserted key element is inserted as a child of pParent.

Required DLLs and Libraries

LTDIC

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

Platforms

Win32, x64

See Also

Functions:	L_DicomGetValueKey, L_DicomDeleteKey, L_DicomGetRootKey, L_DicomGetParentKey, L_DicomGetChildKey, L_DicomGetFirstKey, L_DicomGetLastKey, L_DicomGetPrevKey, L_DicomGetNextKey, L_DicomGetValueKey, L_DicomFindFirstKey, L_DicomFindLastKey, L_DicomFindPrevKey, L_DicomFindNextKey
Topics:	Working with Key Elements

Example

L_INT DicomInsertKeyExample(L_VOID)
{
   L_INT x;
   L_TCHAR szOut[200];
   L_TCHAR * pVal=NULL;
   HDICOMDS hDS=NULL;
   pDICOMELEMENT pKey=NULL;
   pDICOMELEMENT pElement=NULL;
   
   hDS = L_DicomCreateDS(NULL);
   L_DicomInitDS(hDS, CLASS_UNKNOWN, 0);

   /* insert some keys */
   pKey = L_DicomInsertKey(hDS, NULL, TEXT("PATIENT"), TRUE); /* insert PATIENT level key */
   if (pKey == NULL)
   {
      L_DicomFreeDS(hDS);
      return DICOM_ERROR_MEMORY;
   }

   pKey = L_DicomInsertKey(hDS, pKey, TEXT("STUDY"), TRUE); /* insert STUDY level key */
   if (pKey == NULL)
   {
      L_DicomFreeDS(hDS);
      return DICOM_ERROR_MEMORY;
   }
   
   /* insert 5 SERIES level keys and some data */
   for(x=1; x<=5; x++)
   {
      wsprintf(szOut, TEXT("%d"), x);
      pKey = L_DicomInsertKey(hDS, pKey, TEXT("SERIES"), TRUE);
      if (pKey == NULL)
      {
         L_DicomFreeDS(hDS);
         return DICOM_ERROR_MEMORY;
      }

      pElement = L_DicomGetChildElement(hDS, pKey, FALSE);
      pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
      if (!L_DicomSetStringValue(hDS, pElement, szOut, 1, DICOM_CHARACTER_SET_DEFAULT))
      {
         L_DicomFreeDS(hDS);
         return FAILURE - 1;
      }

      pKey = L_DicomGetParentKey(hDS, pKey); /*move back up one level */
   }
   
   /* move to root key */
   pKey = L_DicomGetRootKey(hDS, pKey); /* PATIENT level */
   MessageBox(NULL, L_DicomGetValueKey(hDS, pKey), TEXT("Test"), MB_OK);
      
   /* move to SERIES level */
   pKey = L_DicomGetChildKey(hDS, pKey); /*STUDY*/
   pKey = L_DicomGetChildKey(hDS, pKey); /*SERIES*/
   
   /* find first SERIES */
   pKey = L_DicomFindFirstKey(hDS, pKey, TEXT("SERIES"), TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);
   
   /* find next series */
   pKey = L_DicomFindNextKey(hDS, pKey, TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);
   
   /* find last SERIES */
   pKey = L_DicomFindLastKey(hDS, pKey, TEXT("SERIES"), TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);
   
   /* find previous SERIES */
   pKey = L_DicomFindPrevKey(hDS, pKey, TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);

   /* find last SERIES and delete it */
   pKey = L_DicomFindLastKey(hDS, pKey, TEXT("SERIES"), TRUE);
   L_DicomDeleteKey(hDS, pKey);
   
   /* move to root key */
   pKey = L_DicomGetFirstKey(hDS, NULL, FALSE);
   MessageBox(NULL, L_DicomGetValueKey(hDS, pKey), TEXT("Test"), MB_OK);
   
   /* move to SERIES level */
   pKey = L_DicomGetChildKey(hDS, pKey); /*STUDY*/
   pKey = L_DicomGetChildKey(hDS, pKey); /*SERIES*/
   
   /* move to first SERIES */
   pKey = L_DicomGetFirstKey(hDS, pKey, TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);
   
   /* move to next series */
   pKey = L_DicomGetNextKey(hDS, pKey, TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);
   
   /* move to last SERIES */
   pKey = L_DicomGetLastKey(hDS, pKey, TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);
   
   /* move to previous SERIES */
   pKey = L_DicomGetPrevKey(hDS, pKey, TRUE);
   pElement = L_DicomGetChildElement(hDS, pKey, TRUE);
   pElement = L_DicomFindFirstElement(hDS, pElement, TAG_REFERENCED_FILE_ID, TRUE);
   pVal = L_DicomGetStringValue(hDS, pElement, 0, 1);
   MessageBox(NULL, pVal, TEXT("Test"), MB_OK);

   L_DicomFreeDS(hDS);
   return DICOM_SUCCESS;
}