332 lines
7.6 KiB
C
332 lines
7.6 KiB
C
/******************************************************************************
|
||
* @file tool_registry.h
|
||
* @brief Registre des outils et dépendances externes.
|
||
******************************************************************************/
|
||
|
||
#ifndef LABFY_INVESTIGATION_TOOL_REGISTRY_H
|
||
#define LABFY_INVESTIGATION_TOOL_REGISTRY_H
|
||
|
||
#include <glib.h>
|
||
|
||
G_BEGIN_DECLS
|
||
|
||
/**
|
||
* @brief Importance d’un outil externe pour l’application.
|
||
*/
|
||
typedef enum
|
||
{
|
||
/**
|
||
* L’absence de l’outil ne bloque pas l’application.
|
||
*/
|
||
TOOL_REQUIREMENT_OPTIONAL,
|
||
|
||
/**
|
||
* L’outil est indispensable à la fonctionnalité concernée.
|
||
*/
|
||
TOOL_REQUIREMENT_REQUIRED
|
||
} ToolRequirement;
|
||
|
||
/**
|
||
* @brief État de disponibilité d’un outil externe.
|
||
*/
|
||
typedef enum
|
||
{
|
||
/**
|
||
* L’outil n’a pas encore été recherché.
|
||
*/
|
||
TOOL_AVAILABILITY_UNKNOWN,
|
||
|
||
/**
|
||
* L’exécutable a été trouvé.
|
||
*/
|
||
TOOL_AVAILABILITY_AVAILABLE,
|
||
|
||
/**
|
||
* L’exécutable n’a pas été trouvé.
|
||
*/
|
||
TOOL_AVAILABILITY_MISSING
|
||
} ToolAvailability;
|
||
|
||
/**
|
||
* @brief Erreurs produites par ToolRegistry.
|
||
*/
|
||
typedef enum
|
||
{
|
||
/**
|
||
* Un argument transmis à une fonction est invalide.
|
||
*/
|
||
TOOL_REGISTRY_ERROR_INVALID_ARGUMENT,
|
||
|
||
/**
|
||
* Un outil possède le même identifiant qu’un outil déjà enregistré.
|
||
*/
|
||
TOOL_REGISTRY_ERROR_DUPLICATE_IDENTIFIER,
|
||
|
||
/**
|
||
* L’outil demandé n’existe pas dans le registre.
|
||
*/
|
||
TOOL_REGISTRY_ERROR_NOT_FOUND
|
||
} ToolRegistryError;
|
||
|
||
/**
|
||
* @brief Domaine d’erreur du registre d’outils.
|
||
*/
|
||
#define TOOL_REGISTRY_ERROR \
|
||
tool_registry_error_quark()
|
||
|
||
/**
|
||
* @brief Registre opaque des outils externes.
|
||
*/
|
||
typedef struct ToolRegistry ToolRegistry;
|
||
|
||
/**
|
||
* @brief Informations opaques décrivant un outil externe.
|
||
*/
|
||
typedef struct ToolInfo ToolInfo;
|
||
|
||
/**
|
||
* @brief Retourne le domaine d’erreur du registre.
|
||
*
|
||
* @return Quark GLib du domaine d’erreur.
|
||
*/
|
||
GQuark tool_registry_error_quark(void);
|
||
|
||
/**
|
||
* @brief Crée un registre d’outils vide.
|
||
*
|
||
* @return Nouveau registre, ou NULL en cas d’échec.
|
||
*/
|
||
ToolRegistry *tool_registry_new(void);
|
||
|
||
/**
|
||
* @brief Libère un registre et tous les outils qu’il contient.
|
||
*
|
||
* @param tool_registry Registre à libérer, ou NULL.
|
||
*/
|
||
void tool_registry_free(
|
||
ToolRegistry *tool_registry
|
||
);
|
||
|
||
/**
|
||
* @brief Enregistre un nouvel outil externe.
|
||
*
|
||
* Le registre duplique toutes les chaînes reçues.
|
||
*
|
||
* L’outil commence avec :
|
||
*
|
||
* - une disponibilité inconnue ;
|
||
* - aucun chemin résolu ;
|
||
* - aucune version détectée.
|
||
*
|
||
* @param tool_registry Registre cible.
|
||
* @param identifier Identifiant interne unique.
|
||
* @param display_name Nom affiché à l’utilisateur.
|
||
* @param executable_name Nom de l’exécutable recherché dans le PATH.
|
||
* @param requirement Importance de la dépendance.
|
||
* @param error Emplacement facultatif pour l’erreur.
|
||
*
|
||
* @return TRUE en cas de succès, sinon FALSE.
|
||
*/
|
||
gboolean tool_registry_register(
|
||
ToolRegistry *tool_registry,
|
||
const char *identifier,
|
||
const char *display_name,
|
||
const char *executable_name,
|
||
ToolRequirement requirement,
|
||
GError **error
|
||
);
|
||
|
||
/**
|
||
* @brief Recherche tous les exécutables enregistrés dans le PATH.
|
||
*
|
||
* Chaque ancien chemin résolu est remplacé par le résultat de la nouvelle
|
||
* détection.
|
||
*
|
||
* @param tool_registry Registre à actualiser.
|
||
* @param error Emplacement facultatif pour l’erreur.
|
||
*
|
||
* @return TRUE lorsque le rafraîchissement a pu être effectué.
|
||
*/
|
||
gboolean tool_registry_refresh(
|
||
ToolRegistry *tool_registry,
|
||
GError **error
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne le nombre d’outils enregistrés.
|
||
*
|
||
* @param tool_registry Registre consulté.
|
||
*
|
||
* @return Nombre d’outils, ou zéro si le registre est NULL.
|
||
*/
|
||
gsize tool_registry_get_count(
|
||
const ToolRegistry *tool_registry
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne un outil à partir de son index.
|
||
*
|
||
* Le pointeur retourné est emprunté. Il ne doit pas être libéré.
|
||
*
|
||
* @param tool_registry Registre consulté.
|
||
* @param index Index de l’outil.
|
||
*
|
||
* @return Outil correspondant, ou NULL si l’index est invalide.
|
||
*/
|
||
const ToolInfo *tool_registry_get_tool(
|
||
const ToolRegistry *tool_registry,
|
||
gsize index
|
||
);
|
||
|
||
/**
|
||
* @brief Recherche un outil à partir de son identifiant.
|
||
*
|
||
* Le pointeur retourné est emprunté. Il ne doit pas être libéré.
|
||
*
|
||
* @param tool_registry Registre consulté.
|
||
* @param identifier Identifiant recherché.
|
||
*
|
||
* @return Outil correspondant, ou NULL s’il est absent.
|
||
*/
|
||
const ToolInfo *tool_registry_find(
|
||
const ToolRegistry *tool_registry,
|
||
const char *identifier
|
||
);
|
||
|
||
/**
|
||
* @brief Mémorise la version détectée d’un outil.
|
||
*
|
||
* Une version NULL ou vide efface la version actuellement enregistrée.
|
||
*
|
||
* @param tool_registry Registre contenant l’outil.
|
||
* @param identifier Identifiant de l’outil.
|
||
* @param detected_version Version détectée, ou NULL.
|
||
* @param error Emplacement facultatif pour l’erreur.
|
||
*
|
||
* @return TRUE en cas de succès, sinon FALSE.
|
||
*/
|
||
gboolean tool_registry_set_version(
|
||
ToolRegistry *tool_registry,
|
||
const char *identifier,
|
||
const char *detected_version,
|
||
GError **error
|
||
);
|
||
|
||
/**
|
||
* @brief Indique si une dépendance obligatoire est explicitement absente.
|
||
*
|
||
* Les outils encore dans l’état UNKNOWN ne sont pas considérés ici comme
|
||
* explicitement absents.
|
||
*
|
||
* @param tool_registry Registre consulté.
|
||
*
|
||
* @return TRUE si au moins un outil obligatoire est MISSING.
|
||
*/
|
||
gboolean tool_registry_has_missing_required_tools(
|
||
const ToolRegistry *tool_registry
|
||
);
|
||
|
||
/**
|
||
* @brief Indique si toutes les dépendances obligatoires sont disponibles.
|
||
*
|
||
* Un outil obligatoire dans l’état UNKNOWN empêche cette fonction de
|
||
* retourner TRUE.
|
||
*
|
||
* @param tool_registry Registre consulté.
|
||
*
|
||
* @return TRUE si tous les outils obligatoires sont AVAILABLE.
|
||
*/
|
||
gboolean tool_registry_all_required_tools_available(
|
||
const ToolRegistry *tool_registry
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne l’identifiant interne d’un outil.
|
||
*
|
||
* La chaîne retournée est empruntée.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return Identifiant, ou NULL.
|
||
*/
|
||
const char *tool_info_get_identifier(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne le nom affiché d’un outil.
|
||
*
|
||
* La chaîne retournée est empruntée.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return Nom affiché, ou NULL.
|
||
*/
|
||
const char *tool_info_get_display_name(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne le nom de l’exécutable d’un outil.
|
||
*
|
||
* La chaîne retournée est empruntée.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return Nom de l’exécutable, ou NULL.
|
||
*/
|
||
const char *tool_info_get_executable_name(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne l’importance d’un outil.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return Importance de l’outil.
|
||
*/
|
||
ToolRequirement tool_info_get_requirement(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne l’état de disponibilité d’un outil.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return État de disponibilité.
|
||
*/
|
||
ToolAvailability tool_info_get_availability(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne le chemin absolu détecté d’un outil.
|
||
*
|
||
* La chaîne retournée est empruntée.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return Chemin détecté, ou NULL.
|
||
*/
|
||
const char *tool_info_get_resolved_path(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne la version détectée d’un outil.
|
||
*
|
||
* La chaîne retournée est empruntée.
|
||
*
|
||
* @param tool_info Outil consulté.
|
||
*
|
||
* @return Version détectée, ou NULL.
|
||
*/
|
||
const char *tool_info_get_detected_version(
|
||
const ToolInfo *tool_info
|
||
);
|
||
|
||
G_END_DECLS
|
||
|
||
#endif
|