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 containing the output parameters to set (must not be NULL). Any previous parameters are overridden.

The strm_dict_t object becomes API property after this call, even if the call fails. You should not use or destroy the dictionary after passing it to this function.

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 parameter is 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 two 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. You can use this parameter instead of using the Audio Manager API to obtain an audio manager handle, and then using that handle to set the audio type.

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.

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.

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

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 look up the audio type string by passing the AUDIO_TYPES_VOICE_TONES code to the Audio Manager API, store the returned string in a dictionary, and pass the dictionary to mm-renderer, as follows:
#include <mm/renderer.h>
#include <strm.h>

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>

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
}

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().