L_DicomCreatePrivateCreatorDataElement

#include "Ltdic.h"

L_LTDIC_API L_UINT16 EXT_FUNCTION L_DicomCreatePrivateCreatorDataElement(hDS, pElement, uElementGroup, uElementNumber, pszIdCode, ppPrivateCreatorDataElement)

Creates a Private Creator Data Element to reserve private data elements. This feature is available in version 16 or higher.

Parameters

HDICOMDS hDS

A DICOM handle.

pDICOMELEMENT pElement

Pointer to a DICOMELEMENT structure that contains an item in the Data Set. The inserted item will be inserted at the same level as this item.

L_UINT16 uElementGroup

Group number of the private creator data element.

L_UINT16 uElementNumber

Element number of the private creator data element.

L_TCHAR * pszIdCode

String identifier that is assigned to the private creator data element.

pDICOMELEMENT * ppPrivateCreatorDataElement

Pointer to the created private creator data element.

Returns

Value Meaning
DICOM_SUCCESS The function was successful.
< 1 An error occurred. Refer to Return Codes.

Comments

A DICOM Data Set can have private data, which is stored in private tags. Private tags are reserved by adding a Private Creator Data Element to the data set. Elements of the form (gggg,0010-00FF) represent private creator data elements. More specifically:

Private Creator Data Elements are elements of the form (gggg,eeee) where:

  1. gggg is a four-digit hexadecimal group number

  2. eeee is a four-digit hexadecimal element number

  3. gggg is odd

  4. gggg is NOT 0001, 0003, 0005, 0007 or FFFF

  5. eeee is in the range 0010 to 00FF

  6. Value Representation is LO (Long String).

  7. Value Multiplicity is 1

A private creator data element of the form (gggg,00ee) reserves the following 256 elements, which can be of any value reprentation:

(gggg, ee00)

(gggg, ee01)

(gggg, ee02)

(gggg, eeFF).

For example, suppose you want to add the following three private elements to a DICOM data set:

(0017,1201)

(0017,1203)

(0017,1205)

You would first reserve the elements by adding the corresponding private creator data element (0017, 0012).

When using the L_DicomCreatePrivateCreatorDataElement function, the created private creator data element is on the same level as the element pointed to by argument pElement. If pElement is NULL, the private creator data element is created at the top or first level.

If parameter uElementNumber is 0xFFFF, the private creator data element is created with the first available element number in the group uGroupNumber.

Required DLLs and Libraries

Platforms

Win32, x64, Linux.

See Also

Functions

Topics

Example

This example shows the steps to properly reserve and insert some private tags

  1. Reserve elements by first creating a 'Private Creator Data Element'-- create in group 'uGroup', and take first available element
  2. Now insert five private elements that have been reserved by the 'Private Creator Data Element'
    L_INT DicomCreatePrivateCreatorDataElementExample(HDICOMDS hDS, pDICOMELEMENT pRoot, L_UINT16 uElementGroup) 
    { 
       L_INT nRet = DICOM_SUCCESS; 
       L_UINT32 uTag = 0; 
       L_TCHAR *pszUniqueID = TEXT("MyPrivateCreatorDataElement"); 
     
       // We will add some private tags 
       // First see if the Private Creator Data Element already exists -- search by unique ID, ANY group 
       pDICOMELEMENT pPrivateCreatorElement = L_DicomFindFirstPrivateCreatorDataElement(hDS, pRoot, TRUE, pszUniqueID, 0); 
     
       // If the Private Creator Data Element does not exist, try to create it 
       if (pPrivateCreatorElement == NULL) 
       { 
          nRet = L_DicomCreatePrivateCreatorDataElement(hDS, pRoot, uElementGroup, 0xFF, pszUniqueID, &pPrivateCreatorElement); 
          if (nRet != DICOM_SUCCESS) 
             return nRet; 
     
          // Private Creator Data Element tag was created successfully 
          // Add it to the DICOM Tag table  
          L_DicomInsertTag( 
             pPrivateCreatorElement->nTag,  
             0xFFFFFFFF,  
             pszUniqueID,  
             pPrivateCreatorElement->nVR, 
             1,1,1 
             ); 
       } 
     
       // Insert some private elements 
       for (int i = 0; i<5; i++) 
       { 
          nRet = L_DicomGetNextUnusedPrivateTag(hDS, pPrivateCreatorElement, &uTag); 
          if (nRet == DICOM_SUCCESS) 
          { 
             pDICOMELEMENT p = L_DicomInsertElement(hDS, pRoot, FALSE, uTag, VR_IS, FALSE, 0); 
             if (p) 
             { 
                L_DicomSetLongValue(hDS, p, &i, 1); 
             } 
          } 
       } 
       return nRet; 
    } 
Help Version 20.0.2020.4.2
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2020 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS DICOM C API Help