In This Topic ▼

L_EnumMarkers

Summary

Enumerates the markers in the marker collection.

Syntax

#include "l_bitmap.h"

L_LTFIL_API L_INT L_EnumMarkers(hMarkers, uFlags, pfnCallback, pUserData)

Parameters

L_VOID* hMarkers

Handle to the collection of metadata markers to enumerate. The data accessed by the handle may change, even if the handle value stays the same. A handle to a collection of metadata markers can be obtained by calling either L_LoadMarkers or L_CreateMarkers.

L_UINT uFlags

Reserved for future use. Pass 0.

ENUMMARKERSCALLBACK pfnCallback

Callback function for processing each enumerated marker. Use the function pointer as the value of this parameter.

L_EnumMarkers calls this callback function as it gets the handle of each marker. The callback function must adhere to the function prototype described in the ENUMMARKERSCALLBACK Function.

L_VOID* pUserData

Void pointer that you can use to pass one or more additional parameters that the callback function needs.

To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure. If the additional parameters are not needed, you can pass NULL in this parameter.

Returns

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

Comments

L_EnumMarkers filters the return codes from ENUMMARKERSCALLBACK. For example: if ENUMMARKERSCALLBACK returns SUCCESS_ABORT, the enumeration will be aborted and L_EnumMarkers will copy the remaining markers to the resulting marker collection. L_EnumMarkers will return SUCCESS if the copy succeeds.

This function actually updates the metadata marker collection as changes (deletions, insertions, etc.) take place. Therefore, when this function successfully returns, the contents of the resulting marker collection referenced by hMarkers may be different from the contents of the marker collection initially passed to L_EnumMarkers in the hMarkers parameter.

This function can also be used to selectively delete markers from hMarkers.

Your callback function will be called for every marker in the handle. You can delete, replace or insert markers using the callback.

You can call the LEADMARKERCALLBACK from your callback to insert a marker. The marker will be inserted before the current marker.

You can think of this function as though the LEAD engine is creating a new collection of markers. If your ENUMMARKERSCALLBACK returns SUCCESS, the marker passed to it will be included in the resulting marker collection by pfnLEADCallback. This resulting marker collection will be referenced by the hMarkers parameter when the L_EnumMarkers function successfully returns. You can also call pfnLEADCallback yourself if you want to insert extra markers or to control the order in which the markers are written.