nfc_settings

This enumeration specifies the types of user settings that are available from the NFC menu on the device.

Synopsis:

#include <nfc/nfc.h>

typedef enum {
      NFC_SETTING_ENABLED = 0   
      NFC_SETTING_CE_BACKLIGHT_OFF = 1   
      NFC_SETTING_CE_POWERED_OFF = 2   
      NFC_SETTING_PROMPT_TO_SEND_FILES = 3   
      NFC_SETTING_ENABLED_ASYNC = 4   
} nfc_settings_t;

Since:

BlackBerry 10.0.0

Data:

NFC_SETTING_ENABLED

User setting responsible for the current status of the NFC radio (on/off).

This setting is reflected to the user as "NFC Connectivity" menu from the device.

It is important to note that NFC_SETTING_ENABLED can be set to true, but not to false, by using the nfc_set_setting() function. An attempt to set NFC_SETTING_ENABLED to false through this function will result in an error of NFC_RESULT_INVALID_PARAMETER. NFC cannot be turned off programmatically; NFC remains enabled until the user explicitly disables NFC from the NFC menu on the device.

Enabling NFC_SETTING_ENABLED from the nfc_set_setting() function will trigger a prompt to be displayed on the device to request permission to modify this user setting. If NFC_SETTING_ENABLED is already enabled, no prompt will be displayed. The nfc_set_setting() function blocks the caller until the user makes a selection. If you don't want a blocking call, you can use the NFC_SETTING_ENABLED_ASYNC variant with nfc_set_setting().

nfc_set_setting() returns one of the following codes of type nfc_result_t:

NFC_RESULT_SUCCESS: The user permitted the operation.
NFC_RESULT_OPERATION_REJECTED: The user denied the operation, an attempt was made to enable NFC when it was already enabled, or the calling application was not in the foreground.
NFC_RESULT_RESOURCE_BUSY: The user allowed the setting change, but the change could not be applied.

The following rules apply when querying (via the nfc_get_setting() function) the value of this user setting:

If NFC hardware is not supported, NFC_SETTING_ENABLED will be false.
If NFC is not allowed by configuration on the device, NFC_SETTING_ENABLED will be false.
If NFC radio is OFF, NFC_SETTING_ENABLED will be false.
If NFC radio is ON, NFC_SETTING_ENABLED will be true.

NFC_SETTING_CE_BACKLIGHT_OFF

User setting governing whether or not card transactions are allowed when the device is either locked or its backlight is off.

This user setting is reflected to the user as "Allow NFC Card Transactions When locked or backlight is off" from the NFC menu on the device.

An application attempting to change this setting must currently be in the foreground.

Enabling NFC_SETTING_CE_BACKLIGHT_OFF from the nfc_set_setting() function will trigger a prompt to be displayed on the device to request permission to modify this user setting. If NFC_SETTING_CE_BACKLIGHT_OFF is already enabled, no prompt will be displayed.

Disabling NFC_SETTING_CE_BACKLIGHT_OFF from the nfc_set_setting() function will trigger a prompt to be displayed on the device to request permission to modify this user setting. If NFC_SETTING_CE_POWERED_OFF is enabled, then the user prompt will additionally request permission to disable both NFC_SETTING_CE_BACKLIGHT_OFF and NFC_SETTING_CE_POWERED_OFF at the same time. If NFC_SETTING_CE_BACKLIGHT_OFF is already disabled, no prompt will be displayed.

Note that nfc_set_setting() returns successfully, once the prompt is displayed on the device. Whether you're enabling or disabling, an NFC_CE_ENABLE_BACKLIGHT_OFF_EVENT or an NFC_CE_DISABLE_BACKLIGHT_OFF_EVENT notification is respectively sent to the application. This notification includes one of the following return codes of type nfc_result_t:

NFC_RESULT_SUCCESS (the user permitted the operation)
NFC_RESULT_OPERATION_REJECTED (the user denied the operation)

Use the nfc_get_notification_value() function to retrieve the return code from either the NFC_CE_ENABLE_BACKLIGHT_OFF_EVENT or the NFC_CE_DISABLE_BACKLIGHT_OFF_EVENT notification.

NFC_SETTING_CE_POWERED_OFF

User setting governing whether or not card transactions are enabled when the device is powered off.

An application attempting to change this setting must currently be in the foreground.

This user setting is represented by "Allow NFC Card Transactions When device is turned off" from the NFC menu on the device. Note that in order for this user setting to be enabled, "Allow NFC Card Transactions When locked or backlight is off" must also be enabled.

The user will be prompted by a display on the device to permit modification to this user setting if you are setting a value that is different from the current value of this setting. If the user permits this change, then Card Transactions while the device is powered off will reflect the settings change at once.

Enabling NFC_SETTING_CE_POWERED_OFF from the nfc_set_setting() function will trigger a prompt to be displayed on the device to request permission to modify this user setting. If NFC_SETTING_CE_BACKLIGHT_OFF is disabled, then the user prompt will additionally request permission to enable both NFC_SETTING_CE_BACKLIGHT_OFF and NFC_SETTING_CE_POWERED_OFF at the same time. If NFC_SETTING_CE_POWERED_OFF is already enabled, no prompt will be displayed.

Disabling NFC_SETTING_CE_POWERED_OFF from the nfc_set_setting() function will trigger a prompt to be displayed on the device to request permission to modify this user setting. If NFC_SETTING_CE_POWERED_OFF is already disabled, no prompt will be displayed.

Note that nfc_set_setting() returns successfully, once the prompt is displayed on the device. Whether you're enabling or disabling, an NFC_CE_ENABLE_POWERED_OFF_EVENT or an NFC_CE_DISABLE_POWERED_OFF_EVENT notification is respectively sent to the application. This notification includes one of the following return codes of type nfc_result_t:

NFC_RESULT_SUCCESS (the user permitted the operation)
NFC_RESULT_OPERATION_REJECTED (the user denied the operation)

Use the nfc_get_notification_value() function to retrieve the return code from either the NFC_CE_ENABLE_POWERED_OFF_EVENT or the NFC_CE_DISABLE_POWERED_OFF_EVENT notification.

NFC_SETTING_PROMPT_TO_SEND_FILES: User setting that specifies whether the confirmation prompt "Do you want to send file(s)?" should be presented when a user's attempt to send files to another device is detected as a result of an NFC Tap gesture.; This user setting can be changed only by the user from the NFC menu on the device. It cannot be changed using the nfc_set_setting() function.

NFC_SETTING_ENABLED_ASYNC

User setting responsible for the current status of the NFC radio (on/off).

This is the asynchronous variant of NFC_SETTING_ENABLED and may be used in conjunction with nfc_set_setting().

Enabling NFC_SETTING_ENABLED_ASYNC from the nfc_set_setting() function will trigger a prompt to be displayed on the device to request permission to modify this user setting. If NFC_SETTING_ENABLED_ASYNC is already enabled, no prompt will be displayed.

An attempt to call NFC_SETTING_ENABLED_ASYNC from the nfc_get_setting() function will result in an error of NFC_RESULT_INVALID_PARAMETER.

It is important to note that NFC_SETTING_ENABLED_ASYNC can be set to true, but not to false, by using the nfc_set_setting() function. An attempt to set NFC_SETTING_ENABLED_ASYNC to false through this function will result in an error of NFC_RESULT_INVALID_PARAMETER. NFC cannot be turned off programmatically; NFC remains enabled until the user explicitly disables NFC from the NFC menu on the device.

Note that nfc_set_setting() returns successfully, once the prompt is displayed on the device. After the user makes a selection an NFC_SETTING_ENABLED_ASYNC_EVENT notification is sent to the application. This notification includes one of the following return codes of type nfc_result_t:

NFC_RESULT_SUCCESS: The user permitted the operation.
NFC_RESULT_OPERATION_REJECTED: The user denied the operation.
NFC_RESULT_RESOURCE_BUSY: The user allowed the setting change, but the setting could not be applied.

Use the nfc_get_notification_value() function to retrieve the return code from the NFC_SETTING_ENABLED_ASYNC_EVENT notification.

Since: BlackBerry 10.2.0

Library:

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

nfc_settings_t

Synopsis:

Since:

Data:

Library:

Description: