In This Topic ▼

LDicomPrintSCU::UpdateImageBox

Summary

Requests the Print SCP to update the specified Basic Grayscale/Color Image Box SOP Instance.

Syntax

#include "ltdic.h"

L_INT LDicomPrintSCU::UpdateImageBox(pszImageBoxInstanceUID, pImage, uIndex, pParameters, pszRefImageOverlayBoxInstanceUID = NULL, pszRefPresLUTInstanceUID = NULL)

Parameters

const L_TCHAR * pszImageBoxInstanceUID

Character string that contains the SOP Instance UID of the Image Box to be updated. The function will return an error if this is NULL or if an empty string is specified. The function LDicomPrintSCU::GetImageBoxInstanceUID returns the SOP Instance UID of a particular Image Box.

LDicomDS* pImage

Pointer to an LDicomDS object that contains the image to be printed in the specified Image Box. If this is set to NULL, the Print SCP will be instructed to erase the image (if there is one) in the specified Image Box.

const L_UINT32 uIndex

Index value that indicates which frame in a Pixel Data element to load.

const pIMAGEBOXPARAMETERS pParameters

Pointer to an IMAGEBOXPARAMETERS structure that specifies the Image Box parameters to be updated. The function will return an error if this parameter is set to NULL or if the Image Position specified is less than 1.

const L_TCHAR * pszRefImageOverlayBoxInstanceUID

Character string that contains the SOP Instance UID of a previously created Basic Print Image Overlay Box SOP Instance to be referenced by the Image Box. This can be set to NULL if the reference is not to be updated. In this case, the corresponding Attribute will not be included in the request to the Print SCP. If an empty string is specified and the Image Box already references an Image Overlay Box, then the update will remove that reference. Refer to the function LDicomPrintSCU::CreateOverlayBox for creating Image Overlay Boxes.

const L_TCHAR * pszRefPresLUTInstanceUID

Character string that contains the SOP Instance UID of a previously created Presentation LUT SOP Instance to be referenced by the Image Box. This can be set to NULL if the reference is not to be updated. In this case, the corresponding Attribute will not be included in the request to the Print SCP. If an empty string is specified and the Image Box already references a Presentation LUT, then the update will remove that reference. Since only a Grayscale Image Box may reference a Presentation LUT, the function ignores this parameter for Color Image Boxes. Refer to the function LDicomPrintSCU::CreatePresentationLUT for creating Presentation LUTs.

Returns

Value	Meaning
0	The specified Basic Grayscale/Color Image Box SOP Instance was updated successfully.
DICOM_ERROR_PRINTSCU_FAILURE_STATUS	The response of the Print SCP specifies a Failure status code.
DICOM_ERROR_PRINTSCU_CLASS_NOT_SUPPORTED	Neither the Basic Grayscale Print Management Meta SOP Class nor the Basic Color Print Management Meta SOP Class is supported on the Association.
> 0	An error occurred. Refer to Return Codes.

Comments

When the Print SCP is requested to create a Film Box, it will also create one or more Image Boxes, based on the Image Display Format. This function updates a particular Image Box. The Image Box specified (by the SOP Instance UID) must belong to the current (last created) Film Box.

The type of the Image Boxes created by the Print SCP (Grayscale or Color) depends on the Meta SOP Class of the Film Session created at first. Refer to the function LDicomPrintSCU::CreateFilmSession for more information.

The function will not return until it receives the response of the Print SCP, or an error occurs. The function LDicomPrintSCU::GetLastOperationStatus can be used to obtain the status code specified in the response of the Print SCP. When the return value of the function UpdateImageBox is 0, then the Image Box was updated successfully, with either a Success or Warning status code in the response of the Print SCP.

The parameter pParameters points to an IMAGEBOXPARAMETERS structure that specifies the Image Box parameters to be updated. In this structure, if a string member is NULL, then the corresponding Attribute will not be included in the request to the Print SCP and hence will not be updated. Similarly, if a numeric member (that specifies an Attribute) is negative, the corresponding Attribute will not be included in the request and hence will not be updated. Notice that since the Attributes Min Density, Max Density, and Configuration Information are defined only for Grayscale Image Boxes, the function will ignore the following structure members for Color Image Boxes:

nMinDensity

nMaxDensity

pszConfigurationInformation

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

Example

L_INT LDicomPrintSCU_UpdateImageBoxExample() 
 
{ 
   L_INT          nRet; 
   LDicomPrintSCU PrintSCU;  
 
   //CPrintSCU PrintSCU;  
 
   PrintSCU.SetTimeout (60); // 60 seconds 
 
   L_TCHAR szMsg[32];  
 
   // Establish the Association 
 
   nRet = PrintSCU.Associate (TEXT("10.0.2.20"), 7104, TEXT("PrintSCP"), 
                             TEXT("PrintSCU"), 
                             PRINTSCU_BASIC_GRAYSCALE_PM_META_SOP_CLASS | 
                             PRINTSCU_BASIC_COLOR_PM_META_SOP_CLASS | 
                             PRINTSCU_BASIC_ANNOTATION_BOX_SOP_CLASS | 
                             PRINTSCU_BASIC_PRINT_IMAGE_OVERLAY_BOX_SOP_CLASS | 
                             PRINTSCU_PRESENTATION_LUT_SOP_CLASS | 
                             PRINTSCU_PRINT_JOB_SOP_CLASS | 
                             PRINTSCU_PRINTER_CONFIGURATION_RETRIEVAL_SOP_CLASS);  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   if (nRet == DICOM_ERROR_PRINTSCU_ASSOCIATE_RQ_REJECTED)  
 
   { 
 
      L_UCHAR nSource, nReason;  
 
      PrintSCU.GetAssociateRejectInfo (NULL, &nSource, &nReason);  
 
      wsprintf(szMsg, TEXT("Source = %i, Reason = %i"), nSource, nReason);  
 
      MessageBox(NULL, szMsg, TEXT("Association Request was Rejected"), MB_OK);  
 
      return nRet; 
 
   } 
 
   else if (nRet != DICOM_SUCCESS)  
 
   { 
 
      wsprintf(szMsg, TEXT("Error code: %i"), nRet);  
 
      MessageBox(NULL, szMsg, TEXT("Failed to Establish the Association"), MB_OK);  
 
      return nRet;  
 
   } 
 
   // Display some printer info 
 
   //GetPrinterInfo(PrintSCU);  
 
   // Display some printer configuration info 
 
   //GetPrinterConfigInfo(PrintSCU);  
 
   FILMSESSIONPARAMETERS FilmSessionParams;  
 
   // Create a Film Session 
 
   PrintSCU.GetDefaultFilmSessionParameters (&FilmSessionParams,  
                                            sizeof(FILMSESSIONPARAMETERS));  
 
   FilmSessionParams.nNumberOfCopies = 1;  
 
   nRet = PrintSCU.CreateFilmSession (&FilmSessionParams);  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   MessageBox(NULL, PrintSCU.GetFilmSessionInstanceUID (), 
              TEXT("Film Session SOP Instance UID"), MB_OK);  
 
   // Update the Film Session to specify a "MED" Print Priority 
 
   nRet = PrintSCU.GetDefaultFilmSessionParameters (&FilmSessionParams,  
                                            sizeof(FILMSESSIONPARAMETERS));  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   FilmSessionParams.pszPrintPriority = TEXT("MED"); 
 
   nRet = PrintSCU.UpdateFilmSession (&FilmSessionParams);  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   FILMBOXPARAMETERS FilmBoxParams;  
 
   nRet = PrintSCU.GetDefaultFilmBoxParameters (&FilmBoxParams,  
                                        sizeof(FILMBOXPARAMETERS));  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   if (PrintSCU.IsClassSupported (PRINTSCU_BASIC_ANNOTATION_BOX_SOP_CLASS))  
 
   { 
 
      FilmBoxParams.pszAnnotationDisplayFormatID = TEXT("SomeID"); 
 
   } 
 
   // Create a Film Box 
 
   nRet = PrintSCU.CreateFilmBox (&FilmBoxParams);  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   MessageBox(NULL, PrintSCU.GetFilmBoxInstanceUID (), 
              TEXT("Film Box SOP Instance UID"), MB_OK);  
 
   L_PCTSTR pszPresLUTInstanceUID = NULL;  
 
   // Create a Presentation LUT 
 
   if (PrintSCU.IsClassSupported (PRINTSCU_PRESENTATION_LUT_SOP_CLASS))  
 
   { 
 
      LDicomDS PresLUT;  
 
      nRet = PresLUT.LoadDS(MAKE_IMAGE_PATH(TEXT("IMAGE1.dcm")), DS_LOAD_CLOSE); 
      if (nRet == DICOM_SUCCESS) 
      { 
 
         nRet = PrintSCU.CreatePresentationLUT (&PresLUT);  
         if(nRet != DICOM_SUCCESS) 
            return nRet; 
 
         pszPresLUTInstanceUID = PrintSCU.GetPresentationLUTInstanceUID (); 
 
         MessageBox(NULL, pszPresLUTInstanceUID,  
                    TEXT("PresLUT SOP Instance UID"), MB_OK);  
 
      } 
      else 
         return nRet; 
 
   } 
 
   if (pszPresLUTInstanceUID)  
 
   { 
 
      // Update the Film Box to reference the Presentation LUT we just created 
 
      nRet = PrintSCU.UpdateFilmBox (NULL, pszPresLUTInstanceUID);  
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
   } 
 
   L_PCTSTR pszOverlayBoxInstanceUID = NULL;  
   L_PCTSTR pszRefPresLUTInstanceUID = NULL; 
 
   // The image to be printed in the Image Box 
 
   LDicomDS Image;  
 
   nRet = Image.LoadDS (MAKE_IMAGE_PATH(TEXT("Image1.dcm")), DS_LOAD_CLOSE);  
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   // Update the Image Box. Since the Image Display Format of the Film Box was 
 
   // set to "STANDARD\1,1", then we are supposed to have one Image Box created 
 
   // by the Print SCP.  
 
   if (PrintSCU.GetImageBoxesCount ()) 
 
   { 
 
      L_PCTSTR pszImageBoxInstanceUID = PrintSCU.GetImageBoxInstanceUID (0);  
 
      MessageBox(NULL, pszImageBoxInstanceUID,  
                 TEXT("Image Box SOP Instance UID"), MB_OK);  
 
      IMAGEBOXPARAMETERS ImageBoxParams;  
 
      nRet = PrintSCU.GetDefaultImageBoxParameters(&ImageBoxParams,  
                                            sizeof(IMAGEBOXPARAMETERS));  
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
      ImageBoxParams.nImagePosition = 1;  
 
      #if defined(LEADTOOLS_V19_OR_LATER) 
            nRet = PrintSCU.UpdateImageBox (pszImageBoxInstanceUID,  
                                            &Image, 
                                            0, 
                                            &ImageBoxParams, 
                                            pszOverlayBoxInstanceUID,  
                                            pszRefPresLUTInstanceUID);  
      #else 
            nRet = PrintSCU.UpdateImageBox (pszImageBoxInstanceUID, 
               &Image,  
               &ImageBoxParams,  
               pszOverlayBoxInstanceUID);  
      #endif 
 
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
      // We don't need them any more 
 
      PrintSCU.FreeImageBoxesInstanceUIDs(); 
 
   } 
 
   // Update the Annotation Boxes (if there are any)  
 
   L_UINT32 uAnnBoxesCount = PrintSCU.GetAnnotationBoxesCount (); 
 
   for (L_UINT32 i = 0; i < uAnnBoxesCount; i++) 
 
   { 
 
      nRet = PrintSCU.UpdateAnnotationBox (PrintSCU.GetAnnotationBoxInstanceUID (i),  
                                   L_UINT16(i + 1), TEXT("Some Text")); 
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
   } 
 
   PrintSCU.FreeAnnotationBoxesInstanceUIDs (); // We don't need them any more 
 
   // Print the Film Session (or the Film Box; there is no difference since we 
 
   // have a single Film Box in the Film Session)  
 
   if (TRUE)  
 
   { 
 
      nRet = PrintSCU.PrintFilmSession (); 
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
   } 
 
   else 
 
   { 
 
      nRet = PrintSCU.PrintFilmBox (); 
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
   } 
 
   // Display some info about the Print Job 
 
   if (PrintSCU.IsClassSupported (PRINTSCU_PRINT_JOB_SOP_CLASS))  
 
   { 
 
      //GetPrintJobInfo(PrintSCU, PrintSCU.GetPrintJobInstanceUID ()); 
 
   } 
 
   // Delete the Film Box (anyway, it would be deleted when the Film Session 
 
   // is deleted)  
 
   nRet = PrintSCU.DeleteFilmBox (); 
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   // Delete the Film Session 
 
   nRet = PrintSCU.DeleteFilmSession (); 
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   // Delete the Presentation LUT 
 
   if (pszPresLUTInstanceUID)  
 
   { 
 
      nRet = PrintSCU.DeletePresentationLUT (pszPresLUTInstanceUID);  
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
   } 
 
   // Delete the Image Overlay Box 
 
   if (pszOverlayBoxInstanceUID)  
 
   { 
 
      nRet = PrintSCU.DeleteOverlayBox (pszOverlayBoxInstanceUID);  
      if(nRet != DICOM_SUCCESS) 
         return nRet; 
 
   } 
 
   // Release the Association and close the connection 
 
   nRet = PrintSCU.Release(); 
   if(nRet != DICOM_SUCCESS) 
      return nRet; 
 
   return DICOM_SUCCESS; 
}