NfcShareManager

Since: BlackBerry 10.0.0

#include <bb/system/NfcShareManager>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

The NfcShareManager class manages all interactions related to sharing files and data over NFC.

A client process can share content (data or files) using NFC technology by tapping an NFC-enabled device or an NFC tag. The NfcShareManager class is the entry point to access this functionality.

To share content using NFC, the client process must do the following:
  1. Specify the type of content to be shared and "Start Transfer" mode by calling setShareMode() with the desired content type.

  2. Specify the content to be shared by making a successful call to one of Note that the content type must match the type set in the preceding call to setShareMode().
  3. Tap the device with another NFC-enabled device or an NFC tag.

The client process can call setShareContent() as many times as needed provided that the content being set matches the current content type set in a preceding call to setShareMode().

When sharing files, the client process can call setShareContent() even after tapping another NFC-enabled device. To enable this functionality, the client process should first call the setShareMode(bb::system::NfcShareMode::File, bb::system::NfcShareStartTransferMode::OnDemand) method.

The client process can change the content type and "Start Transfer" mode at any time by calling setShareMode() with a new content type and a new "Start Transfer" mode. If the new content type differs from the previous content type, any content that was previously set by a call to setShareContent() will be cleared. If the "Start Transfer" mode was set to NfcShareStartTransferMode::OnTap, new content must be set before any sharing can take place.

The client application can reset both the content type and the content to be shared using the reset() method.

The status of any sharing operations is obtained using the signals finished() and error(). The finished() signal is emitted when the operation is successful. The error() signal is emitted when the operation fails. Both signals include a parameter providing more detailed information.

Note:

You should create only one instance of NfcShareManger per application. Each additional instance that you create receives events that are identical to the original, making their creation redundant. In addition, there are cases where a NfcShareManger might try to access an event that has already been managed exclusively by another instance of the NfcShareManger, which can cause the application to crash.


Overview

Public Functions Index

Public Slots Index

voidcancelTarget ()
voidreset ()
voidsetShareMode (bb::system::NfcShareMode::Type method)
voidsetShareMode (bb::system::NfcShareMode::Type method, bb::system::NfcShareStartTransferMode::Type transferMode)
voidsetShareMode (bb::system::NfcShareMode::Type method, bb::system::NfcShareStartTransferMode::Type transferMode, const QList< bb::system::NfcShareHandoverTransport::Type > &transports)
voidstartTransfer ()

Signals Index

voiderror (bb::system::NfcShareError::Type error)
voidfinished (bb::system::NfcShareSuccess::Type result)
voidshareModeChanged (bb::system::NfcShareMode::Type mode)
voidtargetAcquired ()
voidtargetCancelled ()

Public Functions

NfcShareManager (

Creates a new NfcShareManager object.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~NfcShareManager ()

Destructor.

Since:

BlackBerry 10.0.0

bb::system::NfcShareSetContentError::Type setShareContent (

Specifies file content to be shared over NFC.

The current share mode must be set to NfcShareMode::File for this method to complete successfully.

The supplied request must contain at least one file in its list of URLs.

Parameters
request

A description of the file content to share.

Return:

Returns the result of the operation. See NfcShareSetContentError for the list of values.

Since:

BlackBerry 10.0.0

bb::system::NfcShareSetContentError::Type setShareContent (

Specifies the data content to be shared over NFC.

The current share mode must be set to NfcShareMode::Data for this method to complete successfully.

Parameters
request

A description of the data content to share.

Return:

Returns the result of the operation. See NfcShareSetContentError for the list of values.

Since:

BlackBerry 10.0.0

bb::system::NfcShareMode::Type shareMode ()

Retrieves the current share mode for this NFC manager.

Return:

Returns the current NFC share mode. See NfcShareMode for the list of share modes.

Since:

BlackBerry 10.0.0

Public Slots

void cancelTarget ()

Cancels the target that was acquired as a result of the last successful handover.

Discards the target that was acquired as a result of the last successful handover. This method should be used you have no intention to start a transfer to the recently acquired target. Cancellation of the target will result in clearing (resetting) the target acquired as result of the latest tap. You should not be calling the NfcShareManager::cancelTransfer() method more than once for every NfcShareSuccess::TargetAcquired signal received, when the "Start Transfer" mode is set to NfcShareStartTransferMode::OnDemand. This method will not cancel the target if the transfer is already in progress. The targetCancelled() signal is emitted when this command is successfully executed.

Since:

BlackBerry 10.2.0

void reset ()

Resets the state of this NFC manager.

The share mode is reset to NfcShareMode::Disabled. Any content set by a call to the setShareContent() method is cleared. The target will also be cleared however no targetCancelled() signal is emitted.

Since:

BlackBerry 10.0.0

void setShareMode (

Changes the share mode for this NFC manager.

If the new mode is different than the previous mode, any content that was set by a previous call to the setShareContent() method is cleared. If data or file sharing is in progress, an attempt to change the Share Mode will fail, and the NFC Share Manager will deliver a NfcShareError::TransferInProgress error.

Note:

If this method is called, the "Start Transfer" mode is set to NfcShareStartTransferMode::OnTap by default.

Parameters
method

The new share mode for this manager. See NfcShareMode for the list of share modes.

Note:

When handover transports are not specified, the most appropriate order of transports available will be used based on the payload that the shared content contains at the moment a tap occurs.

Since:

BlackBerry 10.0.0

void setShareMode (

Changes the share mode for this NFC manager.

If the mode is being switched between different "File" and "Data" modes, any content that was set by a previous call to the setShareContent() method is cleared. If data or file sharing is in progress, an attempt to change the Share Mode and/or the "Transfer On Tap" setting will have no effect, and the NFC Share Manager will deliver a NfcShareError::TransferInProgress error.

Parameters
method

The new share mode for this manager. See NfcShareMode for a list of share modes.

transferMode

Specifies "Start Transfer" mode for this NFC manager for a given Share Mode. When this option is set to NfcShareStartTransferMode::OnTap, the share content being set by NfcShareManager::setShareContent() will be shared with the device being tapped as soon as tap happens. When the "Start Transfer" mode is set to NfcShareStartTransferMode::OnDemand, the share content WILL NOT be transferred to the device being tapped until the NfcShareManager::startTransfer() method is called. This option allows content to be prepared (or set) for sharing AFTER the tap occurs. Currently, the NfcShareStartTransferMode::OnDemand option is only supported for files.

Note:

When handover transports are not specified, the most appropriate order of transports available will be used based on the payload that the shared content contains at the moment a tap occurs.

Since:

BlackBerry 10.2.0

void setShareMode (

Changes the share mode for this NFC manager.

If the mode is being switched between different "File" and "Data" modes, any content that was set by a previous call to the setShareContent() method is cleared. If data or file sharing is in progress, an attempt to change the Share Mode and/or the "Transfer On Tap" setting will have no effect, and the NFC Share Manager will deliver a NfcShareError::TransferInProgress error.

Parameters
method

The new share mode for this manager. See NfcShareMode for the list of share modes.

transferMode

Specifies the "Start Transfer" mode for this NFC manager, for a given Share Mode. When this option is set to NfcShareStartTransferMode::OnTap, the share content being set by the NfcShareManager::setShareContent() method will be shared with the device being tapped as soon as the tap happens. When the "Start Transfer" mode is set to NfcShareStartTransferMode::OnDemand, the share content WILL NOT be transferred to the device being tapped until the NfcShareManager::startTransfer() method is called. This option allows content to be prepared (or set) for sharing AFTER the tap occurs. Currently, NfcShareStartTransferMode::OnDemand option is only supported for files.

transports

Specifies the list of handover transports that should be used during the handover negotiation. The handover transports are listed in priority sequence. This means that the transport listed first will be used as the most preferred transport during the handover negotiation process. If this transport fails, there will be an attempt to use the second transport specified in this list etc. This process will continue until all one of the handover transports listed succeeds.

Since:

BlackBerry 10.2.0

void startTransfer ()

Triggers the transfer of the shared content when the "Start Transfer" mode was previously set to NfcShareStartTransferMode::OnDemand.

Triggers the transfer of the shared content, when the "Start Transfer" mode is set to NfcShareStartTransferMode::OnDemand. As with the NfcShareManager::setShareMode() method, the result of this call is obtained using the signals finished() and error(). You should not be calling the NfcShareManager::startTransfer() method more than once for every NfcShareSuccess::TargetAcquired signal received, when the "Start Transfer" mode is set to NfcShareStartTransferMode::OnDemand. Currently, only the file transfer is supported. If data or file sharing is in progress, an attempt to call this method will result in a NfcShareError::TransferInProgress error being delivered over the NfcShareError::error() signal.

Note:

Calling this method 20 seconds after the tap has occurred will cause the transfer to fail. This is because handover negotiation results between two devices will have already expired. In this case, the users must tap their devices again.

Since:

BlackBerry 10.2.0

Signals

void error (

Emitted when an attempt to share content using NFC fails.

Parameters
error

More specific information about the failure. See NfcShareError for a list of possible errors.

Since:

BlackBerry 10.0.0

void finished (

Emitted when content is successfully shared using NFC.

Parameters
result

More specific information on the successfully completed operation. See NfcShareSuccess for a list of values.

Since:

BlackBerry 10.0.0

void shareModeChanged (

Emitted when the share mode for this NFC manager changes.

Parameters
mode

The new share mode. See NfcShareMode for a list of share modes.

Since:

BlackBerry 10.0.0

void targetAcquired ()

A connection handover was successfully established.

This signal is only sent when the "Start Transfer" mode from the NfcShareManager::setShareMode() method is set to NfcShareStartTransferMode::OnDemand. This signal indicates that the content to share can be set, and that the file transfer can be initiated by calling the NfcShareManager::startTransfer() method.

Note:

Currently this signal is only emitted when share mode is set to NfcShareMode::File and the "Start Transfer" mode is set to NfcShareStartTransferMode::OnDemand in the NfcShareManager::setShareMode() method.

Since:

BlackBerry 10.2.0

void targetCancelled ()

A target that was acquired during the last successful handover is discarded.

This signal is only sent after developer calls NfcShareManager::cancelTarget() method. This signal indicates that there are no more targets to transfer data or files to, and any attempt to initiate a file transfer by calling the NfcShareManager::startTransfer() method will fail with a NfcShareError::NoTransferTarget error.

Since:

BlackBerry 10.2.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus