# 8. Licença e modo de demonstração #

← FAQ e resolução de problemas · Índice

O PBToolboxAI é uma biblioteca comercial. O controlo da licença é totalmente offline: sem ligação, sem ativação, sem chamada a servidor. Uma chave assinada é atribuída no arranque e a DLL verifica-a localmente.

## 8.1 Os três tipos de chaves #

As chaves são cumuláveis: `PBT_SetLicense` pode ser chamada as vezes necessárias, uma vez que a biblioteca retém uma chave por tipo.

Tipo | Titular | Desbloqueia
--- | --- | ---
`dev` | Nominativa, um programador | Apenas no IDE do PowerBuilder
`runtime` | A sua empresa, incorporada na aplicação entregue | Apenas num executável compilado
`demo` | Fornecida com a aplicação de demonstração | A aplicação de demonstração, no IDE, até à expiração

Um projeto necessita, portanto, de ambas: um posto `dev` por programador e uma chave `runtime` para a aplicação entregue aos seus clientes.

- Uma chave `dev` que acabe por ficar num executável não desbloqueia nada.
- Uma chave `runtime` não confere qualquer posto de desenvolvimento.
- Os clientes finais não têm nada a introduzir nem a ativar: a chave `runtime` está no seu código.

> A deteção «IDE ou executável» é efetuada pela própria DLL (nome do processo, módulos de design-time carregados), e não por código PowerBuilder — não pode ser contornada a partir das suas fontes.

## 8.2 Atribuir a chave #

Há apenas uma coisa a fazer, antes da abertura da primeira window:

    // Declaracao - objeto application, "Local External Functions"
    Function long PBT_SetLicense (string as_client, string as_key) Library "pbtoolboxai.dll"

    // Event open do objeto application
    long ll_rc
    string ls_cle_dev

    // A chave RUNTIME vai no codigo : TEM de ficar dentro do executavel.
    ll_rc = PBT_SetLicense(gs_titulaire, gs_cle_runtime)

    // A chave DEV le-se do posto : so desbloqueia o IDE, e no codigo iria em
    // cada copia entregue sem ali servir para nada.
    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)

> A chave é definida através da função da DLL, nunca através de um método de componente: aplica-se a todo o processo e tem de ser definida antes de existir qualquer componente. É pela mesma razão que `PBT_LicenseStatus` não pede qualquer handle.

O titular é passado em claro, como primeiro argumento: é o nome (ou endereço de e-mail) em que a licença foi emitida e tem de corresponder ao que a chave assinada contém. Assim, uma chave não pode circular sem o nome de quem a comprou.

Retorno | Significado
--- | ---
`0` | Chave válida e retida
`-1` | Formato de chave inválido
`-2` | Assinatura inválida (chave alterada ou externa)
`-3` | Manutenção expirada para esta versão da biblioteca (ver 8.5)
`-4` | Chave `demo` expirada
`-5` | O titular indicado não corresponde ao da chave

> 💡 Que chave vai onde. A chave `runtime` pertence ao código: tem de ficar dentro do executável que entrega. A chave `dev` não — só desbloqueia o IDE, por isso dentro de um executável não serve para nada e mesmo assim circula, com o nome da sua empresa. O seu lugar é um ficheiro `pbtoolboxai.ini` junto ao IDE, ou um valor no registo.

Atribuir a chave depois da criação de um componente também funciona: os componentes já abertos são desbloqueados de imediato. Contudo, o mais simples continua a ser o event `open` da aplicação.

> 💡 A chave deve ser conservada numa constante ou num recurso da aplicação. É assinada: não contém qualquer segredo explorável e não pode ser modificada sem invalidar a respetiva assinatura.

## 8.3 Verificar o estado da licença #

    // Declaracao
    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":""}

Útil na fase de integração para verificar se uma chave é efetivamente tida em conta, ou para registar um arranque no registo aplicacional.

## 8.4 O modo de demonstração #

Sem chave válida — ou com uma chave que não se aplica ao contexto (uma chave `dev` num exe, por exemplo) — a biblioteca funciona em modo de demonstração: tudo é utilizável, tudo é visível, mas com limites — exceto os quatro componentes da edição comunidade, descritos logo abaixo, que nunca são limitados.

### Quatro componentes continuam gratuitos #

A edição comunidade não exige nada: sem qualquer chave, quatro componentes funcionam sem emblema e sem limite, por tempo indeterminado.

Componente | O que traz
--- | ---
statictext | Etiqueta com marcação: negrito, cores, ligações, marcas, blocos dobráveis
messagebox | Caixa de diálogo modal com tema e botões livres
toaster | Notificações ao canto do ecrã, com título, imagem e ações
webbrowser | Navegador WebView2 alojado numa janela PowerBuilder

A escolha é deliberada: são os quatro com que se depara primeiro, não trazem qualquer modelo de dados próprio e bastam para provar num posto bloqueado que o runtime se instala — o verdadeiro obstáculo antes de qualquer compra.

A lista vive na DLL. `PBT_LicenseStatus` devolve-a tal como está, em `"free"`: a sua aplicação pode então anunciar a que tem direito sem chave, em vez de o descobrir componente a componente.

Uma chave válida prevalece sempre: nesses quatro componentes como nos outros, repõe o seu nome e a sua edição.

### O emblema #

Cada componente apresenta um emblema «PBToolboxAI — DEMO», que não pode ser ocultado.

### Os limites funcionais #

Componente | Limite em modo de demonstração
--- | ---
tab | 3 páginas no máximo
ribbon | 2 separadores no máximo
toolbar | 6 items apresentados, no conjunto de todas as barras
tilesbox | 8 mosaicos apresentados
Todos os restantes | Apenas o emblema — nenhum limite funcional

Estes limites aplicam-se à apresentação: nada falha, a apresentação é truncada. É assim possível avaliar realmente cada componente, com os seus dados, antes da compra.

Atribuir uma chave válida levanta instantaneamente todos estes limites e retira o emblema, sem reiniciar a aplicação.

## 8.5 Perpétua + manutenção #

A licença é perpétua: as versões abrangidas pelo seu período de manutenção funcionam para sempre, inclusivamente após a expiração deste.

Na prática, a chave contém uma data de fim de manutenção, comparada com a data de compilação da DLL:

- uma versão da biblioteca publicada durante a sua manutenção fica desbloqueada definitivamente;
- uma versão publicada após a expiração devolve `-3`: é necessário renovar a manutenção para lhe aceder;
- as aplicações já entregues nunca são afetadas: incorporam a versão que sempre utilizaram.

## 8.6 Perguntas frequentes #

A minha chave é verificada online? Não. Nunca há rede. A verificação é uma assinatura RSA validada localmente pelo Windows.

Os meus clientes precisam de uma chave? Não. A sua chave `runtime` está na sua aplicação; eles nunca veem nada relativo à licença.

O que acontece se me esquecer de `PBT_SetLicense` em produção? A aplicação funciona, mas cada componente apresenta o emblema de demonstração e aplicam-se os limites da tabela acima. É o primeiro ponto a verificar se aparecer um emblema num cliente.

Posso atribuir uma chave `dev` e uma chave `runtime` no mesmo código? Sim — é aliás o caso habitual: a `dev` serve para a execução a partir do IDE, a `runtime` para a execução do exe. Cada uma é ignorada no outro contexto.

O emblema aparece embora a chave esteja atribuída. Três causas, por ordem de frequência: (1) chave `dev` quando se está a executar um exe compilado, ou o inverso; (2) retorno de `PBT_SetLicense` não testado — verificar se é igual a `0`; (3) manutenção expirada para a versão de DLL instalada (retorno `-3`). `PBT_LicenseStatus` esclarece a situação numa linha.

Uma chave é nominativa. Uma chave `dev` está associada a um programador, uma chave `runtime` à sua empresa. Não devem ser partilhadas fora da sua equipa.

← FAQ e resolução de problemas · Índice