# 8. Licenza e modalità demo #

← FAQ e risoluzione dei problemi · Sommario

PBToolboxAI è una libreria commerciale. Il controllo della licenza è interamente offline: nessuna connessione, nessuna attivazione, nessuna chiamata a un server. Una chiave firmata viene impostata all'avvio, la DLL la verifica localmente.

## 8.1 I tre tipi di chiavi #

Le chiavi sono cumulabili: chiami `PBT_SetLicense` tutte le volte che serve, la libreria conserva una chiave per tipo.

Tipo | Titolare | Sblocca
--- | --- | ---
`dev` | Nominativa, un solo sviluppatore | Solo nell'IDE PowerBuilder
`runtime` | La Sua società, incorporata nell'applicazione consegnata | Solo in un eseguibile compilato
`demo` | Fornita con l'applicazione dimostrativa | L'applicazione dimostrativa, nell'IDE, fino alla scadenza

Un progetto ha quindi bisogno di entrambe: una postazione `dev` per ogni sviluppatore e una chiave `runtime` per l'applicazione consegnata ai Suoi clienti.

- Una chiave `dev` che finisse in un eseguibile non sblocca nulla.
- Una chiave `runtime` non concede alcuna postazione di sviluppo.
- I Suoi clienti finali non devono inserire nulla, non devono attivare nulla: la chiave `runtime` è nel Suo codice.

> Il rilevamento « IDE o eseguibile » è effettuato dalla DLL stessa (nome del processo, moduli design-time caricati), non da codice PowerBuilder — non può essere aggirato dai Suoi sorgenti.

## 8.2 Impostare la chiave #

Una sola cosa da fare, prima dell'apertura della prima finestra:

    // Dichiarazione - oggetto applicazione, "Local External Functions"
    Function long PBT_SetLicense (string as_client, string as_key) Library "pbtoolboxai.dll"

    // Event open dell'oggetto applicazione
    long ll_rc
    string ls_cle_dev

    // La chiave RUNTIME va nel codice : DEVE finire nell'eseguibile.
    ll_rc = PBT_SetLicense(gs_titulaire, gs_cle_runtime)

    // La chiave DEV si legge dalla postazione : sblocca solo l'IDE, e nel codice
    // finirebbe in ogni copia consegnata senza servire a nulla.
    ls_cle_dev = ProfileString("pbtoolboxai.ini", "license", "dev", "")
    if ls_cle_dev <> "" then ll_rc = PBT_SetLicense(gs_titulaire, ls_cle_dev)

    Open(w_principale)

> La chiave si posa tramite la funzione della DLL, mai tramite un metodo di componente: vale per l'intero processo e va posata prima che esista qualsiasi componente. È per la stessa ragione che `PBT_LicenseStatus` non chiede alcun handle.

Il titolare viene passato in chiaro, come primo argomento: è il nome (o l'indirizzo e-mail) a cui la licenza è stata intestata e deve corrispondere a quello contenuto nella chiave firmata. Una chiave non può quindi circolare senza il nome di chi l'ha acquistata.

Ritorno | Significato
--- | ---
`0` | Chiave valida e conservata
`-1` | Formato di chiave non valido
`-2` | Firma non valida (chiave alterata o estranea)
`-3` | Manutenzione scaduta per questa versione della libreria (vedere 8.5)
`-4` | Chiave `demo` scaduta
`-5` | Il titolare indicato non corrisponde a quello della chiave

> 💡 Quale chiave va dove. La chiave `runtime` appartiene al codice: deve finire nell'eseguibile che consegnate. La chiave `dev` no — sblocca solo l'IDE, quindi in un eseguibile è inutile pur continuando a circolare, con il nome della vostra società. Il suo posto è un file `pbtoolboxai.ini` accanto all'IDE, o un valore nel registro.

Impostare la chiave dopo la creazione di un componente funziona ugualmente: i componenti già aperti si sbloccano immediatamente. Ma la soluzione più semplice resta l'event `open` dell'applicazione.

> 💡 Conservi la chiave in una costante o in una risorsa della Sua applicazione. È firmata: non contiene alcun segreto sfruttabile e non può essere modificata senza invalidarne la firma.

## 8.3 Verificare lo stato della licenza #

    // Dichiarazione
    Function long PBT_LicenseStatus (ref string as_json, long al_len) Library "pbtoolboxai.dll"

    string ls_statut

    ls_statut = Space(1024)
    PBT_LicenseStatus(ls_statut, 1024)
    // -> {"licensed":true,"ide":false,"keys":{...},"reason":""}

Utile in fase di integrazione per verificare che una chiave sia effettivamente presa in considerazione, oppure per tracciare un avvio nel Suo registro applicativo.

## 8.4 La modalità demo #

Senza una chiave valida — o con una chiave che non si applica al contesto (una chiave `dev` in un exe, per esempio) — la libreria funziona in modalità demo: tutto è utilizzabile, tutto è visibile, ma con dei limiti — tranne i quattro componenti dell'edizione community, descritti qui sotto, che non sono mai limitati.

### Quattro componenti restano gratuiti #

L'edizione community non richiede nulla: senza alcuna chiave, quattro componenti funzionano senza badge e senza limiti, a tempo indeterminato.

Componente | Che cosa porta
--- | ---
statictext | Etichetta con marcatura: grassetto, colori, collegamenti, elenchi, blocchi richiudibili
messagebox | Finestra di dialogo modale a tema, con pulsanti liberi
toaster | Notifiche nell'angolo dello schermo, con titolo, immagine e azioni
webbrowser | Browser WebView2 ospitato in una finestra PowerBuilder

La scelta è voluta: sono i quattro che si incontrano per primi, non portano alcun modello di dati proprio e bastano a dimostrare su una postazione bloccata che il runtime si distribuisce — il vero ostacolo prima di ogni acquisto.

L'elenco vive nella DLL. `PBT_LicenseStatus` lo restituisce tale e quale, in `"free"`: la vostra applicazione può quindi annunciare a che cosa ha diritto senza chiave, invece di scoprirlo componente per componente.

Una chiave valida prevale sempre: su questi quattro componenti come sugli altri, ripristina il vostro nome e la vostra edizione.

### Il badge #

Ogni componente mostra un badge « PBToolboxAI — DEMO », non nascondibile.

### I limiti funzionali #

Componente | Limite in modalità demo
--- | ---
tab | 3 pagine al massimo
ribbon | 2 schede al massimo
toolbar | 6 item visualizzati, su tutte le barre
tilesbox | 8 riquadri visualizzati
Tutti gli altri | Solo il badge — nessun limite funzionale

Questi limiti si applicano al rendering: nulla fallisce, la visualizzazione è troncata. Può quindi valutare davvero ogni componente, sui Suoi dati, prima di acquistare.

Impostare una chiave valida rimuove istantaneamente tutti questi limiti e toglie il badge, senza riavviare l'applicazione.

## 8.5 Perpetua + manutenzione #

La licenza è perpetua: le versioni coperte dal Suo periodo di manutenzione funzionano per sempre, anche dopo la scadenza dello stesso.

In concreto, la chiave porta una data di fine manutenzione, confrontata con la data di compilazione della DLL:

- una versione della libreria pubblicata durante la Sua manutenzione è sbloccata definitivamente;
- una versione pubblicata dopo la scadenza restituisce `-3`: rinnovi la manutenzione per accedervi;
- le Sue applicazioni già consegnate non sono mai interessate: incorporano la versione che hanno sempre utilizzato.

## 8.6 Domande frequenti #

La mia chiave viene verificata online? No. Nessuna rete, mai. La verifica è una firma RSA convalidata localmente da Windows.

I miei clienti hanno bisogno di una chiave? No. La Sua chiave `runtime` è nella Sua applicazione; loro non vedono mai nulla della licenza.

Che cosa succede se dimentico `PBT_SetLicense` in produzione? L'applicazione funziona, ma ogni componente mostra il badge demo e si applicano i limiti della tabella qui sopra. È il primo punto da verificare se un badge appare presso un cliente.

Posso impostare una chiave `dev` e una chiave `runtime` nello stesso codice? Sì — è anzi il caso più comune: la `dev` serve quando esegue dall'IDE, la `runtime` quando esegue l'exe. Ciascuna viene ignorata nell'altro contesto.

Il badge appare anche se la chiave è impostata. Tre cause, in ordine di frequenza: (1) chiave `dev` mentre esegue un exe compilato, o il contrario; (2) valore restituito da `PBT_SetLicense` non verificato — controlli che sia `0`; (3) manutenzione scaduta per la versione di DLL installata (ritorno `-3`). `PBT_LicenseStatus` risolve il dubbio in una riga.

Una chiave è nominativa. Una chiave `dev` è legata a uno sviluppatore, una chiave `runtime` alla Sua società. Non le condivida fuori dal Suo team.

← FAQ e risoluzione dei problemi · Sommario