ROX-CLib

For Programmers

Compiling and linking against the library

Compile the library first

Copy the libdir script from ROX-CLib/$PLATFORM/bin/libdir into your app dir.

Add the output of

   ROX-CLib --cflags

   ROX_CLIB="`$APP_DIR/libdir ROX-CLib`/AppRun"

   gcc `$ROX_CLIB --cflags` -c main.c 

You should include the main file:

   #include <rox/rox.h>

Add the output of

   ROX-CLib --cflags
   ROX-CLib --libs

   ROX_CLIB="`$APP_DIR/libdir ROX-CLib`/AppRun"

   gcc `$ROX_CLIB --cflags` -o main main.o `$ROX_CLIB --libs`

If you are using autoconf and building a ROX program then:

• Copy ROX-CLib/Help/aclocal.m4 to your programs src directory.
• In src/configure.in add:

  ROX_CLIB(2, 0, 0)

• In src/Makefile.in add:

    ROX_CLIB = @ROX_CLIB_PATH@/AppRun

  and to CFLAGS add: `${ROX_CLIB} --cflags` and to LDFLAGS add: `${ROX_CLIB} --libs`
• In AppRun (and AppletRun if it is an applet) ensure you have:

     APP_DIR=`dirname $0`
     APP_DIR=`cd $APP_DIR;pwd`; export APP_DIR
     if [ -z "$LD_LIBRARY_PATH" ]; then
         LD_LIBRARY_PATH=`$APP_DIR/libdir ROX-CLib --runtime`
     else
         LD_LIBRARY_PATH=`$APP_DIR/libdir ROX-CLib --runtime`:$LD_LIBRARY_PATH
     fi
     export LD_LIBRARY_PATH
  

Zero Install

To use ROX-CLib through Zero Install change the use of libdir to:

    ROX_CLIB="`$APP_DIR/libdir --0install www.kerofin.demon.co.uk ROX-CLib`/AppRun"

Library reference

Organized by header file. Last updated for version 2.1.4. Use as e.g.

#include <rox/rox.h>
#include <rox/rox_soap.h>

• rox.h
• choices.h
• error.h
• gtksavebox.h
• infowin.h
• rox_debug.h
• rox_dnd.h
• rox_path.h
• rox_resources.h
• rox_soap.h
• rox_filer_action.h
• applet.h
• rox_soap_server.h
• options.h
• basedir.h
• mime.h
• appinfo.h
• mime_handler.h
• uri.h

rox.h

Top level include. It includes:

• choices.h
• options.h
• error.h
• rox_debug.h
• rox_resources.h
• infowin.h

Six functions are declared:

void rox_init(const char *program, const char *domain, int *argc, char ***argv)

This handles the initialization of the library. It calls:

• gtk_init(argc, argv)
• rox_debug_init(program)
• choices_init()
• options_init_with_domain(program, domain) (if it detects an $APP_DIR/Options.xml file)
• rox_dnd_init()
• mime_init()

domain is used to differentiate your program called "App" from every other program called "App". It is a domain name under the control of the program's author. If you do not have a unique domain, you can use your email address.

void rox_init(const char *program, int *argc, char ***argv)

This handles the initialization of the library. It is equivalent to rox_init_with_domain(program, NULL, argc, argv).

const gchar *rox_get_program_name(void);

Returns the program name, as passed to rox_init(). If rox_init() was not called then it returns NULL.

const gchar *rox_get_app_dir(void);

Returns the program's application directory, the environment variable APP_DIR. If APP_DIR is not defined then it returns NULL.

GdkPixbuf *rox_get_program_icon(void);

Returns the program icon, loaded from the file .DirIcon in the application directory. If there is no icon then NULL is returned.

int rox_clib_version_number(void)

Returns the version number of the library, so that 1.2.3 is encoded as 10203.

const char *rox_clib_version_string(void)

Returns a string of the version number of the library, in the form "x.y.z (nth month year)" (actually the contents of the Version tag in the AppInfo.xml file).

int rox_clib_gtk_version_number(void)

Returns the version number of the GTK+ library ROX-CLib is linked against, so that 1.2.3 is encoded as 10203.

const char *rox_clib_gtk_version_string(void)

Returns a string of the version number of the GTK+ library ROX-CLib is linked against.

void rox_add_window(GtkWidget *window)

Registers the window with the window counting system. When the window is destoyed it will automatically be de-registered.

int rox_get_n_windows(void)

Returns the number of windows registered.

void rox_main_loop(void)

This behaves as gtk_main(), except that it will return when the number of registered windows reaches zero. If there are no registered windows when called it will return immediately. (Opening an options window via options_show() registers a window).

void rox_main_quit(void)

Exit from rox_main_loop() by calling gtk_main_quit(). The number of registered windows is ignored.

choices.h

Interface to the choices system and $CHOICESPATH. Originally by Thomas Leonard and taken from the ROX-Filer source.

void choices_init(void)

Must be called before the other choices_* calls.

GPtrArray *choices_list_dirs(const char *dir)

Returns an array of the directories in CHOICESPATH which contain a subdirectory called 'dir'. The result should be freed by passing it to choices_free_list()

void choices_free_list(GPtrArray *list)

Frees the list returned by choices_list_dirs()

gchar *choices_find_path_load(const char *leaf, const char *dir)

Get the pathname of a choices file to load. Eg: choices_find_path_load("menus", "ROX-Filer") -> "/usr/local/share/Choices/ROX-Filer/menus".

The return values may be NULL - use built-in defaults - otherwise g_free() the result.

gchar *choices_find_path_save(const char *leaf, const char *dir, gboolean create)

Returns the pathname of a file to save to, or NULL if saving is disabled. If 'create' is TRUE then intermediate directories will be created (set this to FALSE if you just want to find out where a saved file would go without actually altering the filesystem).

g_free() the result.

gchar *rox_choices_load(const char *leaf, const char *dir, const char *domain)

Get the pathname of a choices file to load. Eg: rox_choices_load("menus", "ROX-Filer", "rox.sourceforge.net") -> "/usr/local/share/Choices/ROX-Filer/menus" (or "/etc/xdg/rox.sourceforge.net/ROX-Filer/menus" ).

The return values may be NULL - use built-in defaults - otherwise g_free() the result.

This uses the XDG base directories specification (used by basedir.h) to look up the file, falling back on the old $CHOICESPATH system. domain may be NULL.

gchar *rox_choices_save(const char *leaf, const char *dir, const char *domain)

Returns the pathname of a file to save to, or NULL if saving is disabled.

g_free() the result.

This uses the XDG base directories specification (used by basedir.h) to look up the file, but it does not use the old $CHOICESPATH system. domain may be NULL.

error.h

Reporting errors.

void rox_error(const char *fmt, ...)

Generates a string according to a printf style formatting string and supplied args, then displays the string in a dialog window with the title "Error!" and an OK button.

gtksavebox.h

Simple RISC OS style save box.

GtkSaveBox is a GTK+ widget, derived from GtkWindow. Originally by Thomas Leonard and taken from the ROX-Filer source.

Functions

GtkWidget* gtk_savebox_new(void)

Creates the GtkSaveBox widget.

void gtk_savebox_set_icon(GtkSavebox *savebox, GdkPixmap *pixmap, GdkPixmap *mask)

Sets the icon that may be dragged about.

void gtk_savebox_set_pathname(GtkSavebox *savebox, gchar *pathname)

Sets the pathname in the entry box.

Types

enum { GTK_XDS_SAVED, GTK_XDS_SAVE_ERROR, GTK_XDS_NO_HANDLER, }

Used by the save_to_file signal:

GTK_XDS_SAVED	Done the save - no problem
GTK_XDS_SAVE_ERROR	Error during save - reported
GTK_XDS_NO_HANDLER	Used internally (sanity checking)

Signals

gint save_to_file(GtkSavebox *savebox, const gchar *pathname)

Save the data to disk using this pathname. Return GTK_XDS_SAVED on success, or GTK_XDS_SAVE_ERROR on failure (and report the error to the user somehow). DO NOT mark the data unmodified or change the pathname for the file - this might be a scrap file transfer.

void saved_to_uri(GtkSavebox *savebox, const gchar *uri)

The data is saved. If 'uri' is non-NULL, mark the file as unmodified and update the pathname/uri for the file to the one given.

infowin.h

RISC OS style information window.

ROXInfoWin is a GTK+ widget, derived from GtkDialog. Changed in ROX-CLib 2.1.2: InfoWin was renamed ROXInfoWin and the functions renamed accordingly. Functions remain available under the old names for binary compatability, but should not be used in new code.

Functions

GtkWidget* rox_info_win_new(const gchar *program, const gchar *purpose, const gchar *version, const gchar *author, const gchar *website)

Create a new ROXInfoWin object. The data in the window is taken from the function arguments. rox_info_win_new_from_appinfo is prefered.

GtkWidget* rox_info_win_new_from_appinfo(const gchar *program)

Create a new ROXInfoWin object. The data in the window is taken from the file $APP_DIR/AppInfo.xml, if it exists.

void rox_info_win_add_browser_command(ROXInfoWin *iw, const gchar *cmd)

Adds a command which will visit a named web site. The command will be called with a single argument, the URL passed in rox_info_win_new() or defined in $APP_DIR/AppInfo.xml.

Deprecated, ROXInfoWin now uses rox_uri_launch() which relies on the handler for the text/x-uri MIME type.

GtkWidget* info_win_new(const gchar *program, const gchar *purpose, const gchar *version, const gchar *author, const gchar *website)

Deprecated. Use rox_info_win_new_from_appinfo() instead. This is the same as that, except that the new window is persistant: when closed it is hidden, not destroyed.

GtkWidget* info_win_new_from_appinfo(const gchar *program)

Deprecated. Use rox_info_win_new_from_appinfo() instead. This is the same as that, except that the new window is persistant: when closed it is hidden, not destroyed

void info_win_add_browser_command(ROXInfoWin *iw, const gchar *cmd)

Deprecated.

Signals

None.

rox_debug.h

Utilities for generating debug output. Unless the pre-processor symbol DEBUG is defined and non-zero before rox_debug.h is included then nothing is declared.

void rox_debug_init(const char *progname)

Initialises the debug system. progname is the name of the program which will prefix the output. Should be called at start, if not (or progname==NULL) then progname is assumed to be "ROX".

void rox_debug_printf(int level, const char *format, ...)

Sends a debug message, using glib's g_logv. level is the level of severity and should be in the range 0-5, with 0 most severe. The user controls the amount of output by setting the environment PROGNAME_DEBUG_LEVEL to the maximum severity to display.

#define dprintf rox_debug_printf

Aliases dprintf as rox_debug_printf

rox_dnd.h

Utilities to simplify the handling of drag and drop for the client. Based on the ROX-Filer code written by Thomas Leonard

typedef gboolean (*rox_dnd_handle_uris)(GtkWidget *widget, GSList *uris, gpointer data, gpointer udata)

Type of function called when a widget registered with rox_dnd has a list of URIs dropped on it. It should return TRUE if handled successfully, FALSE otherwise.

typedef gboolean (*rox_dnd_handle_xds)(GtkWidget *widget, const gchar *path, gpointer data, gpointer udata)

Type of function called when a widget registered with rox_dnd has a direct save on it. It should return TRUE if handled successfully, FALSE otherwise.

void rox_dnd_init(void)

Called to initialise rox_dnd, before any other call.

void rox_dnd_register_full(GtkWidget *widget, guint flags, rox_dnd_handle_uris uris, rox_dnd_handle_xds xds, gpointer udata)

Registers a widget with rox_dnd to handle any drops on it. There are no flags defined yet, so flags must be set to zero. uris handles URI list drops, xds handles the XDirectSave protocol. udata is passed to the handler routine.

GSList *rox_dnd_filter_local(GSList *uris)

Scans list of URIs and picks out only those that refer to local files. Free result with rox_dnd_local_free().

void rox_dnd_local_free(GSList *paths)

Frees the data returned by rox_dnd_filter_local().

rox_path.h

Utilities for handling the URIs used in the drag & drop protocol. All returned strings should be passed to g_free() when done.

gchar *rox_path_get_local(const gchar *uri)

Returns the local path of the URI if it refers to a local file: path, otherwise it returns NULL.

gchar *rox_path_get_server(const gchar *uri)

Returns the host part of the URI if it is a file: URI, otherwise it returns NULL.

gchar *rox_path_get_path(const gchar *uri)

Returns the path part of a file: URI regardless of whether it is the local host or not.

int rox_hostname_is_local(const gchar *hname)

Returns TRUE if the host name hname is one of the valid host names for the current machine.

rox_resources.h

Utility functions for finding resource files, which may be locale specific.

gchar *rox_resources_find(const gchar *app_name, const gchar *leaf, const gchar *lang)

Search $CHOICESPATH, then $APP_DIR for a directory called Resources which contains the file leaf, whether in a sub-directory lang or directly. Returns the full path if found (pass to g_free when done) or NULL if not. lang may be ROX_RESOURCES_NO_LANG to not search for sub-directories, or ROX_RESOURCES_DEFAULT_LANG for the sub-directory appropriate for the selected language.

If the language is set to en_GB.ISO8859-1 then the sub-directories tried are:

• {Choices}/app_name/en_GB.ISO8859-1/
• {Choices}/app_name/en.ISO8859-1/
• {Choices}/app_name/en_GB/
• {Choices}/app_name/en/
• {Choices}/app_name/

in that order.

rox_soap.h

Communicating with the filer via SOAP. Based on the ROX-Filer code written by Thomas Leonard

typedef struct rox_soap_filer ROXSOAP;

This is an opaque type representing the connection to an instance of the filer.

typedef void (*rox_soap_callback)(ROXSOAP *filer, gboolean status, xmlDocPtr reply, gpointer udata)

Defines the function called when the SOAP call completes. If status is FALSE then the call failed and reply is NULL. If status is not FALSE then the call succeeded and reply contains the result (may still be NULL).

void rox_soap_init(void); =09

Initializes the data.

void rox_soap_define_program(const char *name, const char *atom_fmt, const char *command);

Define how to connect to the named program.

name	name of program as passed to rox_soap_connect
atom_fmt	format of atom name to use to connect, %e is effective UID, %h is FQDN of display
command	command that may be fed the SOAP document on stdin if connecting via the atom fails, may be NULL

An entry for ROX-Filer is pre-defined. ("ROX-Filer", "_ROX_FILER_%e_%h", "rox -R").

char *rox_soap_atom_name_for_program(const char * name);

Returns the name of the atom which will be used to locate the given program. It uses the format given in the rox_soap_define_program() call, with the defined substitutions. Pass to g_free() when done.

gboolean rox_soap_ping(const char *prog);

Returns TRUE if the named program is contactable via SOAP.

ROXSOAP *rox_soap_connect(const char *prog_name);

Initialise the connection to the named program.

ROXSOAP *rox_soap_connect_to_filer(void);

Initialise the connection to the filer.

gboolean rox_soap_send(ROXSOAP *program, xmlDocPtr doc, gboolean run_prog, rox_soap_callback callback, gpointer udata);

Send the XML document to program using SOAP. If run_prog is TRUE and there is no program to talk to, use rox_soap_send_via_pipe(). Returns TRUE if comms succeeded, when complete callback is called with the status and reply.

gboolean rox_soap_send_via_pipe(ROXSOAP *filer, xmlDocPtr doc, rox_soap_callback callback, gpointer udata);

Send the XML document to the program, using the command defined by rox_soap_define_program(). When complete callback is called with the status and reply.

void rox_soap_set_timeout(ROXSOAP *filer, guint ms);

Set the timeout when contacting ROX-Filer (in ms, defaults to 10000). If filer is NULL it sets the timeout for all new connections.

xmlDocPtr rox_soap_build_xml(const char *action, const char *ns_url, xmlNodePtr *act);

Build part of XML document to send. The action to perform is in name space ns_url. Add arguments to the node act, then call rox_soap_send() with the return value.

const char *rox_soap_get_last_error(void);

Returns the text of the last error raised. This may be "No error" if no error has occured, or rox_soap_clear_error() has been called.

void rox_soap_clear_error(void);

Clears the error text.

void rox_soap_close(ROXSOAP *filer);

Close connection.

rox_filer_action.h

These functions drive ROX-Filer via the rox_soap.h interface above.

typedef enum panel_side { ROXPS_TOP,ROXPS_BOTTOM,ROXPS_LEFT,ROXPS_RIGHT } ROXPanelSide;

The four possible places for a panel, used in rox_filer_panel().

#define ROX_FILER_DEFAULT (-1)

This value means "use value user has selected in options".

char *rox_filer_version(void);

Return the version string for the current filer. Return value should be passed to g_free when done.

void rox_filer_open_dir(const char *filename);

Open a viewer for the given directory.

void rox_filer_close_dir(const char *filename);

Close all viewers for the given directory and any subdirectories.

void rox_filer_examine(const char *filename);

Re-fresh the viewer for the given directory.

void rox_filer_panel(const char *name, ROXPanelSide side);

Open a panel with the given name on the specfied side. If name is "" then the panel on that side is closed instead.

void rox_filer_panel_add(ROXPanelSide side, const char *path, int after);

Add an object to the panel on the specfied side. If after is FALSE then the object is placed on the left (top or bottom panels) or top (left or right panels), otherwise the other end.

void rox_filer_pinboard(const char *name);

Display pinboard name on the desktop background. Name can be a name in Choices (eg, `MyPinboard') or a full pathname.

void rox_filer_pinboard_add(const char *path, int x, int y);

Add an object to the pinboard at the specfied co-ordinates.

void rox_filer_run(const char *filename);

Run filename as if it was clicked on in the filer.

void rox_filer_show(const char *directory, const char *leafname);

Open directory and flash the file leafname inside it.

void rox_filer_copy(const char *from, const char *to, const char *leafname, int quiet);

Copy the object from into the directory to. If leafname is not NULL then use it as the new name of the file. If quiet is FALSE then prompt the user before copying.

void rox_filer_move(const char *from, const char *to, const char *leafname, int quiet);

Move the object from into the directory to. If leafname is not NULL then use it as the new name of the file. If quiet is FALSE then prompt the user before moving.

void rox_filer_link(const char *from, const char *to, const char *leafname);

Symbolically link the object from into the directory to. If leafname is not NULL then use it as the new name of the file.

void rox_filer_mount(const char *mountpoint, int quiet, int opendir);

Attempt to mount on the directory mountpoint (which should be in /etc/fstab or similar). If quiet is FALSE then prompt the user before mounting. If opendir is not FALSE then open a viewer for the new directory if succesfully mounted. The ability to mount is normally restricted.

char *rox_filer_file_type(const char *file);

Return a string describing the MIME type of the given file (which need not exist!). Return value should be passed to g_free when done. If NULL is returned then there was an error in communication.

int rox_filer_have_error(void);

Returns non-zero if an error message is available.

const char *rox_filer_get_last_error(void);

Returns the text of the last error raised. This may be "No error" if no error has occured, or rox_filer_clear_error() has been called.

void rox_filer_clear_error(void);

Clears the error text.

applet.h

Utilities for developing ROX applets.

typedef enum panel_location { PANEL_TOP, PANEL_BOTTOM, PANEL_LEFT, PANEL_RIGHT, PANEL_UNKNOWN } PanelLocation;

Defines the four possible locations for the panel containing the applet, plus an error condition.

extern void applet_popup_menu(GtkWidget *plug, GtkWidget *menu, GdkEventButton *evbut);

Shows a pop-up menu in a suitable place for the applet. It is assumed that this will be called in a button_press handler which is passed a GdkEventButton *. plug is the GtkPlug object which is the applets window.

rox_soap_server.h

Provides a ROX-Filer like SOAP server. Based on the ROX-Filer code written by Thomas Leonard

typedef struct rox_soap_server ROXSOAPServer;

This is an opaque object representing the server.

typedef xmlNodePtr (*rox_soap_server_action)(ROXSOAPServer *server, const char *action_name, GList *args, gpointer udata);

This represents the type of the function called when a SOAP method is executed. Any reply should be returned as an XML node. args is a list of the arguments passed as XML nodes, in the order they were defined in rox_soap_server_add_action() (required, then optional). Optional arguments may be NULL.

typedef struct rox_soap_server_actions ROXSOAPServerActions;

This type is used for an array of SOAP server actions to be passed to rox_soap_server_add_actions(). It is defined as:

typedef struct rox_soap_server_actions {
  const char *action_name;
  const char *args;
  const char *optional_args;
  rox_soap_server_action action;
  gpointer udata;
} ROXSOAPServerActions;

void rox_soap_server_init(void);

Initialise the server routines.

ROXSOAPServer *rox_soap_server_new( const char *program_name, const char *ns_url);

Create a new server object and advertise it via the root window. program_name is the name of the program (see rox_soap_define_program()). ns_url is the name space URL.

void rox_soap_server_add_action( ROXSOAPServer *server, const char *action_name, const char *args, const char *optional_args, rox_soap_server_action action, gpointer udata);

Define a new method (or action) supported by this server. action_name is the name of the action. args is a string of a comma seperated list of arguments, or NULL if there are no required arguments. optional_args is a string of a comma seperated list of arguments, or NULL if there are no optional arguments. action is the function to call when a correctly formatted SOAP message is received.

void rox_soap_server_add_action( ROXSOAPServer *server, ROXSOAPServerActions *actiona);

Define a group of new methods (or actions) supported by this server. actions is the array of action definitions, terminated by an entry with a NULL action_name.

void rox_soap_server_delete( ROXSOAPServer *server);

Shutdown the server and release its memory.

options.h

Options system for configuring your program, similar to ROX-Filer's options. Based on the ROX-Filer code written by Thomas Leonard

typedef struct _Option Option;

Object used to store an option. The following members are used to access the values:

gchar *value

Value of the option, as a string

long int_value

Value of the option, as a number

gboolean has_changed

Non-zero if the option has changed (valid in the OptionNotify callback).

gchar *backup;

Copy of value to Revert to

The other members are used when implementing new widget types.

GtkWidget *widget;

Widget that stores the value

void (*update_widget)(Option *option);

Call to set value

gchar *(*read_widget)(Option *option);

Call to read value

typedef void OptionNotify(void);

Type of function called when options changed (see option_add_notify() below).

typedef GList * (*OptionBuildFn)(Option *option, xmlNode *node, gchar *label);

Type of function used to build widgets (see option_register_widget() below) for the options window. option is the option for which the widget is used. node is the XML node from the Options.xml file describing the widget. label is the label property from the element, to be used as a label. Returns a list of widgets to be added to the window.

void options_init_with_domain(const char *project, const char *domain);

Called to initialize options system. Must be called after choices_init(), but before any other function in the options system. project is the name of the project and is passed to choices functions. domain is also passed to the choices functions and may be NULL.

void options_init(const char *project);

Equivalent to options_init_with_domain(project, NULL).

void option_register_widget(char *name, OptionBuildFn builder);

Registers a new widget type. name is the name of the XML element in the Options.xml file. builder is the function used to build the widget. Pre-defined widget types include:

• label
• spacer
• frame
• toggle
• slider
• entry
• numentry
• radio-group
• colour
• menu
• font

void option_check_widget(Option *option);

This is called when the widget's value is modified by the user. Reads the new value of the widget into the option and calls the notify callbacks.

void option_add_int(Option *option, const gchar *key, int value);

Adds a new option to hold integer values.

void option_add_string(Option *option, const gchar *key, const gchar *value);

Adds a new option to hold string values, including fonts and colours.

void options_notify(void);

Inform watching functions that options have changed.

void option_add_notify(OptionNotify *callback);

Add a callback to be called when options have changed.

GtkWidget *options_show(void);

Show options window. Returns the window widget (you don't normally need this), NULL if already open. This causes the $APP_DIR/Options.xml file to be parsed. This is an XML file containing an 'options' element. This in turn contains 1 or more 'section' element, each with a 'title' property and containing one or more widgets to be built. The 'section' elements can be nested.

Widgets available by default (see option_register_widget() for more) are:

label help=int

A label

hbox [label=str]

vbox [label=str]

spacer

frame label=str

Container for other objects

section title=str

Groups options, can be nested.

toggle name=str label=str

Simple on/off switch

slider name=str label=str min=int max=int fixed=bool showvalue=bool [end=str]

Range of ints. fixed is fixed width. If showvalue then current value shown. end is label after slider widget

entry name=str label=str

Text entry

numentry name=str label=str min=int max=int step=int width=int [unit=str]

Numeric entry. width is number of digits. unit is text to right of widget (units indicator).

radio-group name=str label=str [columns=int]

List of exclusive options. Must contain radio elements

radio label=str value=str

Option for a radio group

colour name=str label=str

Button for colour selector

menu name=str label=str

Option menu. Must contain 'item' elements.

item label=str value=str

Option for an option menu

font name=str label=str override=int

Button for font selector. If override, adds a checkbox to enable the font.

The new window is registered using rox_add_window()

basedir.h

Interface to the XDG Base directory system.

gchar *basedir_save_config_path(const char *resource, const char *leaf)

Returns the pathname of a configuration file to save. This will be in the directory $XDG_CONFIG_HOME (defaulting to $HOME/.config). Eg: basedir_save_config_path("MyApp", "options.dat") -> "/home/myuser/.config/MyApp/options.dat".

The directory $XDG_CONFIG_HOME and the sub-directory resource are created by this call if required.

The parameter leaf may be NULL. If so just the directory part is returned.

basedir_save_config_path("MyApp", NULL) -> "/home/myuser/.config/MyApp".

The return value may be NULL - saving is disabled - otherwise g_free() the result.

gchar *basedir_save_data_path(const char *resource, const char *leaf)

Returns the pathname of a data file to save. This will be in the directory $XDG_DATA_HOME (defaulting to $HOME/.local/share). Eg: basedir_save_data_path("MyApp", "data.dat") -> "/home/myuser/.local/share/MyApp/data.dat".

The directory $XDG_DATA_HOME and the sub-directory resource are created by this call if required.

The parameter leaf may be NULL. If so just the directory part is returned.

basedir_save_data_path("MyApp", NULL) -> "/home/myuser/.local/share/MyApp".

The return value may be NULL - saving is disabled - otherwise g_free() the result.

gchar *basedir_load_config_path(const char *resource, const char *leaf)

Returns the pathname of a configuration file to load. This will be in the directory $XDG_CONFIG_HOME (defaulting to $HOME/.config) or a directory named in $XDG_CONFIG_DIRS (defaulting to /etc/xdg). Eg: basedir_load_config_path("MyApp", "options.dat") -> "/home/myuser/.config/MyApp/options.dat".

The return value may be NULL - meaning the file was not found - otherwise g_free() the result.

gchar *basedir_load_data_path(const char *resource, const char *leaf)

Returns the pathname of a data file to load. This will be in the directory $XDG_DATA_HOME (defaulting to $HOME/.local/share) or a directory named in $XDG_DATA_DIRS (defaulting to /usr/local/share:/usr/share). Eg: basedir_load_data_path("MyApp", "data.dat") -> "/usr/local/share/MyApp/data.dat".

The return value may be NULL - meaning the file was not found - otherwise g_free() the result.

GList *basedir_load_config_paths(const char *resource, const char *leaf)

Returns a list of all the pathnames of existing configuration files to load. This includes the directories $XDG_CONFIG_HOME (defaulting to $HOME/.config) and $XDG_CONFIG_DIRS (defaulting to /etc/xdg).

If leaf is NULL then just the existing configuration directories for resource are returned. If resource is NULL then the existing configuration directories are returned.

The return value may be NULL if no config directories or config files could be found. Otherwise g_free() each list item and g_list_free() the whole list.

GList *basedir_load_data_paths(const char *resource, const char *leaf)

Returns a list of all the pathnames of existing data files to load. This includes the directories $XDG_DATA_HOME (defaulting to $HOME/.local/share) and $XDG_DATA_DIRS (defaulting to /usr/local/share:/usr/share).

If leaf is NULL then just the existing data directories for resource are returned. If resource is NULL then the existing data directories are returned.

The return value may be NULL if no data directories or data files could be found. Otherwise g_free() each list item and g_list_free() the whole list.

mime.h

Interface to the Shared MIME database system.

typedef struct mime_type MIMEType;

This type represents a MIME type. It has a number of members, two of which are public but read-only:

• const char *media;
• const char *subtype;

These are the two parts of the MIME type media/subtype (e.g. text/plain).

extern MIMEType *text_plain;

MIME type representing text/plain files. This is the default for a file under *nix.

This is not valid until mime_init() has been called.

extern MIMEType *application_executable;

MIME type representing application/x-executable files. This represents an executable file.

This is not valid until mime_init() has been called.

extern MIMEType *application_octet_stream;

MIME type representing application/octet-stream files. This represents a non-text binary file.

This is not valid until mime_init() has been called.

extern MIMEType *inode_directory;

MIME type representing inode/directory files. This represents a directory.

This is not valid until mime_init() has been called.

extern MIMEType *inode_mountpoint;

MIME type representing inode/mountpoint files. This represents a directory on which a file system is mounted, or may be mounted according to /etc/fstab. ROX-CLib does not yet recognize such objects.

This is not valid until mime_init() has been called.

extern MIMEType *inode_pipe;

MIME type representing inode/fifo files. This represents a pipe or FIFO object.

This is not valid until mime_init() has been called.

extern MIMEType *inode_socket;

MIME type representing inode/socket files. This represents a socket object.

This is not valid until mime_init() has been called.

extern MIMEType *inode_block;

MIME type representing inode/blockdevice files. This represents a block device object.

This is not valid until mime_init() has been called.

extern MIMEType *inode_char;

MIME type representing inode/char files. This represents a character device object.

This is not valid until mime_init() has been called.

extern MIMEType *inode_door;

MIME type representing inode/door files. This represents a door object (Solaris only).

This is not valid until mime_init() has been called.

extern MIMEType *inode_unknwon;

MIME type representing inode/unknown files. This represents an object which could not be identified (probably missing).

This is not valid until mime_init() has been called.

extern void mime_init(void)

Initializes the MIME system, defines the default types, and loads the lookup database.

extern MIMEType *mime_lookup(const char *path)

Returns the MIME type of the given file. If the file exists then it is first checked for being a non-regular file. If it is regular and by content lookups are enabled the contents of the file is checked. If none of the above identifies the file then the file is identified by its name.

In future a check may be made using extended attributes for a user-defined MIME type. This check will be made on regular files before contents are checked.

The object returned is maintained by the MIME system and should not be freed or modified.

extern MIMEType *mime_lookup_by_name(const char *name)

Returns the MIME type object for the named type. name should be in the form media/subtype.

The object returned is maintained by the MIME system and should not be freed or modified.

extern char *mime_type_name(const MIMEType *type)

Returns the name of the MIME type in the form text/plain. The returned string must be passed to g_free() when done.

extern const char *mime_type_comment(MIMEType *type)

Returns the comment field of the MIME type. This is the human readable name of the type, such as C headers for text/x-chdr. Unlike mime_type_lookup() this call reads one or more files, including /uri/0install/zero-install.sourceforge.net/share and may take some time to complete.

The string returned is maintained by the MIME system and should not be freed or modified.

extern void mime_set_ignore_exec_bit(int ignore)

If ignore is non-zero then mime_type_lookup() will check the name of executable files for determining type and only return application/x-executable if that fails. Otherwise application/x-executable is always returned for files with an executable bit set.

extern int mime_get_ignore_exec_bit(void)

Returns the ignore executable bit flag.

extern void mime_set_by_content(int content)

If content is zero then mime_type_lookup() will not check the contents of the file to determine the type. This is the default.

Currently ignored as by-content lookups are not enabled.

extern int mime_get_by_content(void)

Returns the by content flag.

appinfo.h

An object representing a parsed AppInfo.xml file.

typedef struct _ROXAppInfo ROXAppInfo;

This type represents an AppInfo.xml. It is derived from GObject.

GObject *rox_appinfo_new(void)

This parses the current app's AppInfo.xml file and returns a pointer to a ROXAppInfo object. If $APP_DIR is unset, $APP_DIR/AppInfo.xml is missing or not valid XML then NULL is returned.

You should call g_object_unref() to free this object when done.

GObject *rox_appinfo_new_from_path(const gchar *path)

This parses the named AppInfo.xml file and returns a pointer to a ROXAppInfo object. If path is missing or not valid XML then NULL is returned.

You should call g_object_unref() to free this object when done.

void rox_appinfo_set_language(ROXAppInfo *ai, const gchar *lang)

Set the language used when parsing the AppInfo data. If lang is NULL then the data returned will be that with no language set, otherwise the appropriate elements for the set language will be returned, falling back to the no language elements if the specific language is not found.

const char *rox_appinfo_get_language(ROXAppInfo *ai)

Return the language code used when parsing the AppInfo data. This may be NULL for no language set.

const char *rox_appinfo_get_summary(ROXAppInfo *ai)

Return the contents of the Summary element.

char *rox_appinfo_get_about(ROXAppInfo *ai, const gchar *element)

Return the contents of the named element in the About element. Pass the return value to g_free() when done.

char *rox_appinfo_get_label(ROXAppInfo *ai, const gchar *element)

Return the label for the named element in the About element in the current language. If this is not set or is empty then a copy of element is returned. Pass the return value to g_free() when done.

const xmlNodePtr rox_appinfo_get_element(ROXAppInfo *ai, const gchar *element)

Return the xmlNode object for the named element. Only child elements of the root AppInfo element are searched, no recursive search is performed. NULL is returned if no element was found, otherwise just the first matching entry is returned. Language is not checked.

xmlNodePtr is part of libxml.

GList *rox_appinfo_get_mime_type_list(ROXAppInfo *ai, const gchar *element)

Returns a list of MIMEType * objects. The mime types are listed in <MimeType> elements in the top level element element (found by rox_appinfo_get_element()). See the AppInfo.xml file for VideoThumbnail for an example.

void rox_appinfo_free_mime_type_list( GList *list)

Free a list of MIMEType * objects, as returned by rox_appinfo_get_mime_type_list().

GList *rox_appinfo_get_can_run_list(ROXAppInfo *ai)

Returns a list of MIMEType * objects declared in the <CanRun> element. This is equivalent to rox_appinfo_get_mime_type_list(ai, "CanRun").

GList *rox_appinfo_get_can_thumbnail_list(ROXAppInfo *ai)

Returns a list of MIMEType * objects declared in the <CanThumbnail> element. This is equivalent to rox_appinfo_get_mime_type_list(ai, "CanThumbnail"). See the AppInfo.xml file for VideoThumbnail for an example.