LDicomDS::GetEncapsulatedDocument

Summary

Retrieves an encapsulated document and corresponding DICOM elements from a DICOM data set. This feature is available in version 17.5 or higher.

Syntax

#include "ltdic.h"

L_UINT16 LDicomDS::GetEncapsulatedDocument(pElement, bChild, pszFileDocument, pEncapsulatedDocument, pConceptNameCodeSequence)

L_UINT16 LDicomDS::GetEncapsulatedDocument(pElement, bChild, pBuffer, puBufferSize, pEncapsulatedDocument, pConceptNameCodeSequence)

Parameters

pDICOMELEMENT pElement

Pointer to a DICOMELEMENT structure that contains an item in the Data Set. The inserted item will be inserted as a neighbor to this item, or as a child, depending on the value of bChild.

L_BOOL bChild

Flag that indicates where to insert the item. Possible values are:

Value Meaning
TRUE The new item will be inserted as the last child of pElement.
FALSE The new item will be inserted as the last sibling of pElement.

L_UCHAR *pBuffer

Address of the destination memory buffer where the encapsulated document will be copied.

L_UINT32 *puBufferSize

Pointer to an unsigned integer that contains the size of the memory buffer (in bytes).

L_TCHAR * pszFileDocument

Character string that contains the name of the file that will contain the retrieved encapsulated document. This will either be a PDF or a CDA file.

pDICOMENCAPSULATEDDOCUMENT pEncapsulatedDocument

Pointer to a DICOMENCAPSULATEDDOCUMENT structure, which is filled with the encapsulated document module attributes. This member must NOT be NULL.

pDICOMCODESEQUENCEITEM pConceptNameCodeSequence

Pointer to a DICOMCODESEQUENCEITEM structure, which is filled with the Concept Name Code Sequence attributes. This member can be NULL.

Returns

Value Meaning
0 DICOM_SUCCESS
> 0 An error occurred. Refer to Return Codes.

Comments

There are two overloads for this function.

  1. The first overload retrieves the encapsulated document (PDF or CDA) for a DICOM dataset, and stores the encapsulated document in a file.

  2. The second overload retrieves the encapsulated document and stores its contents in a memory buffer.

    • When using the second overload, you must call this function twice.

    • The first time, pass NULL for pBuffer, and the size of the required buffer will be returned in *puBufferSize.  

    • Allocate pBuffer with a size of *puBufferSize bytes

    • Call GetEncapsulatedDocument() a second time, this time passing the newly allocated pBuffer

The members of the DICOMENCAPSULATEDDOCUMENT structure and the DICOMCODESEQUENCEITEM structure together represent the set of attributes contained in the "Encapsulated Document Module Attributes". The Encapsulated Information Object Definition (IOD) describes either a

that has been encapsulated within a DICOM information object.

For more information, refer to Part 3 of the DICOM standard.

The DICOMENCAPSULATEDDOCUMENT structure corresponds to the Encapsulated Document Module Attributes described in part 3 of the DICOM specification. To retrieve the Concept Name Code Sequence element (0040,A043) pass a pointer to a pConceptNameCodeSequence item.

The pszFileDocument argument points to a file location that will contain the encapsulated document after it is extracted. If this file already exists, it will be over written.

Before calling this function:

  1. Initialize pEncapsulatedDocument->uStructSize to be sizeof(DICOMENCAPSULATEDDOCUMENT). After a successful function call, the fields of this structure will either point to the element values, or contain NULL. If a field contains NULL, this means that the corresponding element does not exist in the data set.

  2. If retrieving the Concept Name Code Sequence element, pConceptNameCodeSequence should be the address of a DICOMCODESEQUENCEITEM structure. Initialize pConceptNameCodeSequence->uStructSize to be sizeof(DICOMCODESEQUENCEITEM). After a successful function call, the fields of this structure will either point to the element values, or contain NULL. If a field contains NULL, this means that the corresponding element does not exist in the data set.

Required DLLs and Libraries

Platforms

Win32, x64

See Also

Functions

Topics

Example

This example extracts an encapsulated document and the corresponding DICOM tags from a DICOM data set.
The contents of the tags are displayed.

CString DumpDate(pVALUEDATE p) 
{ 
   CString s = L""; 
   if (p) 
   { 
      s.Format(L"%.02d/%.02d/%.04d", p->nMonth, p->nDay, p->nYear); 
   } 
   return s; 
} 
 
CString DumpTime(pVALUETIME p) 
{ 
   CString s = L""; 
      if (p) 
   { 
      s.Format(L"%.02d:%.02d:%.02d:%.06d", p->nHours, p->nMinutes, p->nSeconds, p->nFractions); 
   } 
   return s; 
} 
 
CString DumpDateTime(pVALUEDATETIME p) 
{ 
   CString s = L""; 
   if (p) 
   { 
      s.Format(L"%.02d/%.02d/%.04d  %.02d:%.02d:%.02d:%.06d%+05d", p->nMonth, p->nDay, p->nYear, p->nHours, p->nMinutes, p->nSeconds, p->nFractions, p->nOffset); 
   } 
   return s; 
} 
 
L_TCHAR *DumpString(L_TCHAR *p) 
{ 
   return p ? p : L""; 
} 
 
L_VOID DumpEncapsulatedDocumentTags(L_TCHAR *pszMsg,  DICOMENCAPSULATEDDOCUMENT &EncapsulatedDocument, DICOMCODESEQUENCEITEM &ConceptNameCodeSequence) 
{ 
   CString csMsg1; 
 
   csMsg1.Format(L"%s\n\nuType: %s\nInstanceNumber: %d\nContentDate: %s\nContentTime: %s\nAcquisitionDateTime: %s\nBurnedInAnnotation: %s\nDocumentTitle: %s\nVerificationFlag: %s\nHL7InstanceIdentifier: %s\nMIMETypeOfEncapsulatedDocument: %s\nListOfMIMETypes: %s\n\n",  
      pszMsg, 
      EncapsulatedDocument.uType == ENCAPSULATED_DOCUMENT_PDF ? L"ENCAPSULATED_DOCUMENT_PDF" : L"ENCAPSULATED_DOCUMENT_CDA", 
      EncapsulatedDocument.nInstanceNumber, 
      DumpDate(EncapsulatedDocument.pContentDate), 
      DumpTime(EncapsulatedDocument.pContentTime), 
      DumpDateTime(EncapsulatedDocument.pAcquisitionDateTime), 
      DumpString(EncapsulatedDocument.pszBurnedInAnnotation), 
      DumpString(EncapsulatedDocument.pszDocumentTitle), 
      DumpString(EncapsulatedDocument.pszVerificationFlag), 
      DumpString(EncapsulatedDocument.pszHL7InstanceIdentifier), 
      DumpString(EncapsulatedDocument.pszMIMETypeOfEncapsulatedDocument), 
      DumpString(EncapsulatedDocument.pszListOfMIMETypes) 
      ); 
 
   // ConceptNameCodeSequence 
   CString csMsg2; 
   csMsg2.Format(L"CodeValue: %s\nCodingSchemeDesignator: %s\nCodingSchemeVersion: %s\nCodeMeaning: %s\nContextIdentifier: %s\nMappingResource: %s\nContextGroupVersion: %s\nContextGroupLocalVersion: %s\nContextGroupExtensionCreatorUID: %s", 
      DumpString(ConceptNameCodeSequence.pszCodeValue), 
      DumpString(ConceptNameCodeSequence.pszCodingSchemeDesignator), 
      DumpString(ConceptNameCodeSequence.pszCodingSchemeVersion), 
      DumpString(ConceptNameCodeSequence.pszCodeMeaning), 
      DumpString(ConceptNameCodeSequence.pszContextIdentifier), 
      DumpString(ConceptNameCodeSequence.pszMappingResource), 
      DumpDateTime(ConceptNameCodeSequence.pContextGroupVersion), 
      DumpDateTime(ConceptNameCodeSequence.pContextGroupLocalVersion), 
      DumpString(ConceptNameCodeSequence.pszContextGroupExtensionCreatorUID) 
      ); 
 
   MessageBox(NULL, csMsg1 + csMsg2, L"", MB_OK); 
} 
 
 
L_INT LDicomDS_GetEncapsulatedDocument(pDICOMELEMENT pElement, L_BOOL bChild, LDicomDS &ds, L_TCHAR *pszFileDocument ) 
{ 
   DICOMENCAPSULATEDDOCUMENT EncapsulatedDocument = {0}; 
   EncapsulatedDocument.uStructSize = sizeof(DICOMENCAPSULATEDDOCUMENT); 
 
   DICOMCODESEQUENCEITEM ConceptNameCodeSequence = {0}; 
   ConceptNameCodeSequence.uStructSize = sizeof(DICOMCODESEQUENCEITEM); 
 
   L_UINT16 uRet = ds.GetEncapsulatedDocument(pElement, bChild, pszFileDocument, &EncapsulatedDocument, &ConceptNameCodeSequence); 
   if (uRet == DICOM_SUCCESS) 
   { 
      CString csMsg; 
      csMsg.Format(L"Encapsulated Document Extracted: %s", pszFileDocument); 
      DumpEncapsulatedDocumentTags( csMsg.GetBuffer(), EncapsulatedDocument, ConceptNameCodeSequence); 
   } 
   return uRet; 
} 

Help Version 23.0.2024.7.1
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2024 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS DICOM C++ Class Library Help
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.