Add-ons

Declaré dans: be/translation/TranslatorAddOn.h

Librairie: libtranslation.so

Cette section décrit les fonctions et les données qu'un add-on de conversion doit ( ou peut) alimenter. Les Add-on de conversion que vous créez et installez sont chargés dans un objet BTranslatorRoster au travers de ses fonctions Default() ou AddTranslators().

Vous compilez votre add-on comme une librairie partagée liée avec libtranslation.so, et installez le fichier de l'objet add-on dans le sous-répertoire Translators de B_USER_ADDONS_DIRECTORY.

Le tableau ci-dessous liste brièvement les symboles des add-on de conversion :

Symbole	Nécessaire?	Description
translatorInfo	oui	Description longue du convertisseur
translatorName	oui	Nom court du convertisseur
translatorVersion	oui	Numéro de version du convertisseur
Identify()	oui	Identifie les données dans un objet BPositionIO
Translate()	oui	Convertie les données d'un format vers un autre
inputFormats	non	Liste des formats d'entrée supportés
outputFormats	non	Liste des formats de sortie supportés
GetConfigMessage()	non	Sauvegarde la configuration courante dans un BMessage
MakeConfig()	non	Crée une vue pour la configuration utilisateur du convertisseur

Fonctions Add-on

GetConfigMessage()

	status_t GetConfigMessage(BMessage *ioExtension)

Optionnelle

Cette fonction stoke la configuration courante dans la classe ioExtension de telle manière qu'elle puisse être compressée,décompressée, et puis passée en paramètre de Translate() comme un objet ioExtension.

Identify()

	status_t Identify(BPositionIO *inSource,       const translation_format *inFormat,       BMessage *ioExtension,       translator_info *outInfo,       uint32 outType)

Nécessaire

Si le convertisseur comprend comment convertir les données dans inSource vers un support de type outType, il rempli outInfo avec les détails du format d'entrée et retourne B_OK. S'il ne sait pas comment effectuer la conversion des données, il retourne B_NO_TRANSLATOR.

Les champs quality et capability dans outInfo sont utilisés par le kit de conversion pour sélectionner les meilleurs convertisseurs pour une conversion donnée, donc il vaut mieux être prudent en choisissant ces valeurs.

Si le format du média n'a pas un code de type dans <be/support/TypeConstants.h> ( comme c'est le plus souvent le cas), choisisez des valeurs raisonnables. Par exemple, le convertisseur Targa inclus dans la distribution BEOS utilise le code 'TGA'.

Le convertisseur ne doit pas remplir le champs translator dans outInfo; BTranslatorRoster rempli cette valeur pour vous.

Rappellez-vous que inSource peut être de n'importe quelle source, incluant une entrée réseau. Il est par conséquent plus prudent d'utiliser des appels comme BPositionIO::Size() qui force toutes les données en dehors du flux. De la même façon , il est préférable de lire autant de flux de données que ncessaire.

inFormat, s'il n'est pas NULL, est fourni comme source de préférence de la donnée dans inSource. Comme ce n'est qu'un conseil, la donnée peut être d'un tout autre format.

ioExtension, s'il n'est pas NULL, contient une information supplémentaire sur l'add-on. Il est décrit plus en détail dans la section BTranslatorRoster intitulée "Configuration".

outType peut être 0, dans ce cas n'importe quel format de sortie est acceptable.

MakeConfig()

	status_t MakeConfig(BMessage *ioExtension,       BView **outView,       BRect *outExtent)

Optionnelle

Cette fonction crée un nouvel objet BView au travers duquel l'utilisateur configure l'add-on. Par exemple, il peut être utilisé pour contrôler le degré de compression de l'image utilisée ou la fréquence de la vidéo. Les limites de la vue sont retournées dans outExtent, bien qu'elles puissent être retaillées par une source extérieure. Les changements de la configuration prennent effet immédiatement, bien que des conversions soient en cours avec ces mêmes paramètres.

Translate()

	status_t Translate(BPositionIO *inSource,       const translator_info *inInfo,       BMessage *ioExtension,       uint32 outType,       BPositionIO *outDestination)

Nécessaire

Les convertisseurs traduisent des données de inSource au format outType, en écrivant la sortie de la fonction dans outDestination. outType peut être 0, dans ce cas il est supposé que l'on utilise le format par défaut. Comme dans Identify(), inInfo sert comme conseil sur le format des données dans inSource. ioExtension rempli son rôle habituel comme un container d'information de configuration. La fonction retourne B_OK si elle a pu convertir les données. Si elle n'a pas été capable d'effectuer la conversion, elle retourne B_NO_TRANSLATOR ou une erreur appropriée.

Translator Add-on Data

inputFormats , outputFormats

	translation_format inputFormats[]; translation_format outputFormats[];

Optionnelles

Ces tableaux disent à BTranslatorRoster quels formats sont supportés par l'add-on. S'ils ne sont pas exportés par le convertisseur, la fonction Identify() de l'add-on sera appellée chaque fois que l'application demandera une conversion. Chaque tableau se termine par une structure vide translation_format, donc un inputFormats type aura la forme suivante :

   translation_format inputFormats[] = {
      { 'TGA ', B_TRANSLATOR_BITMAP, 0.6, 0.5, "image/targa", 
        "Targa bitmap format" },
      { B_TRANSLATOR_BITMAP, B_TRANSLATOR_BITMAP, 0.4, 0.6, "image/x-be-bitmap",
        "Be Bitmap format" },
      { 0, 0, 0, 0, 0, 0 }
   };

et de la même façon pour outputFormats.

translatorInfo , translatorName , translatorVersion

	char translatorInfo[]; char translatorName[]; int32 translatorVersion;

Nécessaires

translatorInfo retourne un pointeur au nom long du convertisseur e.g. "aiff translator by the Pie Man (pie@the.man)".

translatorName retourne un pointeur au nom court du convertisseur, e.g. "aiff translator". Le nom court peut être approprié pour l'affichage dans un menu.

translatorVersion donne un numéro de version du convertisseur sous la forme "MM.mm". Par exemple, TranslatorVersion() de 314 est interprété comme une version 3.14.