Sending content using NFC Share Cards
The NFC Share Card is one of the many BlackBerry 10 cards that can be invoked by the invocation framework on behalf of an app. Your app can send an InvokeRequest to the invocation framework in order to share content with the help of the NFC Share Card. These requests and handlers can be created in QML using and InvokeActionItem, or they can be created in C++ using the InvokeManager class.
In either case, your app must set the action property of the InvokeRequest to a value of bb.action.SHARE. Then it must set the InvokeRequest object's uri, mimeType, or data properties. Once this is done, the InvokeRequest is sent by your app to the invocation framework.
The invocation framework will invoke the Share dialog as shown in the screenshot to the right. This Share dialog contains a list of all invocation targets that are registered to share the content provided by the invoking application. Users can select an application from the menu to help them share their content. As you can see in the image to the right, these invocation targets include the NFC Share Card.
If the user selects the NFC Share Card from the above Share dialog, then the NFC Share Card shown in the screenshot to the right is displayed with a preview of the shared content.
As you can see in the screen shot to the right, the NFC Share Card is ready to share an image file. In this case, Bluetooth Connection Handover is used to share the image file with the NFC target device.
For more information on the Connection Handover NFC specification, see NFC Forum.
Supported functionality of the NFC Share Card
- Writing small amounts of data to an NFC tag.
- Sending small amounts of data to another NFC-enabled device using SNEP.
- Transferring files to another NFC-enabled device using NFC Connection Handover with Bluetooth transport.
The NFC Share Card uses the following criteria to select one of the above sharing approaches:
- The combination of uri, mimeType and data property values defined within the InvokeRequest.
- The type of content being shared and the NFC target detected. The NFC target is an NFC Tag or NFC-enabled device that is receiving the content. For example, content that is a Data type can either be written to NFC-tags, or sent using SNEP to NFC devices. Content that is a File type is typically sent using the Bluetooth Connection Handover approach.
The NFC Share Card is registered with the invocation framework by default. This is done to ensure that it will always get displayed in the list of invocation targets shown in the Share dialog when the action element of an InvokeRequest is set to bb.action.SHARE.
When your app shares content with the help of Share Cards, it doesn't have control over which card will be selected by a user who wants to share their content. Your app can control which Share Cards appear in the list of invocation targets by specifying the type of content that will be shared. This is done using the uri, mimeType and data property values defined within the InvokeRequest, as mentioned above.
For example, if an app decides to share text content, and packages it as a text/plain MIME-type, any share card that is registered to handle that MIME-type will appear in the Share dialog.
When your app wants to target the NFC Share Card specifically, the text content should be wrapped within an NDEF message, and the MIIME-type of the shared content should be set to application/vnd.rim.nfc.ndef. You can also specify the invocation target by setting the target property of the InvokeRequest to sys.NFCViewer, which will invoke the NFC Viewer app.
Most common use case for sharing content
The most common use case for sharing content with the help of Share Cards is the process described above using the invocation framework to select the content to share (uri, mimeType or data) and letting the invocation framework build a list of invocation targets to display to the user in the Share dialog. This use case is illustrated in the flow and sequence diagram shown below.
Flow diagram: Sharing content using the NFC Share Card
The following diagram illustrates the flow when sharing file content using the NFC Share Card.
The following diagram illustrates the flow when sharing data content using the NFC Share Card.
Sequence diagram: Sharing content using the NFC Share Card
The following diagram illustrates the sequence of events that occur when sharing content using the NFC Share Card.
The above diagrams depict the complete interaction between the device components involved in the process of sharing over NFC with the help of Share Cards. It's important to remember that your app's involvement is limited to interacting with the components of the invocation framework, which includes the InvokeActionItem or InvokeRequest.
Last modified: 2013-10-31