The MMI API provides control functions for client applications such as creating and running instances of the MMI workflow through the MMI framework.

Required Header

#include <mmi.h>

Overview

The MMI API provides control functions for client applications such as creating and running instances of the MMI workflow through the MMI framework. The MMI workflow collects data from various modalities, processes it, and performs the function of deriving meaningful information to provide to client applications.
This API set allows you to:

initialize/deinitialize the MMI Framework
set/unset a callback function for MMI state changes
create/destroy standard or custom workflow instances
activate/deactivate workflow instances
set attributes to workflow instances
emit signals to workflow instances
set/unset a callback function to receive the output of workflow instance
By utilizing these functionalities, application developers can use multimodal workflows that integrate different modalities such as voice, touch, and vision.

State Transitions

FUNCTION	PRE-STATE	POST-STATE	SYNC TYPE
mmi_initialize()	NONE	READY	SYNC
mmi_deinitialize()	READY	NONE	SYNC

Callback(Event) Operations

The callback mechanism is used to notify the application about significant MMI events.

REGISTER	UNREGISTER	CALLBACK	DESCRIPTION
mmi_set_state_changed_cb()	mmi_unset_state_changed_cb()	mmi_state_changed_cb()	This callback is used to notify that the MMI state has changed
mmi_workflow_instance_set_output_cb()	mmi_workflow_instance_unset_output_cb()	mmi_workflow_output_cb()	This callback is used to notify that an error has occurred

Related Features

This API is related with the following features:

http://tizen.org/feature/multimodal_interaction

It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions
int	mmi_initialize (void)
	Initializes the MMI framework.
int	mmi_deinitialize (void)
	Deinitializes the MMI framework.
int	mmi_set_state_changed_cb (mmi_state_changed_cb callback, void *user_data)
	Sets a callback function to be invoked when the MMI state changes.
int	mmi_unset_state_changed_cb (mmi_state_changed_cb callback)
	Unsets the previously set callback function for MMI state changes.
int	mmi_standard_workflow_instance_create (mmi_standard_workflow_type_e type, mmi_workflow_instance_h *instance)
	Creates a new workflow instance from a standard workflow prototype.
int	mmi_custom_workflow_instance_create (mmi_workflow_h workflow, mmi_workflow_instance_h *instance)
	Instantiates a workflow from a custom workflow prototype.
int	mmi_workflow_instance_destroy (mmi_workflow_instance_h instance)
	Destroys a workflow instance.
int	mmi_workflow_instance_activate (mmi_workflow_instance_h instance)
	Activates a workflow instance.
int	mmi_workflow_instance_deactivate (mmi_workflow_instance_h instance)
	Deactivates a workflow instance.
int	mmi_workflow_instance_set_attribute (mmi_workflow_instance_h instance, mmi_attribute_h attribute)
	Sets an attribute of a workflow instance.
int	mmi_workflow_instance_emit_signal (mmi_workflow_instance_h instance, mmi_signal_h signal)
	Emits a signal to a workflow instance.
int	mmi_workflow_instance_set_output_cb (mmi_workflow_instance_h instance, const char name, mmi_workflow_output_cb callback, void user_data)
	Sets a callback function to receive workflow output.
int	mmi_workflow_instance_unset_output_cb (mmi_workflow_instance_h instance, mmi_workflow_output_cb callback)
	Unsets a callback function for an output of a workflow instance.
Typedefs
typedef int(*	mmi_state_changed_cb )(mmi_state_e state, void *user_data)
	Callback function type for MMI state change notifications.
typedef void *	mmi_workflow_instance_h
	Handle for MMI workflow instance.
typedef void(*	mmi_workflow_output_cb )(mmi_workflow_instance_h instance, const char name, mmi_data_h data, void user_data)
	Callback function type for handling workflow output.

Typedef Documentation

typedef int(* mmi_state_changed_cb)(mmi_state_e state, void *user_data)

Callback function type for MMI state change notifications.

This callback function is called whenever the state of the MMI client changes.

Since :: 9.0

Parameters:

[in]	state	The new state of the MMI client.
[in]	user_data	User-provided data passed to the callback function.

Returns:: An integer value indicating the result of the callback execution.

Return values:

0	on success, otherwise a negative error value.

See also:: mmi_state_e

typedef void* mmi_workflow_instance_h

Handle for MMI workflow instance.

This handle represents a workflow instance created within the MMI framework.

Since :: 9.0

typedef void(* mmi_workflow_output_cb)(mmi_workflow_instance_h instance, const char *name, mmi_data_h data, void *user_data)

Callback function type for handling workflow output.

This callback function is called when the MMI framework generates output for a workflow instance.

Since :: 9.0

Remarks:: The instance should not be released. The data should not be released. The data can be used only in the callback. To use outside, make a copy.

Parameters:

[in]	instance	The workflow instance handle for which the output is generated. The instance is the same object for which the callback was set/added. The instance is available until the workflow instance is released.
[in]	name	The name associated with the workflow output. The name can be used only in the callback. To use outside, make a copy.
[in]	data	The output data generated by the workflow.
[in]	user_data	User-provided data passed to the callback function.

See also:: mmi_workflow_instance_set_output_cb(); mmi_workflow_instance_unset_output_cb()

Enumeration Type Documentation

enum mmi_state_e

Enumeration for MMI state.

This enumeration defines the different states of the MMI client.

Since :: 9.0

Enumerator:

MMI_STATE_NONE	Indicates that there is no active state.
MMI_STATE_READY	Indicates that the MMI client is ready to use.

Function Documentation

int mmi_custom_workflow_instance_create	(	mmi_workflow_h	workflow,
		mmi_workflow_instance_h *	instance
	)

Instantiates a workflow from a custom workflow prototype.

This function creates an instance of a workflow based on a custom workflow prototype.

Since :: 9.0

Remarks:: The instance should be released using mmi_workflow_instance_destroy().

Parameters:

[in]	workflow	The handle to the custom workflow prototype.
[out]	instance	The handle to the newly created workflow instance.

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter
MMI_ERROR_OUT_OF_MEMORY	Out of memory

Precondition:: The custom workflow prototype must be valid and properly configured.

Postcondition:: A new workflow instance will be created and assigned to the provided instance handle.

Example

   #include <mmi.h>
   ...
   const char *workflow_script = "@workflow\n...";
   mmi_workflow_h workflow;
   mmi_workflow_create_from_script(workflow_script, &workflow);
   ...
   mmi_workflow_instance_h instance;
   mmi_custom_workflow_instance_create(workflow, &instance);
   ...
   mmi_workflow_instance_destroy(instance);

See also:: mmi_workflow_h; mmi_workflow_instance_h

int mmi_deinitialize ( void )

Deinitializes the MMI framework.

This function deinitializes the MMI (Multimodal Interaction) framework. It must be called after all MMI operations are completed.

Since :: 9.0

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_OPERATION_FAILED	Operation failed

See also:: mmi_initialize(void)

int mmi_initialize ( void )

Initializes the MMI framework.

This function initializes the MMI (Multimodal Interaction) framework. It must be called before any other MMI functions.

Since :: 9.0

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_OPERATION_FAILED	Operation failed
MMI_ERROR_OUT_OF_MEMORY	Out of memory

See also:: mmi_deinitialize(void)

int mmi_set_state_changed_cb	(	mmi_state_changed_cb	callback,
		void *	user_data
	)

Sets a callback function to be invoked when the MMI state changes.

This function sets a callback function that will be called whenever the state of the MMI framework changes.

Since :: 9.0

Parameters:

[in]	callback	The callback function to be called when state is changed
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: mmi_state_changed_cb(); mmi_unset_state_changed_cb()

int mmi_standard_workflow_instance_create	(	mmi_standard_workflow_type_e	type,
		mmi_workflow_instance_h *	instance
	)

Creates a new workflow instance from a standard workflow prototype.

This function creates a new workflow instance from a predefined standard workflow prototype.

Since :: 9.0

Remarks:: The instance should be released using mmi_workflow_instance_destroy().

Parameters:

[in]	type	The type of the standard workflow prototype
[out]	instance	A pointer to the created workflow instance handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter
MMI_ERROR_OUT_OF_MEMORY	Out of memory

Example

   #include <mmi.h>
   ...
   mmi_workflow_instance_h instance;
   mmi_standard_workflow_instance_create(MMI_STANDARD_WORKFLOW_VOICE_TOUCH, &instance);
   ...
   mmi_workflow_instance_destroy(instance);

See also:: mmi_standard_workflow_type_e; mmi_workflow_instance_destroy()

int mmi_unset_state_changed_cb ( mmi_state_changed_cb callback )

Unsets the previously set callback function for MMI state changes.

This function removes the previously set callback function that was called whenever the state of the MMI framework changes.

Since :: 9.0

Parameters:

[in] callback The callback function to be unset

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: A callback function must have been set using mmi_set_state_changed_cb() before calling this function.

Postcondition:: The callback function will no longer be called when the MMI state changes.

See also:: mmi_state_changed_cb(); mmi_set_state_changed_cb()

int mmi_workflow_instance_activate ( mmi_workflow_instance_h instance )

Activates a workflow instance.

This function starts the execution of a workflow instance.

Since :: 9.0

Parameters:

[in] instance The handle to the workflow instance to be activated.

Returns:: 0 on success, otherwise a negative error value.

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created before calling this function.

Postcondition:: The workflow instance is ready to process inputs and emit outputs.

See also:: mmi_standard_workflow_instance_create(); mmi_custom_workflow_instance_create(); mmi_workflow_instance_deactivate()

int mmi_workflow_instance_deactivate ( mmi_workflow_instance_h instance )

Deactivates a workflow instance.

This function stops the execution of a workflow instance.

Since :: 9.0

Parameters:

[in] instance The handle to the workflow instance to be deactivated.

Returns:: 0 on success, otherwise a negative error value.

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created and activated before calling this function.

Postcondition:: The workflow instance is stopped and cannot process inputs or emit outputs.

See also:: mmi_workflow_instance_activate()

int mmi_workflow_instance_destroy ( mmi_workflow_instance_h instance )

Destroys a workflow instance.

This function destroys a workflow instance and releases all associated resources.

Since :: 9.0

Parameters:

[in] instance The handle to the workflow instance to be destroyed.

Returns:: 0 on success, otherwise a negative error value.

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created and activated before calling this function.

Postcondition:: The workflow instance is destroyed and its handle becomes invalid.

See also:: mmi_standard_workflow_instance_create(); mmi_custom_workflow_instance_create(); mmi_workflow_instance_activate()

int mmi_workflow_instance_emit_signal	(	mmi_workflow_instance_h	instance,
		mmi_signal_h	signal
	)

Emits a signal to a workflow instance.

This function sends a signal to the workflow instance.

Since :: 9.0

Parameters:

[in]	instance	The handle to the workflow instance.
[in]	signal	The handle to the signal to be emitted.

Returns:: 0 on success, otherwise a negative error value.

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created and activated before calling this function.

Postcondition:: The signal is processed by the workflow instance.

See also:: mmi_signal_create()

int mmi_workflow_instance_set_attribute	(	mmi_workflow_instance_h	instance,
		mmi_attribute_h	attribute
	)

Sets an attribute of a workflow instance.

This function sets an attribute to the workflow instance.

Since :: 9.0

Parameters:

[in]	instance	The handle to the workflow instance.
[in]	attribute	The handle to the attribute to be set.

Returns:: 0 on success, otherwise a negative error value.

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created before calling this function.

Postcondition:: The attribute is set to the workflow instance.

See also:: mmi_attribute_create()

int mmi_workflow_instance_set_output_cb	(	mmi_workflow_instance_h	instance,
		const char *	name,
		mmi_workflow_output_cb	callback,
		void *	user_data
	)

Sets a callback function to receive workflow output.

This function sets a callback function that will be called when the workflow instance emits output.

Since :: 9.0

Parameters:

[in]	instance	The handle to the workflow instance.
[in]	name	The name associated with the callback.
[in]	callback	The callback function to be set.
[in]	user_data	The user data to be passed to the callback function.

Returns:: 0 on success, otherwise a negative error value.

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created before calling this function.

Postcondition:: The callback function will be called when the workflow instance emits output.

See also:: mmi_workflow_output_cb(); mmi_workflow_instance_unset_output_cb()

int mmi_workflow_instance_unset_output_cb	(	mmi_workflow_instance_h	instance,
		mmi_workflow_output_cb	callback
	)

Unsets a callback function for an output of a workflow instance.

This function unsets a callback function that was set by mmi_workflow_instance_set_output_cb(). After this function is called, the callback function will not be called when the workflow instance emits output.

Since :: 9.0

Parameters:

[in]	instance	The handle to the workflow instance
[in]	callback	The callback function pointer to unset

Returns:: 0 on success, otherwise a negative error value

Return values:

MMI_ERROR_NONE	Successful.
MMI_ERROR_NOT_SUPPORTED	Not supported
MMI_ERROR_INVALID_PARAMETER	Invalid parameter.

Precondition:: The workflow instance must have been created before calling this function.

Postcondition:: The callback function will not be called when the workflow instance emits output.

See also:: mmi_workflow_output_cb(); mmi_workflow_instance_set_output_cb()

Required Header

Overview

State Transitions

Callback(Event) Operations

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation