/**
 * GTK2 Media Player - Plugin API
 * 
 * This header defines the public API that plugins must implement
 * and the functions they can call to interact with the application.
 */

#ifndef PLUGIN_H
#define PLUGIN_H

#include <gtk/gtk.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Plugin API version - plugins must match this */
#define PLUGIN_API_VERSION 2

/**
 * Plugin metadata structure
 * Returned by plugin_get_info()
 */
typedef struct {
    const char *name;           /* Display name, e.g. "Screenshot Timer" */
    const char *version;        /* Semantic version, e.g. "1.0.0" */
    const char *description;    /* Short description of functionality */
    const char *author;         /* Author name/email */
    int api_version;            /* Must be PLUGIN_API_VERSION */
} PluginInfo;

/**
 * Application API provided to plugins
 * Passed to plugin_init() for plugins to store and use
 */
typedef struct PluginAPI {
    /* Player control */
    void (*play)(void);
    void (*pause)(void);
    void (*stop)(void);
    void (*toggle_pause)(void);
    void (*seek)(double seconds);
    void (*seek_absolute)(double position);
    
    /* Player state */
    double (*get_position)(void);
    double (*get_duration)(void);
    double (*get_volume)(void);
    gboolean (*is_paused)(void);
    gboolean (*is_playing)(void);
    
    /* Media info */
    char* (*get_current_file)(void);    /* Caller must g_free() */
    char* (*get_media_title)(void);     /* Caller must g_free() */
    
    /* Screenshot */
    void (*take_screenshot)(void);
    void (*take_screenshot_to_file)(const char *path);
    
    /* UI access */
    GtkWindow* (*get_main_window)(void);
    
    /* Message dialogs */
    void (*show_info)(const char *title, const char *message);
    void (*show_warning)(const char *title, const char *message);
    void (*show_error)(const char *title, const char *message);
    
    /* Menu registration - add items to Plugins menu */
    void (*register_menu_item)(GtkWidget *menu_item);
    void (*unregister_menu_item)(GtkWidget *menu_item);
    
    /* UI layouts (Added for Audio Player plugin) */
    void (*set_video_area_visible)(gboolean visible);
    void (*set_window_size)(int width, int height);
    
    /* Advanced MPV access */
    void (*execute_mpv_command)(const char **args);
    
    /* Reserved for future expansion */
    void *_reserved[5];
} PluginAPI;

/**
 * Plugin event types for optional hooks
 */
typedef enum {
    PLUGIN_EVENT_FILE_LOADED,       /* New file loaded, data = filepath (const char*) */
    PLUGIN_EVENT_PLAYBACK_STARTED,  /* Playback started, data = NULL */
    PLUGIN_EVENT_PLAYBACK_PAUSED,   /* Playback paused, data = NULL */
    PLUGIN_EVENT_PLAYBACK_STOPPED,  /* Playback stopped, data = NULL */
    PLUGIN_EVENT_POSITION_CHANGED,  /* Position changed, data = position (double*) */
    PLUGIN_EVENT_VOLUME_CHANGED,    /* Volume changed, data = volume (double*) */
} PluginEventType;

/*
 * =============================================================================
 * REQUIRED PLUGIN EXPORTS
 * 
 * Every plugin MUST implement and export these three functions:
 * =============================================================================
 */

/**
 * Get plugin metadata
 * Must return a pointer to static PluginInfo structure
 * 
 * @return Pointer to plugin info (must remain valid until shutdown)
 */
#define PLUGIN_EXPORT_GET_INFO "plugin_get_info"
typedef const PluginInfo* (*PluginGetInfoFunc)(void);

/**
 * Initialize plugin
 * Called when plugin is loaded. Store the API pointer for later use.
 * 
 * @param api Application API for plugin to use
 * @return 0 on success, non-zero on failure
 */
#define PLUGIN_EXPORT_INIT "plugin_init"
typedef int (*PluginInitFunc)(const PluginAPI *api);

/**
 * Shutdown plugin
 * Called when plugin is unloaded. Clean up any resources.
 */
#define PLUGIN_EXPORT_SHUTDOWN "plugin_shutdown"
typedef void (*PluginShutdownFunc)(void);

/*
 * =============================================================================
 * OPTIONAL PLUGIN EXPORTS
 * 
 * Plugins MAY implement these for additional functionality:
 * =============================================================================
 */

/**
 * Get plugin's menu item(s)
 * If plugin wants to add menu items, return a GtkMenuItem.
 * For multiple items, use a submenu.
 * 
 * @return GtkWidget* menu item, or NULL if none
 */
#define PLUGIN_EXPORT_GET_MENU "plugin_get_menu_item"
typedef GtkWidget* (*PluginGetMenuFunc)(void);

/**
 * Handle application events
 * Called when various application events occur.
 * 
 * @param event Event type
 * @param data Event-specific data (see PluginEventType comments)
 */
#define PLUGIN_EXPORT_ON_EVENT "plugin_on_event"
typedef void (*PluginOnEventFunc)(PluginEventType event, void *data);

/**
 * Configure plugin
 * Called when user selects "Configure" in plugin manager.
 * Should open a configuration dialog.
 */
#define PLUGIN_EXPORT_CONFIGURE "plugin_configure"
typedef void (*PluginConfigureFunc)(void);

/**
 * Show about dialog
 * Called when user selects "About" in plugin manager.
 * Should open an about dialog.
 */
#define PLUGIN_EXPORT_ABOUT "plugin_about"
typedef void (*PluginAboutFunc)(void);

/*
 * =============================================================================
 * HELPER MACROS FOR PLUGIN DEVELOPMENT
 * =============================================================================
 */

/* Declare standard plugin info */
#define DECLARE_PLUGIN_INFO(p_name, p_version, p_description, p_author) \
    static const PluginInfo _plugin_info = { \
        .name = p_name, \
        .version = p_version, \
        .description = p_description, \
        .author = p_author, \
        .api_version = PLUGIN_API_VERSION \
    }; \
    const PluginInfo* plugin_get_info(void) { return &_plugin_info; }

#ifdef __cplusplus
}
#endif

#endif /* PLUGIN_H */
