git.gag.com Git - debian/amanda/blob - perl/amglue/amglue.h

   1 /*
   2  * Copyright (c) 2007-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17  *
  18  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  19  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  20  */
  21
  22 #ifndef AMANDA_AMGLUE_H
  23 #define AMANDA_AMGLUE_H
  24
  25 #include "../config/config.h"
  26 #include "EXTERN.h"
  27 #include "perl.h"
  28 #include "XSUB.h"
  29 #include <glib.h>
  30 #include <glib-object.h>
  31
  32 /* These defines are missing from older glibs, so we add them here */
  33 #ifndef G_MAXINT8
  34 #define G_MAXINT8 (127)
  35 #endif
  36
  37 #ifndef G_MININT8
  38 #define G_MININT8 (-127-1)
  39 #endif
  40
  41 #ifndef G_MAXUINT8
  42 #define G_MAXUINT8 (255)
  43 #endif
  44
  45 #ifndef G_MAXINT16
  46 #define G_MAXINT16 (32767)
  47 #endif
  48
  49 #ifndef G_MININT16
  50 #define G_MININT16 (-32767-1)
  51 #endif
  52
  53 #ifndef G_MAXUINT16
  54 #define G_MAXUINT16 (65535)
  55 #endif
  56
  57 #ifndef G_MAXINT32
  58 #define G_MAXINT32 (2147483647)
  59 #endif
  60
  61 #ifndef G_MININT32
  62 #define G_MININT32 (-2147483647-1)
  63 #endif
  64
  65 #ifndef G_MAXUINT32
  66 #define G_MAXUINT32 (4294967295U)
  67 #endif
  68
  69 /*
  70  * prototypes for ghashtable.c
  71  */
  72
  73 /* Turn a GLib hash table (mapping strings to strings) into a reference
  74  * to a Perl hash table.
  75  *
  76  * @param hash: GLib hash table
  77  * @returns: Perl hashref
  78  */
  79 SV *g_hash_table_to_hashref(GHashTable *hash);
  80
  81 /* Turn a GLib hash table (mapping strings to GSList of strings) into a reference
  82  * to a Perl hash table.
  83  *
  84  * @param hash: GLib hash table
  85  * @returns: Perl hashref
  86  */
  87 SV *g_hash_table_to_hashref_gslist(GHashTable *hash);
  88
  89 /* Turn a GLib hash table (mapping strings to property_t) into a reference
  90  * to a Perl hash table.
  91  *
  92  * @param hash: GLib hash table
  93  * @returns: Perl hashref
  94  */
  95 SV *g_hash_table_to_hashref_property(GHashTable *hash);
  96
  97 /*
  98  * prototypes for gerror.c
  99  */
 100
 101 /* Call perl's croak (die) for a GError (if there is one)
 102  *
 103  * @note This is not thread-safe
 104  * @note This function does not return if error is non-NULL
 105  *
 106  * @param domain: String to prefix to error message (followed by ": ")
 107  * @param error: The GError pointer
 108  */
 109 void croak_gerror(const char *domain, GError **error);
 110
 111 /*
 112  * prototypes for bigint.c
 113  */
 114
 115 /*
 116  * These functions handle conversion of integers to and from Perl-compatible
 117  * values.  Most perls do not natively support 64-bit integers, so these functions
 118  * interface with the Math::BigInt module to support those integers.  The functions
 119  * also handle conversions from floating-point to integer values, with silent fraction
 120  * truncation, as perl automatically promotes integers to doubles on overflow.
 121  */
 122
 123 /* Convert an (unsigned) integer to a Perl SV.  These will always produce a
 124  * Math::BigInt object.  Any failure is fatal.  *All* C-to-Perl integer conversions
 125  * must use these functions.
 126  *
 127  * NOTE - NOTE - NOTE
 128  *
 129  * Due to the way SWIG constructs return values, *any* outgoing typemap (out or
 130  * argout) must use the following syntax:
 131  *   SP += argvi; PUTBACK;
 132  *   $result = sv_2mortal(amglue_newSVi64(...));
 133  *   SPAGAIN; SP -= argvi; argvi++;
 134  * This has the effect of saving the arguments added to the perl stack so far, by
 135  * setting the global perl stack to a point above them.
 136  *
 137  * @param v: value to convert
 138  * @returns: pointer to a new SV (refcount=1)
 139  */
 140 SV *amglue_newSVi64(gint64 v);
 141 SV *amglue_newSVu64(guint64 v);
 142
 143 /* Convert a Perl SV to an integer of the specified size.  These functions should
 144  * be used for *all* Perl-to-C integer conversions, since the Perl value may be a
 145  * Math::BigInt object.  All of these functions will call croak() on an overflow
 146  * condition, rather than silently truncate.
 147  *
 148  * @param sv: perl value to convert
 149  * @returns: value of the given type
 150  */
 151 gint64 amglue_SvI64(SV *sv);
 152 guint64 amglue_SvU64(SV *sv);
 153 gint32 amglue_SvI32(SV *sv);
 154 guint32 amglue_SvU32(SV *sv);
 155 gint16 amglue_SvI16(SV *sv);
 156 guint16 amglue_SvU16(SV *sv);
 157 gint8 amglue_SvI8(SV *sv);
 158 guint8 amglue_SvU8(SV *sv);
 159
 160 /*
 161  * prototypes for objwrap.c
 162  */
 163
 164 /* Return a new SV with refcount 1 representing the given C object
 165  * with the given class.
 166  *
 167  * @param c_obj: the object to represent
 168  * @param perl_class: the perl with which to bless and tie the SV
 169  */
 170 SV * new_sv_for_c_obj(gpointer c_obj, const char *perl_class);
 171
 172 /* Return the C object buried in an SV, asserting that the perl SV is
 173  * derived from derived_from.  Returns NULL for undefined perl values.
 174  *
 175  * This function is based on SWIG's SWIG_Perl_ConvertPtr.  The INT2PTR
 176  * situation certainly looks strange, but is documented in perlxs.
 177  *
 178  * @param sv: the SV to convert
 179  * @param derived_from: perl class from which the SV should be derived
 180  * @return: underlying pointer
 181  */
 182 gpointer c_obj_from_sv(SV *sv, const char *derived_from);
 183
 184 /*
 185  * prototypes for xferwrap.c
 186  */
 187
 188 /* declare structs */
 189 struct Xfer;
 190 struct XferElement;
 191
 192 /* Return a new SV representing a transfer.
 193  *
 194  * @param xfer: the transfer to represent
 195  */
 196 SV *new_sv_for_xfer(struct Xfer *xfer);
 197
 198 /* Return a new SV representing a transfer element.
 199  *
 200  * @param xe: the transfer element to represent
 201  */
 202 SV *new_sv_for_xfer_element(struct XferElement *xe);
 203
 204 /* Convert an SV to an Xfer.  The Xfer's reference count is not
 205  * incremented -- this is a "borrowed" reference.
 206  *
 207  * @param sv: the perl value
 208  * @returns: pointer to the corresponding transfer, or NULL
 209  */
 210 struct Xfer *xfer_from_sv(SV *sv);
 211
 212 /* Convert an SV to an XferElement.  The element's reference count is
 213  * not incremented -- this is a "borrowed" reference.
 214  *
 215  * @param sv: the perl value
 216  * @returns: pointer to the corresponding transfer element, or NULL.
 217  */
 218 struct XferElement *xfer_element_from_sv(SV *sv);
 219
 220 /*
 221  * prototypes for source.c
 222  */
 223
 224 typedef enum amglue_Source_state {
 225     AMGLUE_SOURCE_NEW,
 226     AMGLUE_SOURCE_ATTACHED,
 227     AMGLUE_SOURCE_DESTROYED
 228 } amglue_Source_state;
 229
 230 /* There is *one* amglue_Source object for each GSource; this
 231  * allows us to attach amglue-related information to the
 232  * GSource.  See amglue/source.c for more detail. */
 233
 234 typedef struct amglue_Source {
 235     GSource *src;
 236     GSourceFunc callback;
 237     gint refcount;
 238     amglue_Source_state state;
 239     SV *callback_sv;
 240 } amglue_Source;
 241
 242 /* Get the amglue_Source object associated with this GSource, creating a
 243  * new one if necessary, and increment its refcount.
 244  *
 245  * The 'callback' parameter should be a C function with the
 246  * appropriate signature for this GSource.  The callback will
 247  * be given the amglue_Source as its 'data' argument, and should
 248  * invoke its callback_sv as a Perl sub with the appropriate
 249  * parameters.  Simple GSources can use amglue_source_callback_simple,
 250  * below.
 251  *
 252  * This amglue_Source object can be returned directly to perl via a
 253  * SWIG binding; it will be bound as an Amanda::MainLoop::Source
 254  * object, and its memory management will be handled correctly.
 255  *
 256  * @param gsrc: the GSource object to wrap
 257  * @param callback: function to trigger a perl callback
 258  * @returns: an amglue_Source with appropriate refcount
 259  */
 260 amglue_Source *amglue_source_get(GSource *gsrc, GSourceFunc callback);
 261
 262 /* Create a new amglue_Source object for this GSource.  Use this when
 263  * the GSource was just created and does not yet have a corresponding
 264  * amglue_Source.
 265  *
 266  * @param gsrc: the GSource object to wrap
 267  * @param callback: function to trigger a perl callback
 268  * @returns: an amglue_Source with appropriate refcount
 269  */
 270 amglue_Source *amglue_source_new(GSource *gsrc, GSourceFunc callback);
 271
 272 /* Increment the refcount on an amglue_Source */
 273 #define amglue_source_ref(aS) aS->refcount++
 274
 275 /* Unref an amglue_Source object, freeing it if its refcount reaches
 276  * zero.  */
 277 #define amglue_source_unref(aS) if (!--(aS)->refcount) amglue_source_free((aS))
 278 void amglue_source_free(amglue_Source *);
 279
 280 #endif /* AMANDA_AMGLUE_H */