navigator_invoke_invocation_t

This type defines the navigator_invoke_invocation_t structure used by several functions in the invocation framework. Use this to create and control invocations. The navigator_invoke_invocation_t structure is opaque, but includes the following members:

• ID: the ID used to identify the invocation (navigator_invoke_invocation_set_id())
• Target: the target to which the invocation is sent (navigator_invoke_invocation_set_target())
• Source: the location where response messages to the invocation should be sent (navigator_invoke_invocation_set_source())
• Action: the action the invoked target should perform (navigator_invoke_invocation_set_action())
• Type: the MIME type of the data the invoked target should act on (navigator_invoke_invocation_set_type())
• URI: the URI to the data the invoked target should act on (navigator_invoke_invocation_set_uri())
• Transfer mode: the transfer mode for the URI file (navigator_invoke_invocation_set_file_transfer_mode())
• Data: the data the invoked target should act on (navigator_invoke_invocation_set_data())
• Data length: the length of the data the invoked target should act on (navigator_invoke_invocation_set_data())
• Perimeter: the perimeter the target should be invoked in (navigator_invoke_invocation_set_perimeter())
• List ID: the id of the list the invocation is associated with (navigator_invoke_invocation_set_list_id())

To perform an invocation, you must:

1. Instantiate a navigator_invoke_invocation_t structure with the navigator_invoke_invocation_create() function.
2. Set all desired members with the navigator_invoke_invocation_set_*() functions to match the purpose of the invocation. A minimum of either a target, action, or type member is required for the invocation to be recognised by the framework (though further members may be required for more specific invocations, such as including a uri or data member for invocations that require input data to be successfully performed.)
3. Send the invocation with the navigator_invoke_invocation_send() function. Depending on the members you set to the navigator_invoke_invocation_t structure, the invocation is sent either directly to a target handler or the brokering system to determine which target to use based on the provided information.
4. Retrieve the data from an invocation in an event handler by using the navigator_invoke_invocation_get_*() functions.
5. Deallocate the memory reserved for the navigator_invoke_invocation_t structure with the navigator_invoke_invocation_destroy() function.