[Tsp-devel] pseudo API pour une libtspconfig

[Eric NOULARD]

Suite à une petite discussion avec Ivano,

Voici mon point de vue sur l'API souhaitable pour
une libtspconfig qui lise/écrive les fichiers de conf
XML dont j'ai parlé dans un mail précédent.
http://lists.gnu.org/archive/html/tsp-devel/2004-10/msg00060.html

Je ne parle ici que d'une API C,
ça devrait se transcrire tranquillou en Java pour les amateurs
(m'enfin de ce côté là y'a pas de presse vu jsynoptic).

Je veux [et là je fait le despote :))]
une API:

1) orientée objet
2) ré-entrante.
3) la moins dépendante possible du format de fichier

Voici ma proposition:

#typedef struct tsp_config {

... [ce qui sera necessaire] ...
} tsp_config_t;


/**
* Create and initiliaze a TSP conf.
*/
int32_t tsp_config_create(tsp_config_t** tspconf);

/**
* Destroy a a TSP conf.
*/
int32_t tsp_config_destroy(tsp_config_t* tspconf);

/**
* Open a TSP config file.
* @param path, the file path
* @param mode, opening mode Read, Write etc...
*/
int32_t tsp_config_open(tsp_config_t* tspconf, const char* path, int32_t
mode);

/**
* Close a TSP config file.
* May flush a file opened for writing to disk.
*/
int32_t tsp_config_close(tsp_config_t* tspconf);

/**
* Read/Write an previously opened config file.
* @param action 
*        a tsp_config_action_t which is a to be defined enum
*        for now the only actions supported are
*        TSP_CONFIG_READ_ALL and TSP_CONFIG_WRITE_ALL
*/
int32_t tsp_config_read(tsp_config_t* tspconf, tsp_config_action_t
action);
int32_t tsp_config_write(tsp_config_t* tspconf, tsp_config_action_t
action);

/**
* Returns the number of providers referenced in a config file.
*/
int32_t tsp_config_get_nb_providers(tsp_config_t* tspconf);

/**
* Returns the tsp_url of the provider of specified rank.
* @param provider_rank IN, the provider rank
* @param tsp_url OUT, the tsp provider URL (should be preallocated)
* @param tsp_url_max_size  IN, the size of the preallocated tsp_url.
*/
int32_t tsp_config_get_url(tsp_config_t* tspconf, uint32_t
provider_rank, char* tsp_url, size_t tsp_url_max_size);

/**
* Returns the number of sample symbols of the provider of rank i
*/
int32_t tsp_config_get_nb_symbols(tsp_config_t* tspconf, uint32_t
provider_rank);

/**
* Fill a pre-allocated TSP_consumer_symbol_requested_list_t
* 'symbols' with the symbols found for the provider of 
* specified rank.
* (this function is mainly for READING config file)
* @param symbols_list IN/OUT, on entry the preallocated structure 
*                             on return the updated structure filled
with
*                             requested symbol name, period and phase.
*        
*/
int32_t tsp_config_get_symbols(tsp_config_t* tspconf, uint32_t
provider_rank, TSP_consumer_symbol_requested_list_t* symbols_list);


/**
 * Add a TSP provider to a 'to be written' TSP config
 */
int32_t tsp_config_add_provider(tsp_config_t* tspconf, const char*
tsp_url);

/**
 * Add a set of sample to a 'to be written' TSP config
 * (note that it is similar to 'tsp_config_get_symbols')
 */
int32_t tsp_config_add_symbols(tsp_config_t* tspconf, uint32_t
provider_rank, TSP_consumer_symbol_requested_list_t* symbols_list);


/********* l'API precedente devrait etre suffisante a lire/ecrire des
sample request *******/
Maintenant il faudra trouver un moyen generique d'acceder a des infos
de 'mise en forme'. Genre le sample nomme 'toto' du provider 1 doit
etre un view dans la fenetre 1 etc...

C'est la notion de sample_layout.
Pour l'instant et ce soir en particulier je seche un peu donc ce 
qui suit apres
ne saurait etre considere comme une idee fiable (j'attends vos
contribs).


Dans une config il existe des layouts:

typedef struct tsp_config_layout {
  int layout_type;
  ...???....
} tsp_config_layout_t;

A l'issu de la lecture d'une conf on peut connaitre leur nombre

tsp_config_get_nb_layout(tsp_config_t* tspconf);

On peut connaitre la liste des symboles attaches a un layout
sous la forme d'une liste de doublet (provider_rank,
symbol_index_in_provider);
[!! Attention un meme symbole peut etre attache a des layout
    differents
 !!]

Ensuite il faut definir les differents type de layout,
je propose:

- View 
- Draw
- File

Chaque layout aura sa propre API et la j'attends les suggestions
des specialistes IHMs...


Eric