Introdução

Este documento tem o objetivo de mostrar o desenvolvimento de um plugin para o lazynds, de maneira que permita a expansão das capacidades do programa no tratamento das mais diversas compressões existentes.

Príncipio de Funcionamento

O sistema de plugins do lazynds se baseia num arquivo .plg, responsável por algumas definições do plugin, e de um arquivo .py, contendo a programação do plugin.

O chamamento das funções do plugin é feito através de decorators.

Arquivo de Definição

É um arquivo texto com a extensão plg. Ele possui os seguintes parâmetros:

Module
Prefix
Type
Name
Description
Authors
Copyright
Website

Abaixo, segue a definição de cada parâmetro:

• Module - É o nome do arquivo .py (sem extensão) que contém a programação do plugin
• Prefix - É o prefixo usado para chamar as funções do plugin
• Type - Que funções o plugin suporta. Os seguintes tipos são suportados: Compression-Only, Uncompression-Only, Full, Pointer-Only, Full+Pointer
• Compression-Only - Apenas compressão
• Uncompression-Only - Apenas descompressão
• Full - Compressão e descompressão
• Pointer-Only - Apenas atualização de ponteiro
• Full+Pointer - Compressão, descompressão e atualização de ponteiro

Os demais parâmetros são as informações do plugin que serão apresentadas ao usuário final na caixa de diálogo "Sobre"

Para evitar incompatibilidades com o GTK+, todos os valores dos parâmetros devem ser informados como strings unicode.

Programação do Plugin

Todo arquivo .py deve, obrigatoriamente, importar o módulo pluginmanager, responsável por chamar as funções do plugin.

Cada função deve ser registrada através do seguinte decorator: @pluginmanager.register("XXXX-YYYY") onde XXXX é o parâmetro Prefix, definido no arquivo .plg, e YYYY pode ter os seguintes valores:

• SCAN - Função de busca dos endereços com dados comprimidos
• COMPRESS - Função de compressão de dados
• UNCOMPRESS - Função de descompressão de dados
• POINTER - Função de atualização do ponteiro

Funções auxiliares não devem ser registradas.

Todas essas quatro funções recebem uma lista e um dicionário de argumentos (definidos, respectivamente, por args e kwargs), porém, apenas o dicionário possui argumentos válidos.

Função de Busca

Recebe os seguintes argumentos:

• kwargs["infile"] - A rom onde serão buscados os endereços com dados comprimidos. É do tipo mmap.
• kwargs["min_size"] - O limite inferior da busca. Geralmente, o menor tamanho que o arquivo descomprimido deve ter para ser válido.
• kwargs["max_size"] - O limite superior da busca. Geralmente, o maior tamanho que o arquivo descomprimido deve ter para ser válido.

Deve retornar o seguinte valor:

• Uma lista contendo tuplas. Cada tupla deve conter o seguinte par: (Endereço , Prefixo)

Função de Compressão

Recebe os seguintes argumentos:

• kwargs["infile"] - O arquivo que será comprimido. É do tipo file.

Deve retornar o seguinte valor:

• Um buffer do tipo array de caracteres (array.array("c")) contendo o arquivo comprimido.

Função de Descompressão

Recebe os seguintes argumentos:

• kwargs["infile"] - A rom onde o dado será descomprimido. É do tipo file.
• kwargs["address"] - O endereço onde se encontra o dado comprimido. É do tipo long.

Deve retornar o seguinte valor:

• Um buffer do tipo array de caracteres (array.array("c")) contendo o arquivo descomprimido.

Função de Atualização do Ponteiro

Recebe os seguintes argumentos:

• kwargs["infile"] - A rom onde o ponteiro deverá ser procurado. É do tipo file.
• kwargs["old_address"] - O endereço original do dado comprimido. É do tipo long.
• kwargs["new_address"] - O novo endereço do dado comprimido. É definido na caixa de diálogo da compressão. É do tipo long.
• kwargs["usize"] - Tamanho do dado descomprimido. É do tipo int.
• kwargs["csize"] - Tamanho do dado comprimido. É do tipo int.

Deve retornar o seguinte valor:

• Uma tupla contendo o seguinte par: (Valor a ser escrito , Endereço onde será escrito).

O valor a ser escrito geralmente é o novo ponteiro. Ele, obrigatoriamente, deve estar no formato de string. É recomendado usar o módulo struct para fazer as conversões. O endereço onde o novo ponteiro será escrito deve ser absoluto.

É importante notar que nenhuma das funções deve fazer modificações na ROM original, deixando isso a cargo do lazynds.

Exemplos

Estão disponíveis, junto com o lazynds, três plugins de exemplos. É recomendado usá-los para ilustrar as informações dispostas nessa documentação.