/*
* Copyright (C) 2003-2005, 2010 by the gtk2-perl team (see the file AUTHORS for
* the full list)
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Library General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or (at your
* option) any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
* License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
* $Id$
*/
#ifndef _GPERL_H_
#define _GPERL_H_
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#ifdef WIN32
/* perl and glib disagree on a few macros... let the wookie win. */
# undef pipe
# undef malloc
# undef realloc
# undef free
#endif
#include <glib-object.h>
/*
* filenames
*/
gchar *gperl_filename_from_sv (SV *sv);
SV *gperl_sv_from_filename (const gchar *filename);
/*
* enums and flags
*/
gboolean gperl_try_convert_enum (GType type, SV * sv, gint * val);
gint gperl_convert_enum (GType type, SV * val);
SV * gperl_convert_back_enum_pass_unknown (GType type, gint val);
SV * gperl_convert_back_enum (GType type, gint val);
gboolean gperl_try_convert_flag (GType type, const char * val_p, gint * val);
gint gperl_convert_flag_one (GType type, const char * val_p);
gint gperl_convert_flags (GType type, SV * val);
SV * gperl_convert_back_flags (GType type, gint val);
/* register a fundamental type (enums, flags...) */
typedef struct _GPerlValueWrapperClass GPerlValueWrapperClass;
typedef SV* (*GPerlValueWrapFunc) (const GValue * value);
typedef void (*GPerlValueUnwrapFunc) (GValue * value,
SV * sv);
struct _GPerlValueWrapperClass {
GPerlValueWrapFunc wrap;
GPerlValueUnwrapFunc unwrap;
};
void gperl_register_fundamental (GType gtype, const char * package);
void gperl_register_fundamental_alias (GType gtype, const char * package);
void gperl_register_fundamental_full (GType gtype, const char * package, GPerlValueWrapperClass * wrapper_class);
GType gperl_fundamental_type_from_package (const char * package);
const char * gperl_fundamental_package_from_type (GType gtype);
GPerlValueWrapperClass * gperl_fundamental_wrapper_class_from_type (GType gtype);
/*
* GErrors as exception objects
*/
/* it is rare that you should ever want or need these two functions. */
SV * gperl_sv_from_gerror (GError * error);
void gperl_gerror_from_sv (SV * sv, GError ** error);
void gperl_register_error_domain (GQuark domain,
GType error_enum,
const char * package);
void gperl_croak_gerror (const char * ignored, GError * err);
/*
* inheritance management
*/
/* push @{$parent_package}::ISA, $child_package */
void gperl_set_isa (const char * child_package, const char * parent_package);
/* unshift @{$parent_package}::ISA, $child_package */
void gperl_prepend_isa (const char * child_package, const char * parent_package);
/* these work regardless of what the actual type is (GBoxed, GObject, GEnum,
* or GFlags). in general it's safer to use the most specific one, but this
* is handy when you don't care. */
GType gperl_type_from_package (const char * package);
const char * gperl_package_from_type (GType type);
/*
* we need a GBoxed wrapper for a generic SV, so we can store SVs
* in GObjects reliably.
*/
#define GPERL_TYPE_SV (gperl_sv_get_type ())
GType gperl_sv_get_type (void) G_GNUC_CONST;
SV * gperl_sv_copy (SV * sv);
void gperl_sv_free (SV * sv);
/*
* clean function wrappers for treating gchar* as UTF8 strings, in the
* same idiom as the rest of the cast macros. these are wrapped up
* as functions because comma expressions in macros get kinda tricky.
*/
/*const*/ gchar * SvGChar (SV * sv);
SV * newSVGChar (const gchar * str);
/*
* 64 bit integer converters
*/
gint64 SvGInt64 (SV *sv);
SV * newSVGInt64 (gint64 value);
guint64 SvGUInt64 (SV *sv);
SV * newSVGUInt64 (guint64 value);
/*
* GValues
*/
gboolean gperl_value_from_sv (GValue * value, SV * sv);
SV * gperl_sv_from_value (const GValue * value);
/*
* GBoxed
*/
typedef struct _GPerlBoxedWrapperClass GPerlBoxedWrapperClass;
typedef SV* (*GPerlBoxedWrapFunc) (GType gtype,
const char * package,
gpointer boxed,
gboolean own);
typedef gpointer (*GPerlBoxedUnwrapFunc) (GType gtype,
const char * package,
SV * sv);
typedef void (*GPerlBoxedDestroyFunc) (SV * sv);
struct _GPerlBoxedWrapperClass {
GPerlBoxedWrapFunc wrap;
GPerlBoxedUnwrapFunc unwrap;
GPerlBoxedDestroyFunc destroy;
};
GPerlBoxedWrapperClass * gperl_default_boxed_wrapper_class (void);
void gperl_register_boxed (GType gtype,
const char * package,
GPerlBoxedWrapperClass * wrapper_class);
void gperl_register_boxed_alias (GType gtype, const char * package);
void gperl_register_boxed_synonym (GType registered_gtype, GType synonym_gtype);
SV * gperl_new_boxed (gpointer boxed, GType gtype, gboolean own);
SV * gperl_new_boxed_copy (gpointer boxed, GType gtype);
gpointer gperl_get_boxed_check (SV * sv, GType gtype);
GType gperl_boxed_type_from_package (const char * package);
const char * gperl_boxed_package_from_type (GType type);
/*
* GObject
*/
void gperl_register_object (GType gtype, const char * package);
void gperl_register_object_alias (GType gtype, const char * package);
typedef void (*GPerlObjectSinkFunc) (GObject *);
void gperl_register_sink_func (GType gtype,
GPerlObjectSinkFunc func);
void gperl_object_set_no_warn_unreg_subclass (GType gtype, gboolean nowarn);
const char * gperl_object_package_from_type (GType gtype);
HV * gperl_object_stash_from_type (GType gtype);
GType gperl_object_type_from_package (const char * package);
SV * gperl_new_object (GObject * object, gboolean own);
GObject * gperl_get_object (SV * sv);
GObject * gperl_get_object_check (SV * sv, GType gtype);
SV * gperl_object_check_type (SV * sv, GType gtype);
void _gperl_attach_mg (SV * sv, void * ptr);
MAGIC * _gperl_find_mg (SV * sv);
void _gperl_remove_mg (SV * sv);
/* typedefs and macros for use with the typemap */
typedef gchar gchar_length; /* length in bytes */
typedef gchar gchar_utf8_length; /* length in characters */
typedef gchar gchar_own;
typedef gchar gchar_ornull;
typedef gchar gchar_own_ornull;
typedef char char_ornull;
typedef char char_own;
typedef char char_own_ornull;
typedef GObject GObject_ornull;
typedef GObject GObject_noinc;
typedef gchar *GPerlFilename;
typedef const gchar *GPerlFilename_const;
typedef gchar *GPerlFilename_own;
typedef GPerlFilename GPerlFilename_ornull;
typedef GParamSpec GParamSpec_ornull;
#define newSVGObject(obj) (gperl_new_object ((obj), FALSE))
#define newSVGObject_noinc(obj) (gperl_new_object ((obj), TRUE))
#define SvGObject(sv) (gperl_get_object_check (sv, G_TYPE_OBJECT))
#define SvGObject_ornull(sv) (gperl_sv_is_defined (sv) ? SvGObject (sv) : NULL)
#define newSVGParamSpec_ornull(sv) newSVGParamSpec(sv)
/*
* GSignal.xs
*/
SV * newSVGSignalFlags (GSignalFlags flags);
GSignalFlags SvGSignalFlags (SV * sv);
SV * newSVGSignalInvocationHint (GSignalInvocationHint * ihint);
SV * newSVGSignalQuery (GSignalQuery * query);
void gperl_signal_set_marshaller_for (GType instance_type,
char * detailed_signal,
GClosureMarshal marshaller);
gulong gperl_signal_connect (SV * instance,
char * detailed_signal,
SV * callback,
SV * data,
GConnectFlags flags);
/*
* GClosure
*/
typedef struct _GPerlClosure GPerlClosure;
struct _GPerlClosure {
GClosure closure;
SV * callback;
SV * data; /* callback data */
gboolean swap; /* TRUE if target and data are to be swapped */
int id;
};
/* evaluates to true if the instance and data are to be swapped on invocation */
#define GPERL_CLOSURE_SWAP_DATA(gpc) ((gpc)->swap)
/* this is the one you want. */
GClosure * gperl_closure_new (SV * callback,
SV * data,
gboolean swap);
/* very scary, use only if you really know what you are doing */
GClosure * gperl_closure_new_with_marshaller (SV * callback,
SV * data,
gboolean swap,
GClosureMarshal marshaller);
/*
* GPerlCallback
*/
typedef struct _GPerlCallback GPerlCallback;
struct _GPerlCallback {
gint n_params;
GType * param_types;
GType return_type;
SV * func;
SV * data;
void * priv;
};
GPerlCallback * gperl_callback_new (SV * func,
SV * data,
gint n_params,
GType param_types[],
GType return_type);
void gperl_callback_destroy (GPerlCallback * callback);
void gperl_callback_invoke (GPerlCallback * callback,
GValue * return_value,
...);
/*
* exception handling
*/
int gperl_install_exception_handler (GClosure * closure);
void gperl_remove_exception_handler (guint tag);
void gperl_run_exception_handlers (void);
/*
* to be used by extensions...
*/
gint gperl_handle_logs_for (const gchar * log_domain);
/*
* gparamspec.h / GParamSpec.xs
*/
SV * newSVGParamSpec (GParamSpec * pspec);
GParamSpec * SvGParamSpec (SV * sv);
SV * newSVGParamFlags (GParamFlags flags);
GParamFlags SvGParamFlags (SV * sv);
void gperl_register_param_spec (GType gtype, const char * package);
const char * gperl_param_spec_package_from_type (GType gtype);
GType gperl_param_spec_type_from_package (const char * package);
/*
* gkeyfile.h / GKeyFile.xs
*/
#if GLIB_CHECK_VERSION (2, 6, 0)
SV * newSVGKeyFile (GKeyFile * key_file);
GKeyFile * SvGKeyFile (SV * sv);
SV * newSVGKeyFileFlags (GKeyFileFlags flags);
GKeyFileFlags SvGKeyFileFlags (SV * sv);
#endif /* GLIB_CHECK_VERSION (2, 6, 0) */
/*
* gbookmarkfile.h / GBookmarkFile.xs
*/
#if GLIB_CHECK_VERSION (2, 12, 0)
SV * newSVGBookmarkFile (GBookmarkFile * bookmark_file);
GBookmarkFile * SvGBookmarkFile (SV * sv);
#endif /* GLIB_CHECK_VERSION (2, 12, 0) */
#if GLIB_CHECK_VERSION (2, 6, 0)
/*
* GOption.xs
*/
typedef GOptionContext GOptionContext_own;
#define GPERL_TYPE_OPTION_CONTEXT (gperl_option_context_get_type ())
GType gperl_option_context_get_type (void);
#define SvGOptionContext(sv) (gperl_get_boxed_check ((sv), GPERL_TYPE_OPTION_CONTEXT))
#define newSVGOptionContext(val) (gperl_new_boxed ((gpointer) (val), GPERL_TYPE_OPTION_CONTEXT, FALSE))
#define newSVGOptionContext_own(val) (gperl_new_boxed ((gpointer) (val), GPERL_TYPE_OPTION_CONTEXT, TRUE))
typedef GOptionGroup GOptionGroup_own;
#define GPERL_TYPE_OPTION_GROUP (gperl_option_group_get_type ())
GType gperl_option_group_get_type (void);
#define SvGOptionGroup(sv) (gperl_get_boxed_check ((sv), GPERL_TYPE_OPTION_GROUP))
#define newSVGOptionGroup(val) (gperl_new_boxed ((gpointer) (val), GPERL_TYPE_OPTION_GROUP, FALSE))
#define newSVGOptionGroup_own(val) (gperl_new_boxed ((gpointer) (val), GPERL_TYPE_OPTION_GROUP, TRUE))
#endif /* 2.6.0 */
/*
* gutils.h / GUtils.xs
*/
#if GLIB_CHECK_VERSION (2, 14, 0)
GUserDirectory SvGUserDirectory (SV *sv);
SV * newSVGUserDirectory (GUserDirectory dir);
#endif
/*
* miscellaneous
*/
/* never use this function directly. use GPERL_CALL_BOOT. */
void _gperl_call_XS (pTHX_ void (*subaddr) (pTHX_ CV *), CV * cv, SV ** mark);
/*
* call the boot code of a module by symbol rather than by name.
*
* in a perl extension which uses several xs files but only one pm, you
* need to bootstrap the other xs files in order to get their functions
* exported to perl. if the file has MODULE = Foo::Bar, the boot symbol
* would be boot_Foo__Bar.
*/
#ifndef XS_EXTERNAL
# define XS_EXTERNAL(name) XS(name)
#endif
#define GPERL_CALL_BOOT(name) \
{ \
extern XS_EXTERNAL (name); \
_gperl_call_XS (aTHX_ name, cv, mark); \
}
gpointer gperl_alloc_temp (int nbytes);
gboolean gperl_str_eq (const char * a, const char * b);
guint gperl_str_hash (gconstpointer key);
typedef struct {
int argc;
char **argv;
char **shadow;
} GPerlArgv;
GPerlArgv * gperl_argv_new ();
void gperl_argv_update (GPerlArgv *pargv);
void gperl_argv_free (GPerlArgv *pargv);
char * gperl_format_variable_for_output (SV * sv);
gboolean gperl_sv_is_defined (SV *sv);
#define gperl_sv_is_ref(sv) \
(gperl_sv_is_defined (sv) && SvROK (sv))
#define gperl_sv_is_array_ref(sv) \
(gperl_sv_is_ref (sv) && SvTYPE (SvRV(sv)) == SVt_PVAV)
#define gperl_sv_is_code_ref(sv) \
(gperl_sv_is_ref (sv) && SvTYPE (SvRV(sv)) == SVt_PVCV)
#define gperl_sv_is_hash_ref(sv) \
(gperl_sv_is_ref (sv) && SvTYPE (SvRV(sv)) == SVt_PVHV)
void gperl_hv_take_sv (HV *hv, const char *key, size_t key_length, SV *sv);
/* helper wrapper for static string literals. concatenating with "" enforces
* the restriction. */
#define gperl_hv_take_sv_s(hv, key, sv) \
gperl_hv_take_sv (hv, "" key "", sizeof(key) - 1, sv)
/* internal trickery */
gpointer gperl_type_class (GType type);
/*
* helpful debugging stuff
*/
#define GPERL_OBJECT_VITALS(o) \
((o) \
? form ("%s(%p)[%d]", G_OBJECT_TYPE_NAME (o), (o), \
G_OBJECT (o)->ref_count) \
: "NULL")
#define GPERL_WRAPPER_VITALS(w) \
((SvTRUE (w)) \
? ((SvROK (w)) \
? form ("SvRV(%p)->%s(%p)[%d]", (w), \
sv_reftype (SvRV (w), TRUE), \
SvRV (w), SvREFCNT (SvRV (w))) \
: "[not a reference!]") \
: "undef")
#endif /* _GPERL_H_ */