LDicomDS::FindNextDescendant

Summary

Returns a pointer to the next descendant of pParent having the specified tag.

Syntax

#include "Ltdic.h"

pDICOMELEMENT LDicomDS::FindNextDescendant(pParent, pElement, bNextLevelOnly)

Parameters

pDICOMELEMENT pParent

Pointer to a parent DICOMELEMENT structure within the Data Set.

pDICOMELEMENT pElement

Pointer to a child DICOMELEMENT structure of pParent.

L_BOOL bNextLevelOnly

Flag that indicates how the Data Set will be evaluated. Possible values are:

Value	Meaning
TRUE	Search for items in the next level only.
FALSE	Search for items recursively in all the next levels.

Returns

Value	Meaning
!NULL	A pointer to a DICOMELEMENT structure that contains the first item in the Data Set with the specified tag.
NULL	An item with the specified tag was not found.

Comments

NOTE: This function does not specify a tag to use when searching. However the tag that was used in the last call to LDicomDS::FindFirstDescendant is used by default when searching.

This function finds the next descendant of the pElement that has a DICOM tag equivalent to the nTag argument (LDicomDS::FindFirstDescendant), where the entire search is rooted at the Parent element (i.e. pParent).

The diagram below represents DICOM elements stored in a DICOM dataset.

Behavior when bNextLevelOnly is TRUE

Returns the next element on the next level of pParent that has tag equivalent to the nTag argument used in the previous call to LDicomDS::FindFirstDescendant. Elements included in the search include child elements in the next level only, starting with the element pointed to by pElement.

Example 1

bNextLevelOnly TRUE

pParent points to element 1

pElement points to element 8

Searches elements 11, 12 and returns the first element that matches the nTag argument used in the previous call to LDicomDS::FindFirstDescendant.

Example 2

bNextLevelOnly TRUE

pParent points to element 2

pElement points to element 3

Searches elements 4, 7 and returns the first element that matches the nTag argument used in the previous call to LDicomDS::FindFirstDescendant.

Example 3

bNextLevelOnly TRUE

pParent pointing to element 4

pElement points to element 5

Searches element 6 only, and returns element 6 if it has a tag equivalent to the nTag argument used in the previous call to LDicomDS::FindFirstDescendant.

Example 4

bNextLevelOnly TRUE

pParent pointing to element 1

pElement points to element 12

Returns NULL.

Behavior when bNextLevelOnly is FALSE

Returns the next item that has tag equivalent to the nTag argument used in the previous call to LDicomDS::FindFirstDescendant, using a pre-order search algorithm rooted at pParent.

Example 5

bNextLevelOnly FALSE

pParent pointing to element 1

pElement points to element 4

Searches elements 5, 6, 7, 8, 9, 10, 11, 12 and returns the first element that matches the nTag argument used in the previous call to LDicomDS::FindFirstDescendant.

Example 6

bNextLevelOnly FALSE

pParent pointing to element 2

pElement points to element 4

Searches elements 5, 6, 7 and returns the first element that matches the nTag argument used in the previous call to LDicomDS::FindFirstDescendant.

Example 7

bNextLevelOnly FALSE

pParent pointing to element 4

pElement points to element 5

Searches element 6 only, and returns element 6 if it has a tag equivalent to the nTag argument used in the previous call to LDicomDS::FindFirstDescendant.

The following functions can also help you find elements in the Data Set with a specific tag:

LDicomDS::FindFirstDescendant

LDicomDS::FindFirstElement

LDicomDS::FindLastElement

LDicomDS::FindPrevElement

LDicomDS::FindNextElement

The following functions will help you find specific modules in the Data Set:

LDicomDS::FindModule

LDicomDS::FindIndexModule