mmr_input_parameters()

Set input parameters.

Synopsis:

#include <mm/renderer/renderer.h>
 
int mmr_input_parameters(mmr_context_t *ctxt,
                         strm_dict_t *parms)

Since:

BlackBerry 10.0.0

Arguments:

ctxt

A context handle.

parms

A dictionary containing the input parameters to set (must not be NULL). Any previous parameters are overridden. Do not use or destroy the dictionary after passing it to this function, even if the call fails.

Library:

libmmrndclient (For the qcc command, use the -l mrndclient option to link against this library)

Description:

Set parameters associated with the attached input media.

The input type and the URL format determine which input parameters you can set. Some parameters must be set before the input is attached, because setting them after attaching the input has no effect. All input parameters are cleared when the input is detached, whether explicitly through a call to mmr_input_detach() or implicitly when mmr_input_attach() is called to attach a new input, which causes mm-renderer to detach the current input.

In the case where closed captioning data from an external file is used, the strm_dict_t object must contain a "subpicture_url" entry with its value set to the path of the file. Otherwise, mm-renderer will look for embedded subtitles in the main video file. This parameter must be set before the main input is attached, as you can't switch between internal and embedded "subpicture_url"s. However, you can set this parameter to a different URL later to select a different file (for example, a different language). The new file must be the same format as the initial file.

Some mm-renderer plugins don't return errors when you provide unacceptable values for input parameters. Some input parameters control internal values, such as volume, repeat, update interval, and so on.

If you provide an invalid value in the dictionary, mm-renderer may remove it and apply its internal default (for example, 100% for volume, none for repeat). Alternatively, mm-renderer could replace the invalid value with the previous value of the parameter, and keep the internal value unchanged. To see which values were accepted or changed, client applications can examine the parameters that the Event API returned.

Note: An individual playlist item isn't considered an input but the whole playlist is. To set parameters for individual playlist items, you must use mmr_track_parameters()

When your input has the "autolist" type, any input parameters you specified before attaching the input become the track parameters. After the input is attached, use track parameters, just like you would for a real playlist.

When your input has the "track" type, the input parameters apply to the track. Do not use mmr_track_parameters() with the "track" type.

The "playlist" and "autolist" input types support the following parameter:

repeat

Specifies whether to repeat a track or tracks. Acceptable values are "none" (default), "track", or "all".

When using the "autolist" or "track" input types with a URL that starts with audio:, you can set one of the following two parameters:

audio_type

Specifies the audio type to use with the track. The audio type is specified as a string that's set to one of the audio types defined by AUDIO_TYPE_NAMES, which is documented in the Audio Manager Library reference. Acceptable values include "multimedia" and "notification"; consult the Audio Manager for the complete list of defined audio types and their meanings.

This parameter provides a shortcut for setting the audio type, thereby simplifying your client code. You can use this parameter instead of using the Audio Manager API to obtain an audio manager handle, and then passing that handle to mm-renderer as the "audioman_handle" parameter.

audioman_handle

Associate an audio manager handle with the audio stream that the current context manages. To obtain a value for this parameter, call the audio_manager_get_handle() API function and pass in the desired audio type.

You can then use this handle to change the audio type and other audio stream characteristics through the Audio Manager API. For more information, refer to the audio routing functions described in the Audio Manager Library reference.

When the input URL starts with http: or https:, you can set the following parameters that map to libcurl options:
  • OPT_VERBOSE
  • OPT_CONNECTTIMEOUT_MS
  • OPT_LOW_SPEED_LIMIT
  • OPT_LOW_SPEED_TIME
  • OPT_USERAGENT
  • OPT_USERNAME
  • OPT_PASSWORD
  • OPT_PROXYUSERNAME
  • OPT_PROXYPASSWORD
  • OPT_COOKIE
  • OPT_COOKIEFILE
  • OPT_COOKIEJAR
  • OPT_COOKIESESSION
  • OPT_CAINFO
  • OPT_CAPATH
  • OPT_SSL_VERIFYPEER
  • OPT_SSL_VERIFYHOST
  • OPT_PROXY
  • OPT_NOPROXY
  • OPT_HTTPPROXYTUNNEL
  • OPT_PROXYPORT
  • OPT_PROXYTYPE
  • OPT_PROXYAUTH
  • OPT_HTTPAUTH
  • OPT_HTTPHEADER
  • OPT_DNSCACHETIMEOUT

Note: When a track is played, it has access to its track parameters and the context parameters. For any OPT_ parameters that exist in both the context and track parameters, the track parameter is used.

Returns:

Zero on success, -1 on failure (use mmr_error_info()).

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus