mme_explore_position_set()

Position the information extraction location in the current folder

Synopsis:

#include <mme/explore.h>

int mme_explore_position_set( mme_explore_hdl_t *x_hdl,
                              unsigned offset,
                              unsigned items,
                              const char *metadata_types,
                              const char *filter,
                              uint32_t flags );

Arguments:

x_hdl
An explorer handle returned by mme_explore_start().
offset
The offset in the folder from which to start getting information.
items
The number of items, starting at the offset from which information is required.
metadata_types
An optional pointer to a string containing a comma-separated list of metadata types to retrieve. This pointer may be NULL. See METADATA_* in this reference.
filter
A pointer to a regular expression used for filtering. This pointer may be NULL. See Filtering below.
flags
An MME_EXPLORE_FILTER_* bitmask instructing the MME to treat the filter specification as either an include-only or as an exclude-only specifier. The default is MME_EXPLORE_FILTER_INCLUDE. See Filtering below.

Library:

mme

Description:

The function mme_explore_position_set() sets:


Note: If the item being explored is a playlist file, no metadata will be returned.


Caution: Retrieving more items than can be shown at one time in the HMI display window reduces system responsiveness:
  • Always set items (the number of items requested) to a value less than or equal to the number of items that can be shown at one time in the HMI display window size.
  • Adjust the number of items requested to correspond to changes to the size of the HMI display window.

Filtering

You can use the filter and flag arguments to filter the files examined and deliver only files of interest.

If the filter argument is NULL, it specifies no filter, and removes any previously used filter. When this argument is not NULL, it is an extended regular expression as defined by the regcomp() function, where the flags REG_ICASE | REG_EXTENDED | REG_NOSUB are used.

For example, to include only MP3 and WAVE files, based on the extensions .mp3 and .wav, you should call mme_explore_position_set() as follows:

rc = mme_explore_position_set( x_hdl, 0, 20, NULL, ".mp3$|.wav$", MME_EXPLORE_FILTER_INCLUDE );

Or, to exclude all files with the extension .mov, do the following:

rc = mme_explore_position_set( x_hdl, 0, 20, NULL, ".mov$", MME_EXPLORE_FILTER_EXCLUDE );

Caution:
  • The presence of filters makes using mme_explore_size_get() an expensive operation (for mediastores for which it is normally inexpensive), because the mme_explore_size_get() operation must now traverse the entire session to determine the actual number of items of interest.
  • If a filter is assigned (or removed), the current position with the current explore session is reset to 0.
  • If mme_explore_size_get() is called before the filter is set, its result may not be accurate when the filter is applied.

Events

None delivered.

Blocking and validation

This function performs no validations. It doesn't block.

Returns:

0
Success.
-1
An error occurred (errno is set).

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

mme_explore_end(), mme_explore_hdl_t, mme_explore_info_free(), mme_explore_info_get(), mme_explore_info_t, mme_explore_playlist_find_file(), mme_explore_size_get(), mme_explore_start()