| Table des matières du kit de conversion | Index du kit de conversion |
Dérivée de : BArchivable
Déclarée dans: be/translation/TranslatorRoster.h
Librairie: libtranslation.so
BTranslatorRoster est le mécanisme principal au travers duquel les applications ont une action réciproque avec le kit de conversion. Une application utilisant le kit de conversion n'a pas à se soucier du chargement ou de l'appel d'add-on; BTranslatorRoster manie de manière transparente tous les détails insignifiants. La classe fournit 4 catégories de services: initialisation, information, conversion, et configuration.
Vous pouvez créer un objet vide BTranslatorRoster (qui n'a pas de convertisseur chargé) en l'instanciant de manière usuelle:
BTranslatorRoster *roster = new BTranslatorRoster;
Vous pouvez alors charger les convertisseurs sur le nouvel objet BTranslatorRoster créé avec la méthode AddTranslators() (tous les chemins doivent être absolus):
// Charge tous les convertisseurs d'un répertoire donné
roster->AddTranslators("/boot/home/config/add-ons/viewer/");
// Charge un convertisseur particulier
roster->AddTranslators("/system/add-ons/Translators/photos");
Plus généralement vous voudrez un objetBTranslatorRoster avec les convertisseurs par défaut (qui sont dans /boot/home/config/add-ons/Translators, /boot/home/config/add-ons/Datatypes, et /system/add-ons/Translators). la méthode Default() les retourne bêtement;
BTranslatorRoster *roster = BTranslatorRoster::Default();
Cependant, tous les objets BTranslatorRosters ne sont pas créés de la même façon: l'objet retourné par Default() est global à l'application et est contrôlé par l'objet BTranslatorRoster. Ce qui a pour résultat que vous ne pouvez jamais le supprimer. De même, si vous voulez charger des convertisseurs supplémentaires, vous feriez mieux de créer une nouvelle instance de l'objet BTranslatorRoster plutôt que d'utiliser celui par défaut:
BTranslatorRoster *roster = new BTranslatorRoster; roster->AddTranslators(NULL); // charge les convertisseurs par défaut roster->AddTranslators(...); // charge les convertisseurs supplémentaires
Typiquement les applications demandent les questions suivantes au kit de conversion:
1. Quels convertisseurs sont installés ?
2. Quelles conversions peut exécuter un convertisseur spécial?
3. Quel est le convertisseur le mieux adapté pour effectuer la conversion ?
Une application peut déterminer les convertisseurs installés en appellant GetAllTranslators(). GetAllTranslators() retourne un tableau de valeurs translator_id des convertisseurs installés. Un translator_id est une valeur (application-wide) fixée par l'objet BTranslatorRoster identifiant un convertisseur précis. Le code suivant imprime les noms des convertisseurs par défaut :
BTranslatorRoster *roster = BTranslatorRoster::Default();
int32 num_translators, i;
translator_id *translators;
const char *translator_name, *translator_info;
int32 translator_version;
roster->GetAllTranslators(&translators, &num_translators);
for (i=0;i<num_translators;i++) {
roster->GetTranslatorInfo(translators[i], &translator_name,
&translator_info, &translator_version);
printf("%s: %s (%.2f)n", translator_name, translator_info,
translator_version/100.);
}
delete [] translators; // nettoyage
Le translator_id est trés important; il peut être utilisé pour questionner l'objet BTranslatorRoster pour des informations précises sur les capacités d'un convertisseur. Cette information provient de 2 structures presque équivalentes : translation_format and translator_info. Elles sont définies dans <be/translation/TranslationDefs.h>:
struct
translation_format
{
uint32 type;
uint32 group;
float quality;
float capability;
char MIME[251];
char name[251];
}
struct
translator_info
{
uint32 type;
translator_id translator;
uint32 group;
float quality;
float capability;
char name[251];
char MIME[251];
}
Champs communs :
De plus, la structure translator_info définie un champs supplémentaire:
Pour trouver les formats supportés par un convertisseur particulier, appellez GetInputFormats() ou GetOutputFormats() de manière appropriée. Ces méthodes retournent une liste de formats supportés en entrée ou en sortie dans un tableau de type translation_format.
De nombreuses fois, cependant, vous ne vous intéresserez pas à un convertisseur en particulier; vous voudrez juste avoir le convertisseur le plus adapté pour manier votre flux de données. Dans ces cas, vous pourrez juste appeler Identify() sur l'objet BPositionIO. BTranslatorRoster retournera alors, dans la structure translator_info, le convertisseur le plus adapté pour effectuer la conversion. Si vous êtes intéresé pour trouver tous les convertisseurs capables de manier les données dans votre flux, utilisez plutôt GetTranslators().
Notez que certains convertisseurs ne publient pas leur format d'entrée et de sortie. Dans ces cas , GetInputFormats() et GetOutputFormats() retournent une liste de formats vides. La seule façon de dire si un convertisseur supporte un format d'entrée ou de sortie particulier, est de le passer à Identify().
Bien que le but de BTranslatorRoster est de fournir des services de conversion, effectuer des conversions est simple. tout ce qu'il demande sont des flux d'entrée et de sortie BPositionIO et la constante de type pour la sortie désirée. Dans un cas simple, si vous connaissez la constante de type dans laquelle vous souhaitez convertir vos données, vous pouvez laissez BTranslatorRoster décider quel convertisseur utiliser:
BPositionIO *in = ..., *out = ...; BTranslatorRoster *roster = BTranslatorRoster::Default(); uint32 desired_format_constant = ...; roster->Translate(in, NULL, NULL, out, desired_format_constant);
Parfois,cependant, vous désirerez utiliser un convertisseur spécial. Dans ces cas là, vous pourrez utiliser une forme alternative de Translate():
BPositionIO *in = ..., *out = ...; BTranslatorRoster *roster = BTranslatorRoster::Default(); uint32 desired_format_constant = ...; translator_id desired_translator_id = ...; roster->Translate(desired_translator_id, in, NULL, NULL, out, desired_format_constant);
|
BTranslatorRoster fournit deux méchanismes pour configurer le comportement des convertisseurs : ioExtension et MakeConfiguationView().
ioExtension est un BMessage qui peut être passé à la plupart des membres de BTranslatorRoster. Il est utilisé par l'application pour communiquer des informations de format spécial au convertisseur. Par exemple, il peut être utilisé pour demander à un convertisseur vidéo de convertir seulement les 15 premières images d'un film. Le champs ioExtension est aussi utilisé par le convertisseur pour renvoyer des informations à l'application. Le convertisseur peut l'utiliser, par exemple pour dire à l'application qu'il retourne une image noir et blanc.
Un convertisseur ne doit pas supporter une extension particulière et il n'y a pas de moyen pour une application de dire si un convertisseur ne supporte aucune extension.
Une collection de messages standards ioExtension peut être trouvée dans <be/translation/TranslatorFormats.h> et ils ont expliqués ci-dessous:
| Nom | Type | Direction | Description |
|---|---|---|---|
| B_TRANSLATOR_EX T_HEADER_ONLY | bool | app vers convertisseur | Seulement en-tête de sortie si vrai (true) |
| B_TRANSLATOR_EX T_DATA_ONLY | bool | app vers convertisseur | Seulement données de sortie si vrai (true) |
| B_TRANSLATOR_EX T_COMMENT | string | n/a | Commentaires sur les données. |
| B_TRANSLATOR_EX T_TIME | bigtime_t | app vers convertisseur | S'il en existe un, il spécifie un instant dans le temps. Si 2 existent, ils spécifient une echelle de temps. Le temps est mesuré en microseconde. |
| B_TRANSLATOR_EX T_FRAME | uint32 | app vers convertisseur | Idem kTimeExtension, excepté que l'unité de temps est "frames". |
| B_TRANSLATOR_EX T_BITMAP_RECT | BRect | app vers convertisseur | Spécifie la sous-section d'une image. |
| B_TRANSLATOR_EX T_BITMAP_COLOR_SPACE | uint32 | Bidirectionnel | Spécifie la couleur désirée/ actuelle d'une image. |
| B_TRANSLATOR_EX T_SOUND_CHANNEL | uint32 | app vers convertisseur | seulement les canaux spécifiés d'un son. |
| B_TRANSLATOR_EX T_SOUND_MONO | bool | app vers convertisseur | Mixte tous les canaux audios dans un seul si vrai (true). |
| B_TRANSLATOR_EX T_SOUND_MARKER | uint32 | Bidirectionnel | Spécifie des signets dans un son. Les unités sont en "Frame". "1" spécifit la séparation entre le premier échantillon du dernier canal et le second échantillon du premier canal. |
| B_TRANSLATOR_EX T_SOUND_LOOP | uint32 | Bidirectionnel | S'il y a une valeur, bouclage de la fin de l'échantillon vers le point de bouclage. s'il y a deux valeurs, bouclage de la seconde valeur vers la première. S'il y a plus de deux valeurs, alors il y a une émission de boucles. |
L'objet BTranslatorRoster contient deux méthodes pour faciliter la configuration des convertisseurs. La première méthode, MakeConfigurationView(), charge le convertisseur de créer un objet BView dans lequel les options de configurations pourront être changées. L'application est responsable de l'appel de MakeConfigurationView() pour attacher la vue à un objet BWindow. La seconde méthode, GetConfigurationMessage(), remplit un objet BMessage avec la configuration courante pour un convertisseur particulier. Ce BMessage peut être alors passé à Translate() pour demander une conversion avec la configuration contenue dans cet objet.
La tâche de convertir des données revient souvent à trouver le bon type de constante. La fonction suivante va imprimer le type de constante associée avec une chaine de type MIME donnée par l'objet BTranslatorRoster:
void find_constant(BTranslatorRoster *roster, const char *mime)
{
translator_id *translators;
int32 num_translators;
roster->GetAllTranslators(&translators, &num_translators);
for (int32 i=0;i<num_translators;i++) {
const translation_format *fmts;
int32 num_fmts;
roster->GetOutputFormats(translators[i], &fmts, &num_fmts);
for (int32 j=0;j<num_fmts;j++) {
if (!strcasecmp(fmts[j].MIME, mime))
printf("match: %s type %8.8x (%4.4s)n",
fmts[j].name, fmts[j].type, &fmts[j].type);
}
}
}
|
Crée une nouveau container pour les conversions. Le constructeur sans paramètre crée un container vide. Le constructeur de BMessage charge tous les convertisseurs d'un répertoire spécifié dans les champs "chemin" "be:translator_path" dans model.
Si vous souhaitez seulement charger le convertisseur des répertoires standards, vous pouvez plutôt utiliser la fonction statique Default() décrite ci-dessous.
Voir également: Default() fonction statique, AddTranslators()
|
Décharge tous les convertisseurs qui ont été chargés et libère toute la mémoire allouée par l'objet BTranslatorRoster.
|
Elle retourne un objet BTranslatorRoster chargé avec les convertisseurs par défaut, chargé dans la limite des fichiers et des répertoires correspondant à la variable d'environnement TRANSLATORS. Si une telle variable n'existe pas, les convertisseurs sont chargés depuis les localisations par défaut /boot/home/config/add-ons/Translators, /boot/home/config/add-ons/Datatypes, et /system/add-ons/Translators.
L'instance de BTranslatorRoster retournée par cette fonction est globale à l'application et ne pourra pas être supprimée. Bien que vous puissiez rajouter des convertisseurs à l'objet BTranslatorRoster retourné, cela n'est pas recommandé. il est mieux d'utiliser une nouvelle instance de cette classe.
Voir également: AddTranslators()
|
Retourne un nouvel objet BTranslatorRoster, alloué par new et créé avec le constructeur qui prends un BMessage archive. Cependant, si archive ne contient pas de données sur l'objet BTranslatorRoster , ,Instantiate() retourne NULL.
Voir également: BArchivable::Instantiate(), instantiate_object(), Archive()
|
Positionne outCurVersion au numéro de version du protocole du kit de conversion et outMinVersion au numéro de version minimum de protocole supporté. Retourne une chaêne de caractères faciles à lire contenant des informations sur la version. Actuellement , inAppVersion doit être égal à B_TRANSLATION_CURRENT_VERSION.
|
Charge tous les convertisseurs dans la limite des fichiers et des répertoires trouvés dans load_path. Tous les chemins spécifiés doivent être absolus. Si load_path est NULL, elle charge les convertisseurs à partir des localisations spécifiées dans la variable d'environnement TRANSLATORS. Si la variable d'environnement n'est pas définie, alors elle charge tous les fichiers depuis les répertoires par défaut /boot/home/config/add-ons/Translators, /boot/home/config/add-ons/Datatypes, et /system/add-ons/Translators.
CODES DE RETOUR
. Identification de inSource est réussie.
Voir également: Default() fonction statique
|
Archive l'objet BTranslatorRoster en enregistrant ces add-ons dans BMessage into.
Voir également: BArchivable::Archive(), Instantiate() fonction statique
|
Retourne, dans outList, un tableau de tous les convertisseurs chargés par BTranslationRoster. Le nombre d'éléments du tableau est placé dans outCount. L'application a la responsabilité de désallouer le tableau.
CODES DE RETOUR
. Succès.
Voir également: Identify(), GetTranslators(), GetAllTranslators()
|
Sauvegarde les informations de la configuration courante du convertisseur forTranslator dans ioExtension. Cette information peut être compressée, décompressée, et passée à Translate() pour le configurer.
CODES DE RETOUR
. Succès.
Voir également: GetConfigurationView(), Translate()
|
Retourne un tableau des formats de l'entrée ou de la sortie pour le convertisseur forTranslator. outNumFormats est rempli avec le nombre d'éléments du tableau.
CODES DE RETOUR
. Succès.
Voir également: GetTranslatorInfo()
|
Retourne des informations publiques sur le convertisseur forTranslator. Positionne outName avec la description courte du convertisseur, outInfo avec la description longue, et outVersion avec le numéro de version du convertisseur.
CODES DE RETOUR
. Succès.
Voir également: GetInputFormats(), GetOutputFormats()
|
Identifie le média dans inSource, en retournant un tableau de formats valides et les convertisseurs ayant les qualités pour s'occuper d'eux dans outInfo. outNumInfo contient le nombre d'éléments dans le tableau. Si inHintType ou inHintMIME est spécifié, seulement ces convertisseurs qui peuvent accepter les données du type spécifié seront recherchés. Si inWantType est spécifié, seulement les convertisseurs qui pourront fournir des données de ce type en sortie seront recherchés. ioExtension offre l'opportunité à l'application de spécifier des informations supplémentaires de configuration aux add-ons. L'appliation est responsable de la désallocation du tableau.
CODES DE RETOUR
.L'identification de inSource est un succès.
Voir également: Identify(), GetAllTranslators()
|
Identifie le média dans inSource, en retournant le meilleur choix du format et le convertisseur le plus approprié pour le gérer dans outInfo. Si inHintType ou inHintMIME est spécifié, seulement les convertisseurs qui peuvent accepter des données du type spécifié sont recherchés. Si inWantType est spécifié, seulement les convertisseurs qui peuvent fournir en sortie des données de ce type sont recherchés.. ioExtension offre l'opportunité à l'application de spécifier des informations de configuration additionnelles aux add-ons.
Si plus d'un convertisseur peut identifier inSource, alors celui qui a le meilleur rapport quality*capability est retourné.
CODES DE RETOUR
. L'identification de inSource est un succès.
Voir également: GetTranslators(), GetAllTranslators()
|
Retourne, dans outView, un BView contenant des contrôles pour configurer le convertisseur forTranslator. C'est à l'application de rattacher l'objet BView à un objet BWindow. La taille initiale de BView est donnée dans outExtent mais peut être retaillée par l'application.
CODES DE RETOUR
. Succès.
Voir également: GetConfigurationMessage(), Translate()
|
Ces 2 fonctions exécutent la conversion de données, en convertissant la donnée dans inSource en un type inWantoutType et en plaçant la sortie résultant dans outDestination. inInfo doit toujours contenir soit le résultat d'un appel à Identify() ou NULL. Le convertisseur identifié par inInfo->infoTranslator ou inTranslator sera utilisé pour la conversion. Si inInfo est NULL, Translate() appellera en premier Identify() pour déterminer le format de sortie du flux. ioExtension, s'il n'est pas NULL, fournit un chemin de communication entre le convertisseur et l'application. inHintType et inHintMIME, s'ils sont renseignés, sont passés en conseil au convertisseur.
CODES DE RETOUR
. Succès.
La fonction Archive() ajoute le champs suivant à son argument BMessage:
| Champs | Type | Sens |
|---|---|---|
| "be:translator_path"
(array) |
B_STRING_TYPE | Localistaion de l'add-on du kit de conversion ( un champs par add-on). |
| Table des matières du kit de conversion | Index du kit de conversion |
Copyright © 2000 Be, Inc. All rights reserved..