nbgl_use_case.h

Go to the documentation of this file.

 
#ifndef NBGL_USE_CASE_H
#define NBGL_USE_CASE_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*********************
 *      INCLUDES
 *********************/
 
#include "nbgl_content.h"
#ifdef NBGL_PAGE
#include "nbgl_page.h"
#else  // NBGL_PAGE
#include "nbgl_flow.h"
#endif  // NBGL_PAGE
 
/*********************
 *      DEFINES
 *********************/
#define FIRST_USER_TOKEN 50
 
#define LAST_PAGE_FOR_REVIEW 0xFF
 
#if defined(TARGET_STAX)
#define NB_MAX_LINES_IN_DETAILS 12
#elif defined(TARGET_FLEX)
#define NB_MAX_LINES_IN_DETAILS 11
#elif defined(TARGET_APEX)
#define NB_MAX_LINES_IN_DETAILS 11
#else
// Nano
#define NB_MAX_LINES_IN_DETAILS 3
#endif  // TARGETS
 
#if defined(TARGET_STAX)
#define NB_MAX_LINES_IN_REVIEW 10
#elif defined(TARGET_FLEX)
#define NB_MAX_LINES_IN_REVIEW 9
#elif defined(TARGET_APEX)
#define NB_MAX_LINES_IN_REVIEW 9
#else
// Nano
#define NB_MAX_LINES_IN_REVIEW 3
#endif  // TARGETS
 
#define NB_MAX_DISPLAYED_PAIRS_IN_REVIEW 4
 
#define TAG_VALUE_AREA_HEIGHT (SCREEN_HEIGHT - SMALL_CENTERING_HEADER - SIMPLE_FOOTER_HEIGHT)
 
#define INFOS_AREA_HEIGHT (SCREEN_HEIGHT - TOUCHABLE_HEADER_BAR_HEIGHT)
 
#define TAGLINE_PART1 "This app enables signing\ntransactions on the"
#define TAGLINE_PART2 "network."
 
#define APP_DESCRIPTION_MAX_LEN 74
 
#define MAX_APP_NAME_FOR_SDK_TAGLINE \
    (APP_DESCRIPTION_MAX_LEN - 1 - (sizeof(TAGLINE_PART1) + sizeof(TAGLINE_PART2)))
 
#define INIT_HOME_PAGE 0xff
 
#define STATUS_SCREEN_DURATION 3000
 
#define REAL_TYPE_MASK 0x7
 
// returns true if the given warning structure requires display of an initial page (internal usage)
#define HAS_INITIAL_WARNING(_warning)                                    \
    ((_warning->predefinedSet                                            \
      & ((1 << W3C_THREAT_DETECTED_WARN) | (1 << W3C_RISK_DETECTED_WARN) \
         | (1 << BLIND_SIGNING_WARN)))                                   \
     || (_warning->info != NULL))
 
/**********************
 *      MACROS
 **********************/
 
/**********************
 *      TYPEDEFS
 **********************/
typedef void (*nbgl_callback_t)(void);
 
typedef bool (*nbgl_navCallback_t)(uint8_t page, nbgl_pageContent_t *content);
 
typedef void (*nbgl_choiceCallback_t)(bool confirm);
 
typedef void (*nbgl_actionCallback_t)(uint8_t page);
 
typedef void (*nbgl_pinValidCallback_t)(const uint8_t *pin, uint8_t pinLen);
 
typedef void (*nbgl_keyboardButtonsCallback_t)(nbgl_layoutKeyboardContent_t *content,
                                               uint32_t                     *mask);
 
typedef void (*nbgl_contentCallback_t)(uint8_t contentIndex, nbgl_content_t *content);
 
typedef struct {
    bool callbackCallNeeded;  
    union {
        const nbgl_content_t *contentsList;  
        nbgl_contentCallback_t
            contentGetterCallback;  
    };
    uint8_t nbContents;  
} nbgl_genericContents_t;
 
typedef enum {
    STRONG_HOME_ACTION = 0,  
    SOFT_HOME_ACTION         
} nbgl_homeActionStyle_t;
 
typedef struct {
    const char                *text;  
    const nbgl_icon_details_t *icon;  
    nbgl_callback_t callback;      
    nbgl_homeActionStyle_t style;  
} nbgl_homeAction_t;
 
typedef struct {
    const char                *text;  
    const nbgl_icon_details_t *icon;  
    const char *modalTitle;   
    nbgl_contentType_t type;  
    union {
        nbgl_contentInfoList_t
            infos;  
    };
} nbgl_tipBox_t;
 
typedef enum {
    NO_TYPE_WARNING = 0,    
    CENTERED_INFO_WARNING,  
    QRCODE_WARNING,         
    BAR_LIST_WARNING        
} nbgl_genericDetailsType_t;
 
typedef nbgl_genericDetailsType_t nbgl_warningDetailsType_t;
 
typedef struct {
    uint8_t            nbBars;    
    const char *const *texts;     
    const char *const *subTexts;  
    const nbgl_icon_details_t **icons;  
    const struct nbgl_genericDetails_s
        *details;  
} nbgl_genericBarList_t;
 
typedef nbgl_genericBarList_t nbgl_warningBarList_t;
 
typedef struct nbgl_genericDetails_s {
    const char *title;  
    nbgl_genericDetailsType_t
        type;  
    union {
        nbgl_contentCenter_t
            centeredInfo;  
#ifdef NBGL_QRCODE
        nbgl_layoutQRCode_t qrCode;     
#endif                                  // NBGL_QRCODE
        nbgl_genericBarList_t barList;  
    };
} nbgl_genericDetails_t;
 
typedef nbgl_genericDetails_t nbgl_warningDetails_t;
 
typedef enum {
    W3C_ISSUE_WARN = 0,        
    W3C_RISK_DETECTED_WARN,    
    W3C_THREAT_DETECTED_WARN,  
    W3C_NO_THREAT_WARN,        
    BLIND_SIGNING_WARN,        
    GATED_SIGNING_WARN,        
    NB_WARNING_TYPES
} nbgl_warningType_t;
 
typedef struct nbgl_preludeDetails_s {
    const nbgl_icon_details_t *icon;         
    const char                *title;        
    const char                *description;  
    const char                *buttonText;   
    const char                *footerText;   
    const nbgl_genericDetails_t *details;    
} nbgl_preludeDetails_t;
 
typedef struct {
    uint32_t predefinedSet;    
    const char *dAppProvider;  
    const char *reportUrl;     
    const char *reportProvider;   
    const char *providerMessage;  
    const nbgl_warningDetails_t
        *introDetails;  
    const nbgl_warningDetails_t
        *reviewDetails;  
    const nbgl_contentCenter_t
        *info;  
    const nbgl_icon_details_t
        *introTopRightIcon;  
    const nbgl_icon_details_t *reviewTopRightIcon;  
    const nbgl_preludeDetails_t
        *prelude;  
} nbgl_warning_t;
 
#ifdef NBGL_KEYBOARD
typedef struct {
#ifdef HAVE_SE_TOUCH
    const char *buttonText;  
#endif
    nbgl_callback_t onButtonCallback;  
} nbgl_kbdButtonParams_t;
 
typedef struct {
    const char **buttons;           
    int          firstButtonToken;  
    nbgl_layoutTouchCallback_t
        onButtonCallback;  
    nbgl_keyboardButtonsCallback_t
        updateButtonsCallback;  
} nbgl_kbdSuggestParams_t;
 
typedef struct {
    nbgl_layoutKeyboardContentType_t type;         
    const char                      *title;        
    char                            *entryBuffer;  
    uint8_t                          entryMaxLen;  
    keyboardMode_t                   mode;         
    bool lettersOnly;  
#ifdef HAVE_SE_TOUCH
    bool           numbered;  
    uint8_t        number;    
    keyboardCase_t casing;    
#endif
    union {
        nbgl_kbdSuggestParams_t
                               suggestionParams;  
        nbgl_kbdButtonParams_t confirmationParams;  
    };
} nbgl_keyboardParams_t;
#endif  // NBGL_KEYBOARD
 
typedef enum {
    TYPE_TRANSACTION
        = 0,        
    TYPE_MESSAGE,   
    TYPE_OPERATION  
} nbgl_opType_t;
 
#define SKIPPABLE_OPERATION (1 << 4)
 
#define BLIND_OPERATION (1 << 5)
 
typedef uint32_t nbgl_operationType_t;
 
typedef enum {
    STATUS_TYPE_TRANSACTION_SIGNED = 0,
    STATUS_TYPE_TRANSACTION_REJECTED,
    STATUS_TYPE_MESSAGE_SIGNED,
    STATUS_TYPE_MESSAGE_REJECTED,
    STATUS_TYPE_OPERATION_SIGNED,
    STATUS_TYPE_OPERATION_REJECTED,
    STATUS_TYPE_ADDRESS_VERIFIED,
    STATUS_TYPE_ADDRESS_REJECTED,
} nbgl_reviewStatusType_t;
 
/**********************
 * GLOBAL PROTOTYPES
 **********************/
 
void nbgl_useCaseHomeAndSettings(const char                   *appName,
                                 const nbgl_icon_details_t    *appIcon,
                                 const char                   *tagline,
                                 const uint8_t                 initSettingPage,
                                 const nbgl_genericContents_t *settingContents,
                                 const nbgl_contentInfoList_t *infosList,
                                 const nbgl_homeAction_t      *action,
                                 nbgl_callback_t               quitCallback);
 
void nbgl_useCaseReview(nbgl_operationType_t              operationType,
                        const nbgl_contentTagValueList_t *tagValueList,
                        const nbgl_icon_details_t        *icon,
                        const char                       *reviewTitle,
                        const char                       *reviewSubTitle,
                        const char                       *finishTitle,
                        nbgl_choiceCallback_t             choiceCallback);
 
void nbgl_useCaseReviewBlindSigning(nbgl_operationType_t              operationType,
                                    const nbgl_contentTagValueList_t *tagValueList,
                                    const nbgl_icon_details_t        *icon,
                                    const char                       *reviewTitle,
                                    const char                       *reviewSubTitle,
                                    const char                       *finishTitle,
                                    const nbgl_tipBox_t              *tipBox,
                                    nbgl_choiceCallback_t             choiceCallback);
void nbgl_useCaseAdvancedReview(nbgl_operationType_t              operationType,
                                const nbgl_contentTagValueList_t *tagValueList,
                                const nbgl_icon_details_t        *icon,
                                const char                       *reviewTitle,
                                const char                       *reviewSubTitle,
                                const char                       *finishTitle,
                                const nbgl_tipBox_t              *tipBox,
                                const nbgl_warning_t             *warning,
                                nbgl_choiceCallback_t             choiceCallback);
 
void nbgl_useCaseReviewLight(nbgl_operationType_t              operationType,
                             const nbgl_contentTagValueList_t *tagValueList,
                             const nbgl_icon_details_t        *icon,
                             const char                       *reviewTitle,
                             const char                       *reviewSubTitle,
                             const char                       *finishTitle,
                             nbgl_choiceCallback_t             choiceCallback);
 
void nbgl_useCaseAddressReview(const char                       *address,
                               const nbgl_contentTagValueList_t *additionalTagValueList,
                               const nbgl_icon_details_t        *icon,
                               const char                       *reviewTitle,
                               const char                       *reviewSubTitle,
                               nbgl_choiceCallback_t             choiceCallback);
 
void nbgl_useCaseReviewStatus(nbgl_reviewStatusType_t reviewStatusType,
                              nbgl_callback_t         quitCallback);
 
void nbgl_useCaseReviewStreamingStart(nbgl_operationType_t       operationType,
                                      const nbgl_icon_details_t *icon,
                                      const char                *reviewTitle,
                                      const char                *reviewSubTitle,
                                      nbgl_choiceCallback_t      choiceCallback);
 
void nbgl_useCaseReviewStreamingBlindSigningStart(nbgl_operationType_t       operationType,
                                                  const nbgl_icon_details_t *icon,
                                                  const char                *reviewTitle,
                                                  const char                *reviewSubTitle,
                                                  nbgl_choiceCallback_t      choiceCallback);
 
void nbgl_useCaseAdvancedReviewStreamingStart(nbgl_operationType_t       operationType,
                                              const nbgl_icon_details_t *icon,
                                              const char                *reviewTitle,
                                              const char                *reviewSubTitle,
                                              const nbgl_warning_t      *warning,
                                              nbgl_choiceCallback_t      choiceCallback);
 
void nbgl_useCaseReviewStreamingContinueExt(const nbgl_contentTagValueList_t *tagValueList,
                                            nbgl_choiceCallback_t             choiceCallback,
                                            nbgl_callback_t                   skipCallback);
 
void nbgl_useCaseReviewStreamingContinue(const nbgl_contentTagValueList_t *tagValueList,
                                         nbgl_choiceCallback_t             choiceCallback);
 
void nbgl_useCaseReviewStreamingFinish(const char           *finishTitle,
                                       nbgl_choiceCallback_t choiceCallback);
 
void nbgl_useCaseGenericReview(const nbgl_genericContents_t *contents,
                               const char                   *rejectText,
                               nbgl_callback_t               rejectCallback);
 
void nbgl_useCaseGenericConfiguration(const char                   *title,
                                      uint8_t                       initPage,
                                      const nbgl_genericContents_t *contents,
                                      nbgl_callback_t               quitCallback);
 
void nbgl_useCaseGenericSettings(const char                   *appName,
                                 uint8_t                       initPage,
                                 const nbgl_genericContents_t *settingContents,
                                 const nbgl_contentInfoList_t *infosList,
                                 nbgl_callback_t               quitCallback);
 
void nbgl_useCaseChoice(const nbgl_icon_details_t *icon,
                        const char                *message,
                        const char                *subMessage,
                        const char                *confirmText,
                        const char                *rejectString,
                        nbgl_choiceCallback_t      callback);
void nbgl_useCaseChoiceWithDetails(const nbgl_icon_details_t *icon,
                                   const char                *message,
                                   const char                *subMessage,
                                   const char                *confirmText,
                                   const char                *cancelText,
                                   nbgl_warningDetails_t     *details,
                                   nbgl_choiceCallback_t      callback);
void nbgl_useCaseStatus(const char *message, bool isSuccess, nbgl_callback_t quitCallback);
 
void nbgl_useCaseConfirm(const char     *message,
                         const char     *subMessage,
                         const char     *confirmText,
                         const char     *rejectText,
                         nbgl_callback_t callback);
 
void nbgl_useCaseAction(const nbgl_icon_details_t *icon,
                        const char                *message,
                        const char                *actionText,
                        nbgl_callback_t            callback);
 
void nbgl_useCaseSpinner(const char *text);
 
void nbgl_useCaseNavigableContent(const char                *title,
                                  uint8_t                    initPage,
                                  uint8_t                    nbPages,
                                  nbgl_callback_t            quitCallback,
                                  nbgl_navCallback_t         navCallback,
                                  nbgl_layoutTouchCallback_t controlsCallback);
 
// utils
uint8_t nbgl_useCaseGetNbTagValuesInPage(uint8_t                           nbPairs,
                                         const nbgl_contentTagValueList_t *tagValueList,
                                         uint8_t                           startIndex,
                                         bool                             *requireSpecificDisplay);
uint8_t nbgl_useCaseGetNbTagValuesInPageExt(uint8_t                           nbPairs,
                                            const nbgl_contentTagValueList_t *tagValueList,
                                            uint8_t                           startIndex,
                                            bool                              isSkippable,
                                            bool *requireSpecificDisplay);
uint8_t nbgl_useCaseGetNbInfosInPage(uint8_t                       nbInfos,
                                     const nbgl_contentInfoList_t *infosList,
                                     uint8_t                       startIndex,
                                     bool                          withNav);
uint8_t nbgl_useCaseGetNbSwitchesInPage(uint8_t                           nbSwitches,
                                        const nbgl_contentSwitchesList_t *switchesList,
                                        uint8_t                           startIndex,
                                        bool                              withNav);
uint8_t nbgl_useCaseGetNbBarsInPage(uint8_t                       nbBars,
                                    const nbgl_contentBarsList_t *barsList,
                                    uint8_t                       startIndex,
                                    bool                          withNav);
uint8_t nbgl_useCaseGetNbChoicesInPage(uint8_t                          nbChoices,
                                       const nbgl_contentRadioChoice_t *choicesList,
                                       uint8_t                          startIndex,
                                       bool                             withNav);
uint8_t nbgl_useCaseGetNbPagesForTagValueList(const nbgl_contentTagValueList_t *tagValueList);
 
#ifdef NBGL_KEYPAD
void nbgl_useCaseKeypad(const char             *title,
                        uint8_t                 minDigits,
                        uint8_t                 maxDigits,
                        bool                    shuffled,
                        bool                    hidden,
                        nbgl_pinValidCallback_t validatePinCallback,
                        nbgl_callback_t         backCallback);
#endif  // NBGL_KEYPAD
 
#ifdef NBGL_KEYBOARD
void nbgl_useCaseKeyboard(const nbgl_keyboardParams_t *params, nbgl_callback_t backCallback);
#endif  // NBGL_KEYBOARD
 
#ifdef HAVE_SE_TOUCH
// use case drawing
DEPRECATED void nbgl_useCaseHome(const char                *appName,
                                 const nbgl_icon_details_t *appIcon,
                                 const char                *tagline,
                                 bool                       withSettings,
                                 nbgl_callback_t            topRightCallback,
                                 nbgl_callback_t            quitCallback);
DEPRECATED void nbgl_useCaseHomeExt(const char                *appName,
                                    const nbgl_icon_details_t *appIcon,
                                    const char                *tagline,
                                    bool                       withSettings,
                                    const char                *actionButtonText,
                                    nbgl_callback_t            actionCallback,
                                    nbgl_callback_t            topRightCallback,
                                    nbgl_callback_t            quitCallback);
DEPRECATED void nbgl_useCaseSettings(const char                *settingsTitle,
                                     uint8_t                    initPage,
                                     uint8_t                    nbPages,
                                     bool                       touchableTitle,
                                     nbgl_callback_t            quitCallback,
                                     nbgl_navCallback_t         navCallback,
                                     nbgl_layoutTouchCallback_t controlsCallback);
void            nbgl_useCaseReviewStart(const nbgl_icon_details_t *icon,
                                        const char                *reviewTitle,
                                        const char                *reviewSubTitle,
                                        const char                *rejectText,
                                        nbgl_callback_t            continueCallback,
                                        nbgl_callback_t            rejectCallback);
DEPRECATED void nbgl_useCaseRegularReview(uint8_t                    initPage,
                                          uint8_t                    nbPages,
                                          const char                *rejectText,
                                          nbgl_layoutTouchCallback_t buttonCallback,
                                          nbgl_navCallback_t         navCallback,
                                          nbgl_choiceCallback_t      choiceCallback);
void            nbgl_useCaseStaticReview(const nbgl_contentTagValueList_t *tagValueList,
                                         const nbgl_pageInfoLongPress_t   *infoLongPress,
                                         const char                       *rejectText,
                                         nbgl_choiceCallback_t             callback);
void            nbgl_useCaseStaticReviewLight(const nbgl_contentTagValueList_t *tagValueList,
                                              const nbgl_pageInfoLongPress_t   *infoLongPress,
                                              const char                       *rejectText,
                                              nbgl_choiceCallback_t             callback);
 
DEPRECATED void nbgl_useCaseAddressConfirmationExt(const char                       *address,
                                                   nbgl_choiceCallback_t             callback,
                                                   const nbgl_contentTagValueList_t *tagValueList);
#define nbgl_useCaseAddressConfirmation(__address, __callback) \
    nbgl_useCaseAddressConfirmationExt(__address, __callback, NULL)
#endif  // HAVE_SE_TOUCH
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* NBGL_USE_CASE_H */