/***************************************************************************
         eboxyplugin.h - plugin client library header (external C header)
                             -------------------
    begin                : Thu Oct 3 2002
    copyright            : (C) 2002 by Paul Eggleton
    email                : bluelightning\bluelightning.org
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

/** @file eboxyplugin.h eboxy Plugin API header */

#ifndef PLUGINTYPES_H
#include "plugintypes.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/** Finds a specific object by name, and optionally type.
 *  @param object the name of the object
 *  @param type the type name of the object you're looking for. Pass NULL if you don't care about the type.
 *  @return 1 if the object exists, 0 if not.
 */
int findObject(const char *object, const char *type);

/** Gets the type name of an object.
 *  @param object the name of the object
 *  @return the type name of the specified object or NULL if the object doesn't exist.
 */
const char *typeOfObject(const char *object);

/** Gets the string value of a property.
 *  @param object the name of the object
 *  @param property the name of the property
 *  @return the value of the specified property (or NULL in case of an error).
 */
char *getPropertyAsString(const char *object, const char *property);

/** Sets the string value of a property.
 *  @param object the name of the object
 *  @param property the name of the property
 *  @param value the value to set the property to
 */
int setPropertyAsString(const char *object, const char *property, const char *value);

/** Calls a method on an object
 *  @param object the name of the object
 *  @param method the name of the method
 *  @param numargs the number of arguments being passed to the function (must be equal to the number
 *         specified when the method was registered).
 *  @param args the arguments to pass to the function (pass NULL and 0 for numargs for no arguments).
 *  @return return value of method (NULL if none). Must be freed if not NULL (use callMethodNoReturn()
 *         if you don't care about the return value).
 */
char *callMethod(const char *object, const char *method, int numargs, const char *args[]);

/** Calls a method on an object, when you don't care about the return value.
 *  @param object the name of the object
 *  @param method the name of the method
 *  @param numargs the number of arguments being passed to the function (must be equal to the number
 *         specified when the method was registered).
 *  @param args the arguments to pass to the function (pass NULL and 0 for numargs for no arguments).
 */
void callMethodNoReturn(const char *object, const char *method, int numargs, const char *args[]);

/** Registers a new custom object.
 *  @param name the name of the object
 *  @return 0 on success, non-zero on failure.
 */
int registerObject(const char *name);

/** Registers a property on a custom object.
 *  Properties can only be registered on objects that your plugin created.
 *  @param object the name of the object
 *  @param property the name of the property
 *  @param getter exact name of the function to call in your plugin to get the value of this property.
 *    The function should be defined like this (with your own name, of course):
 *    <pre>  const char *getter(const char *sender)</pre>
 *    You may pass NULL for this parameter, in which case the property will be write-only.
 *  @param setter exact name of the function to call in your plugin to set the value of this property.
 *    The function should be defined like this (with your own name, of course):
 *    <pre>  void setter(const char *sender, const char *value)</pre>
 *    You may pass NULL for this parameter, in which case the property will be read-only.
 *  @return 0 on success, non-zero on failure.
 */
int registerPropertyDL(const char *object, const char *property, const char *getter, const char *setter);

/** Registers a handler for an event. <i>Note:</i> you will not get an error if you register for an event
 *  that will never be triggered, so be careful to type the name correctly.
 *  @param object the name of the object
 *  @param event the name of the event
 *  @param eventfunc exact name of the function to call in your plugin when the event occurs.
 *    The function should be defined like this (with your own name, of course):
 *    <pre>  int eventhandler(const char *sender)</pre>
 *    The return value of this function is currently unused, but you should return 0 for
 *    compatibility with future usage.
 *  @return 0 on success, non-zero on failure.
 */
int registerEventHandlerDL(const char *object, const char *event, const char *eventfunc);

/** Registers a method on a custom object.
 *  Methods can only be registered on objects that your plugin created.
 *  @param object the name of the object
 *  @param method the name of the method
 *  @param numargs the number of arguments the function expects
 *  @param methodfunc exact name of the function to call in your plugin when the method is called.
 *    The function should be defined like this (with your own name, of course):
 *    <pre>  const char *methodcall(const char *sender, int numargs, const char *args[])</pre>
 *    The return value of this function is accessible in scripts. You may return anything you like,
 *    as long as it isn't NULL or an invalid pointer. Return empty string ("") if you don't want to
 *    return anything.
 *  @return 0 on success, non-zero on failure.
 */
int registerMethodDL(const char *object, const char *method, int numargs, const char *methodfunc);

/** Fires an event on an object.
 *  Events can only be fired on objects that your plugin created.
 *  @param object the name of the object
 *  @param event the name of the event
 *  @return 0 on success, non-zero on failure.
 */
int fireEvent(const char *object, const char *event);

/** Gets information on a loaded plugin.
 *  @param name the name of the plugin
 *  @return a struct containing info on the plugin.
 */
const struct plugin_info *getPluginInfo(const char *name);

/** Sets information for your plugin.
 *  This should only ever be called once, in your plugin's ebplugin_init function.
 *  @param namestring the full name of your plugin (excluding version information, otherwise freeform)
 *  @param verstring a version string for your plugin (freeform)
 */
void setPluginInfo(const char *namestring, const char *verstring);

/** Tells eboxy that your plugin should be unloaded as soon as possible.
 */
void requestUnload(void);

/** Changes the current page.
 *  @param pagename the name of the page to change to
 *  @return 0 on success, non-zero on failure.
 */
int changePage(const char *pagename);

/** Loads a new XML file.
 *  @param filename the XML file to load.
 *  @param pagename the name of the page to start with (pass NULL to use the first listed).
 *  @return 0 on success, non-zero on failure.
 */
int loadXMLFile(const char *filename, const char *pagename);

/** Performs an eboxy action (see documentation for action list).
 *  @param actionname the name of the action.
 *  @return 0 on success, non-zero on failure.
 */
int performAction(const char *actionname);

/** Checks if a plugin is loaded.
 *  @param name the name of the plugin
 *  @return 1 if the plugin is loaded, 0 if not.
 */
int isPluginLoaded(const char *name);

/** Unregisters a previously registered custom object. Also unregisters properties, methods and event handlers
 *  registered on the object. Note: it is not required that you unregister objects you create - only if you wish
 *  to withdraw them from service for some reason but still keep the plugin running. (Objects are automatically
 *  unregistered when the plugin that owns them is unloaded).
 *  @param name the name of the object
 *  @return 0 on success, non-zero on failure.
 */
int unregisterObject(const char *name);

/** Unregisters a previously registered handler for an event. Note: it is not required that you unregister events -
 *  only if you wish to stop handling them for some reason but still keep the plugin running. (Event handlers are
 *  automatically unregistered when the plugin that owns them is unloaded).
 *  @param object the name of the object
 *  @param event the name of the event
 *  @return 0 on success, non-zero on failure.
 */
int unregisterEventHandlerDL(const char *object, const char *event);

/** Creates a widget at runtime. Note that to actually make use of this widget, you will need to set its properties 
 *  and then add it to the current page.
 *  @param name the name of the new widget
 *  @param type the type of widget to create. These are the same names as used in the XML skin file.
 *  @param templatename the name of a template from the current XML file to apply to the new widget (optional - pass NULL if unused).
 *  @return 0 on success, non-zero on failure.
 */
int createWidget(const char *name, const char *type, const char *templatename);

/** Creates a page at runtime.
 *  @param name the name of the new page
 *  @return 0 on success, non-zero on failure.
 */
int createPage(const char *name);

/** Creates a copy of an existing widget at runtime. Note that to actually make use of this widget, you will need to
 *  add it to the current page (possibly adjusting its property values beforehand).
 *  @param original the name of the widget to clone
 *  @param duplicate the name of the new duplicate widget
 *  @return 0 on success, non-zero on failure.
 */
int cloneWidget(const char *original, const char *duplicate);

/** Deletes a widget at runtime. The widget cannot be added to a page at this time - you must remove it first.
 *  @param name the name of the widget to delete
 *  @return 0 on success, non-zero on failure.
 */
int deleteWidget(const char *name);

/** Deletes a page at runtime. The page you are deleting can be any page, dynamically created or otherwise, as long
 *  as it is not currently being displayed.
 *  @param name the name of the page to delete
 *  @return 0 on success, non-zero on failure.
 */
int deletePage(const char *name);

/** Execute the specified eboxy script code.
 *  @param code a string containing the script code to execute
 *  @param flags 1 to allow potentially dangerous commands (such as exec) to be used, zero otherwise. All other
 *  values are reserved (and ignored) at this time and should not be supplied.
 *  @return 0 on success, non-zero on failure.
 *  If the trusted flag is turned off, the following commands are disabled within the specified code, and will
 *  result in an error: exec, execwait, exechide, load, loadplugin.
 */
int runScript(const char *code, int flags);

#ifdef __cplusplus
}
#endif