Spécification fonctionnelles générales

L'utilisation type de la librairie serait la suivant :

  • On appelle une fonction d'initialisation avec en paramètre une chaine de caractère représentant le nom complet d'un fichier (par exemple /home/david/Mes Documents/super musique.mid). On obtient une structure qui contient des données sur le fichier midi (taille, format, nombre de piste, etc...)
  • On appelle ensuite une fonction de parcours, en fournissant la structure précédemment obtenue et la piste à parcourir. On obtient une structure qui contient un évènement Midi. Les pointeurs internes pour la piste concernée sont mis à jours, de sorte que le prochain appel à la fonction de parcours renvoie l'évènement midi suivant. Si on est en fin de piste, on renvoie NULL (0).
  • Enfin, une fonction de positionnement permettra, à partir d'une structure sur le fichier midi, le numéro d'une piste et d'une valeur de décalage i de positionner les pointeurs internes d'une piste sur le i-ème élément, récupérable ensuite avec la fonction de parcours.

Les fonctions renverront toutes un code de retour :

0
échec
1
réussite

Afin de pouvoir analyser un échec, on doit disposer d'un mécanisme de diagnostic : une fonction retournera une structure représentant une erreur.

Enfin, pour découpler l'accès aux données des structures de l'implémentation des structures, la librairie fournira des fonctions pour accéder à ces informations. On retrouve ici une approche orientée objet (note pour plus tard : concevoir un ensemble de classes qui encapsule l'API de cette librairie).

Récapitulatif

Types à définir

On ne détaille pas encore l'implémentation des structures.

S4mfrStandardMidiFileInfo
Structure regroupant les informations globales d'un fichier MIDI standard (fichier, type, nombre de piste, pointeurs internes, etc...)
S4mfrMidiEvent
Structure regroupant les informations relatives à un évènement midi (instant, type, données supplémentaires)
S4mfrError
Structure permettant le diagnostique de la dernière erreur rencontrée.
S4mfrString
Un alias d'un type (usuellement char *) représentant une chaine de caractères.

Les fonctions

On utilise une pseudo type String pour représenter le type finalement utilisé pour une chaîne de caractères. On ne liste pas les accesseurs, car on n'a pas encore décidé des informations à récupérer et à stocker dans les structures.

On préfixe toutes les fonctions par S4mfr_

unsigned int S4mfr_openStandardMidiFile(String fileName, S4mfrStandardMidiFileInfo** standardMidiFileInfo, S4mfrError** error)
Ouvre un fichier midi et créée une structure StandardMidiFileInfo.
Erreur si on ne peut pas charger le fichier ou si il y a une incohérence dans la taille du fichier et les informations de longueur.
unsigned int S4mfr_closeStandardMidiFile(S4mfrStandardMidiFileInfo* standardMidiFileInfo, S4mfrError** error)
Libère les ressources utilisée par S4mfr_openStandardMidiFile.
Erreur si on ne peut pas libérer les ressources (déjà libérées par exemple).
unsigned int S4mfr_getNextEvent(S4mfrStandardMidiFileInfo* standardMidiFileInfo, unsigned int track, S4mfrMidiEvent**, S4mfrError** error)
Récupère un évènement d'une piste est avance d'un cran das la liste des évènement.
Erreur si on ne peut pas pas avancer (arrivée en fin de piste).
String S4mfr_getErrorCode(S4mfrError* error)
Récupère un code d'erreur à partir d'une structure de diagnostique.
int S4mfr_getErrorLevel(S4mfrError* error)
Récupère un niveau de sévérité d'erreur à partir d'une structure de diagnostique.
String S4mfr_getErrorMessage(S4mfrError* error)
Récupère un message d'erreur à partir d'une structure de diagnostique.