mmr_output_parameters()

Set output parameters.

Synopsis:

#include <mm/renderer.h>
#include <audio/audio_manager_routing.h>

int mmr_output_parameters( mmr_context_t *ctxt, 
                           unsigned output_id, 
                           strm_dict_t *parms )

Arguments:

ctxt: A context handle.

output_id: An output ID.

parms: A dictionary object containing the parameters to set (handle gets consumed by this call, even on failure).

Library:

mmrndclient, audio_manager_lib

Description:

Set parameters for an output device. The acceptable parameter values depend on the plugins loaded for the attached output and the attached input, if any. Unlike input and track parameters, the values of output parameters won't be changed by mm-renderer plugins. If the provided values aren't supported for the current output and input combination, the function call fails.

The output type determines which output parameters you can set. At present, there are no output parameters for the "file" output type.

For the "audio" output type, the following parameters are available for any URL format:

volume: Set the volume for this audio stream. The volume must be in the range of 0 to 100.

When using the "audio" output type with a URL that starts with audio:, you can set one of the following parameters:

audio_type: Classify the audio track based on its content (voice, ring tones, video chat, etc.). This parameter provides a shortcut for setting the audio type, thereby simplifying your client code. By using this parameter, you can avoid making the multiple Audio Manager API calls required to obtain an audio manager handle and then use that handle to set the audio type.
The audio type is specified as a string, whose value is one of the audio types defined by the AUDIO_TYPE_NAMES set of string constants, which is documented in the Audio Manager Library reference.
audioman_handle: Associate an audio manager handle with the audio stream managed by the current context. This parameter lets you control multiple audio stream settings. To obtain a value for this parameter, call the audio_manager_get_handle() API function, passing 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. Refer to the audio routing functions described in the Audio Manager Library reference for more information.

For the "video" output type, your application should modify the output window directly by using the libscreen library, as demonstrated in "../managing_video_windows.html".

CAUTION:

The legacy video output parameters video_dest_*, video_src_*, and video_clip_* have been deprecated. Using libscreen is the proper way to configure video output.

The mmr_output_attach() function sets the parameters url and type. Some plugins allow you to modify the URL with mmr_output_parameters(). For instance, you can ask mm-renderer to switch output devices by calling mmr_output_parameters() with a new URL in the parameters.

Returns:

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

Classification:

QNX Neutrino

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes

Examples:

Suppose you want to set the audio_type parameter to indicate that an output audio stream contains dialing and call progress tones, also referred to as voice tones. You must first look up the audio type string by passing the AUDIO_TYPES_VOICE_TONES code to the appropriate audio manager API function, then store this string in a dictionary, and then pass the dictionary to mm-renderer, as follows:

#include <mm/renderer.h>
#include <strm.h>

// Store the audio type in the dictionary before 
// setting the output parameters
strm_dict_t* dict = strm_dict_new();    

if ( dict = strm_dict_set( dict, "audio_type", 
              audio_manager_get_name_from_type(
              AUDIO_TYPE_VOICE_TONES ) ) == NULL )
{
    // Do error handling
}    

if ( mmr_output_parameters( context,
                        output_id, dict ) < 0 )
{
    // Call mmr_error_info() and do error handling
}

Presently, the audio type is the only audio stream characteristic that clients can set directly through mm-renderer. The Audio Manager API lets clients manage additional characteristics of an audio stream. For example, you could set both the audio type and reset conditions, as follows:

#include <mm/renderer.h>
#include <strm.h>
#include <audio/audio_manager_routing.h>

// Get an audio manager handle for voice tones 
unsigned int audio_hndl;

if ( audio_manager_get_handle( 
              AUDIO_TYPE_VOICE_TONES, 0, 
              false, &audio_hndl ) != EOK )
{
    // Check errno, do error handling, and exit
}

// Set the reset conditions 
if ( audio_manager_set_handle_routing_conditions( 
       audio_hndl, 
     SETTINGS_RESET_ON_DEVICE_CONNECTION ) != EOK )
{
    // Check errno, do error handling, and exit
}

// Store the handle in the dictionary before
// setting the output parameters
...

You can set the audio_type or audioman_handle parameters for an input in a similar way, by substituting the call to mmr_output_parameters() with a call to mmr_input_parameters().