The opaque invocation argument type.
typedef struct navigator_invoke_invocation_t 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())
To perform an invocation, you must:
- Instantiate a navigator_invoke_invocation_t structure with the navigator_invoke_invocation_create() function.
- 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.)
- 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.
- Retrieve the data from an invocation in an event handler by using the navigator_invoke_invocation_get_*() functions.
- Deallocate the memory reserved for the navigator_invoke_invocation_t structure with the navigator_invoke_invocation_destroy() function.