navigator_invoke_event_get

Retrieve the invocation structure pointer from the BPS event.

Synopsis:

#include <bps/navigator_invoke.h>

BPS_API const navigator_invoke_invocation_t* navigator_invoke_event_get_invocation(bps_event_t *event)

Since:

BlackBerry 10.0.0

Arguments:

event: The NAVIGATOR_INVOKE_TARGET event to extract the invocation from.

Library:

libbps (For the qcc command, use the -l bps option to link against this library)

Description:

The navigator_invoke_event_get_invocation() function extracts the invocation properties from a navigator_invoke_invocation_t structure sent with the navigator_invoke_invocation_send() function. You should call this function upon receiving the NAVIGATOR_INVOKE_TARGET event from the event handler to perform the task defined by the invocation.

We recommend that you use the navigator_event_get_err() function after calling this function in case of an error in processing. The possible errors for an invocation are:

INVOKE_NO_TARGET_ERROR: There is no target identified by the invocation.
INVOKE_BAD_REQUEST_ERROR: The invocation request specifications do not conform to the permitted parameters of the handler. For example, an image sharing invocation being sent to a target application that cannot share images would result in this error.
INVOKE_INTERNAL_ERROR: A generic error occured in the internal framework while attempting to retrieve the navigator_invoke_invocation_t structure.
INVOKE_TARGET_ERROR: A generic error occured with the target handler.

"Ownership" of an event is not transferred to a handler upon its invocation. A handler must not call the navigator_invoke_invocation_destroy() function on invocation pointers that are retrieved using the navigator_invoke_event_get_invocation() function. The pointer to the navigator_invoke_invocation_t structure is valid until the bps_get_event() function is called again.

Returns:

A pointer to the navigator_invoke_invocation_t structure on success, NULL on failure with errno set.