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 via 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 type of the content 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 devices. To enable this functionality, the client process should call setShareMode(bb::system::NfcShareMode::File, bb::system::NfcShareStartTransferMode::OnDemand) method before.

The client process can change the content type and "Start Transfer" mode at any time by calling setShareMode() with a new content type and 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 "Start Transfer" mode was set to bb::system::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 was successful. The error() signal is emitted when the operation failed. 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 an 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.

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 an 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.

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 bb::system::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 bb::system::NfcShareSetContentError for the list of values.

Since:

BlackBerry 10.0.0

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

Specifies data content to be shared over NFC.

The current share mode must be set to bb::system::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 bb::system::NfcShareSetContentError for the list of values.

Since:

BlackBerry 10.0.0

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

Returns the current share mode for this NFC manager.

Return:

Returns the current NFC share mode. See bb::system::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 developer doesn't have intention to start transfer to the recently acquired target. Cancellation of the target will result in clearing (resetting) the target acquired as result of the latest tap. Developer should not be calling bb::system::NfcShareManager::cancelTransfer() method more than once for every bb::system::NfcShareSuccess::TargetAcquired signal received when "Start Transfer" mode is set to bb::system::NfcShareStartTransferMode::OnDemand. This method will not cancel the target if the transfer is already in progress. Successful execution of this command will emit targetCancelled() signal.

Since:

BlackBerry 10.2.0

void reset ()

Resets the state of this NFC manager.

The share mode is reset to bb::system::NfcShareMode::Disabled. Any content set by a call to setShareContent() is cleared.

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 setShareContent() is cleared. If data/file sharing is in progress, attempt to change Share Mode will fail and NFC Share Manager will deliver bb::system::NfcShareError::TransferInProgress error.

Note:

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

Parameters
method

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

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 setShareContent() is cleared. If data/file sharing is in progress, attempt to change Share Mode and/or "Transfer On Tap" setting will have no effect and NFC Share Manager will deliver bb::system::NfcShareError::TransferInProgress error

Parameters
method

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

transferMode

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

Note:

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

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 setShareContent() is cleared. If data/file sharing is in progress, attempt to change Share Mode and/or "Transfer On Tap" setting will have no effect and NFC Share Manager will deliver bb::system::NfcShareError::TransferInProgress error

Parameters
method

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

transferMode

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

transports

Specifies the list of the handover transports that should be used during handover negotiation. The order is important as the transport specified first will be used as the most preferred transport during the handover negotiation process.

Since:

BlackBerry 10.2.0

void startTransfer ()

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

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

Note:

If this method is called 20 sec after the tap occured, the transfer will fail as Bluetooth pairing between two devices has timed out.

Since:

BlackBerry 10.2.0

Signals

void error (

Emitted when an attempt to share content via NFC fails.

Parameters
error

More specific information about the failure. See bb::system::NfcShareError for the list of possible errors.

Since:

BlackBerry 10.0.0

void finished (

Emitted when content is successfully shared via NFC.

Parameters
result

More specific information on the successfully completed operation. See bb::system::NfcShareSuccess for the 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 bb::system::NfcShareMode for the list of share modes.

Since:

BlackBerry 10.0.0

void targetAcquired ()

A connection handover was successfully established.

This signal is only sent when "Start Transfer" mode from bb::system::NfcShareManager::setShareMode() method is set to bb::system::NfcShareStartTransferMode::OnDemand. This signal notifies the developer that they can now set the content to share and initiate file transfer by calling bb::system::NfcShareManager::startTransfer() method.

Note:

Currently this signal is only emitted when share mode is set to bb::system::NfcShareMode::File and "Start Transfer" mode set to bb::system::NfcShareStartTransferMode::OnDemand in bb::system::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 when "Start Transfer" mode from bb::system::NfcShareManager::setShareMode() method is set to bb::system::NfcShareStartTransferMode::OnDemand. This signal notifies the developer that there is no more targets to transfer data/files to and any attempt to initiate a file transfer by calling bb::system::NfcShareManager::startTransfer() method will fail with bb::system::NfcShareError::NoTransferTarget error.

Since:

BlackBerry 10.2.0

Last modified: 2014-03-13

comments powered by Disqus