L_DicomAnnSave

#include "ltdic.h"

L_LTDIC_API L_UINT16 L_DicomAnnSave(hDS, hAnnContainer, uFormat, bSelected, pSaveOption, nIndex, pnPrivateCreatorTag)

HDICOMDS hDS;

/* a DICOM handle */

HANNOBJECT hAnnContainer;

/* handle to the root annotation */

L_UINT uFormat;

/* file format for saving annotation data */

L_BOOL bSelected;

/* flag that indicates which objects to save */

pSAVEFILEOPTION pSaveOption;

/* pointer to optional extended save options */

L_INT nIndex;

/* index of an annotation file */

L_UINT32 *pnPrivateCreatorTag;

/* pointer to the private creator tag */

Saves annotations as private data in a DICOM data set.

Parameter

Description

hDS

A DICOM handle.

hAnnContainer

Handle to the root annotation object that includes all objects to save in the file. This typically is a container object.

uFormat

Format for saving annotation data. Possible values are:

 

Value

Meaning

 

ANNFMT_NATIVE

This format is no longer supported.

 

ANNFMT_ENCODED

This format is no longer supported.

 

ANNFMT_XML

[0x0005] Save as an XML text format. This is currently the only supported format.

 

bSelected

Flag that indicates which objects to save. Possible values are:

 

Value

Meaning

 

TRUE

Save all objects that have the selected property set to TRUE. For getting and setting the selected property, use the L_AnnGetSelected and L_AnnSetSelected functions.

 

FALSE

Save only the specified object.

pSaveOption

Pointer to a SAVEFILEOPTION structure that contains optional extended save options. This information is used to add annotation pages or replace annotation pages in a multi-page annotation file. Pass NULL to save a one page annotation file.

nIndex

Index of the annotation file to save. This is an index into an array of annotation files stored in the DICOM data set. Each DICOM data set can store up to 256 annotation files. This is a zero-based index. Valid values are between 0 and 255.

pnPrivateCreatorTag

Pointer to a private creator tag. You can specify a private creator tag, or pass NULL to have the tag automatically created.

Returns

0

SUCCESS

>0

An error occurred. Refer to Return Codes.

Comments

LEAD Annotation files can be saved as private data in a DICOM data set (LEAD native format or binary encoded format). There can be up to 256 private data tags for LEAD annotation files. Specify one of the 256 possible files by setting the nIndex parameter to be a value from 0 to 255.

You can select the private creator tag (and therefore the private tags) or have the private creator tag automatically chosen.

To choose a private creator tag, do the following:

1.

Declare a variable of type L_UINT32. For example

L_UINT32 uPrivateCreatorElement

2.

Set the value to the desired tag and element. Note that private creator tags must follow the following format:

(gggg, 0010-00FF) where gggg is odd

This reserves 256 private data elements.  For example,

uPrivateCreatorElement = 0x00710043

This particular private creator tag reserves the following elements:

0x00714300 through 0x007143FF

3.

Pass the address of uPrivateCreatorElement as the last argument (pnPrivateCreatorTag)

 

To choose the group but not the element of a private creator tag, do the following:

1.

Declare a variable of type L_UINT32. For example

L_UINT32 uPrivateCreatorElement

2.

Set uPrivateCreatorElement as follows:

(gggg0000) where gggg is odd

3.

Pass the address of uPrivateCreatorElement as the last argument (pnPrivateCreatorTag)

4.

If successful, the private creator tag (group and element) will be returned in uPrivateCreatorElement.

 

To have the private creator tag automatically chosen and returned, do the following:

1.

Declare a variable of type L_UINT32. For example

L_UINT32 uPrivateCreatorElement

2.

Set uPrivateCreatorElement = 0:

3.

Pass the address of uPrivateCreatorElement as the last argument (pnPrivateCreatorTag)

4.

If successful, the private creator tag (group and element) will be returned in uPrivateCreatorElement

 

To have the private creator tag automatically chosen but not returned, do the following:

1.

Pass the NULL as the last argument (pnPrivateCreatorTag)

 

To insert new pages to an annotation multi-page file:

1.

Declare a variable of type SAVEFILEOPTION.

2.

Set the uFlags field of the SAVEFILEOPTION structure to ESO_INSERTPAGE.

3.

Set the PageNumber field of the SAVEFILEOPTION structure to the location for insertion. The new page will be inserted in front of the page specified in the PageNumber field.

 

To replace an existing page in an annotation multi-page file:

1.

Declare a variable of type SAVEFILEOPTION.

2.

Set the uFlags field of the SAVEFILEOPTION structure to ESO_REPLACEPAGE.

3.

Set the PageNumber field of the SAVEFILEOPTION structure to the page to replace.

 

To delete a page from an annotation multi-page file, or to delete the entire annotation file, use L_DicomAnnDelete.

Please note that both the DICOM capabilities and the DOCUMENT capabilities must be unlocked in order to work with DICOM annotations. For more information on unlocking these capabilities, refer to L_UnlockSupport.

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_DicomAnnLoad, L_DicomAnnCount, L_DicomAnnDelete

Topics:

Working with DICOM Annotations

Example

For an example, refer to L_DicomAnnCount.