2 * Copyright (c) 2007-2012 Zmanda, Inc. All Rights Reserved.
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.
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
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
18 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
19 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
22 #ifndef AMANDA_AMGLUE_H
23 #define AMANDA_AMGLUE_H
25 #include "../config/config.h"
30 #include <glib-object.h>
32 /* These defines are missing from older glibs, so we add them here */
34 #define G_MAXINT8 (127)
38 #define G_MININT8 (-127-1)
42 #define G_MAXUINT8 (255)
46 #define G_MAXINT16 (32767)
50 #define G_MININT16 (-32767-1)
54 #define G_MAXUINT16 (65535)
58 #define G_MAXINT32 (2147483647)
62 #define G_MININT32 (-2147483647-1)
66 #define G_MAXUINT32 (4294967295U)
70 * prototypes for ghashtable.c
73 /* Turn a GLib hash table (mapping strings to strings) into a reference
74 * to a Perl hash table.
76 * @param hash: GLib hash table
77 * @returns: Perl hashref
79 SV *g_hash_table_to_hashref(GHashTable *hash);
81 /* Turn a GLib hash table (mapping strings to GSList of strings) into a reference
82 * to a Perl hash table.
84 * @param hash: GLib hash table
85 * @returns: Perl hashref
87 SV *g_hash_table_to_hashref_gslist(GHashTable *hash);
89 /* Turn a GLib hash table (mapping strings to property_t) into a reference
90 * to a Perl hash table.
92 * @param hash: GLib hash table
93 * @returns: Perl hashref
95 SV *g_hash_table_to_hashref_property(GHashTable *hash);
98 * prototypes for gerror.c
101 /* Call perl's croak (die) for a GError (if there is one)
103 * @note This is not thread-safe
104 * @note This function does not return if error is non-NULL
106 * @param domain: String to prefix to error message (followed by ": ")
107 * @param error: The GError pointer
109 void croak_gerror(const char *domain, GError **error);
112 * prototypes for bigint.c
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.
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.
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.
137 * @param v: value to convert
138 * @returns: pointer to a new SV (refcount=1)
140 SV *amglue_newSVi64(gint64 v);
141 SV *amglue_newSVu64(guint64 v);
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.
148 * @param sv: perl value to convert
149 * @returns: value of the given type
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);
161 * prototypes for objwrap.c
164 /* Return a new SV with refcount 1 representing the given C object
165 * with the given class.
167 * @param c_obj: the object to represent
168 * @param perl_class: the perl with which to bless and tie the SV
170 SV * new_sv_for_c_obj(gpointer c_obj, const char *perl_class);
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.
175 * This function is based on SWIG's SWIG_Perl_ConvertPtr. The INT2PTR
176 * situation certainly looks strange, but is documented in perlxs.
178 * @param sv: the SV to convert
179 * @param derived_from: perl class from which the SV should be derived
180 * @return: underlying pointer
182 gpointer c_obj_from_sv(SV *sv, const char *derived_from);
185 * prototypes for xferwrap.c
188 /* declare structs */
192 /* Return a new SV representing a transfer.
194 * @param xfer: the transfer to represent
196 SV *new_sv_for_xfer(struct Xfer *xfer);
198 /* Return a new SV representing a transfer element.
200 * @param xe: the transfer element to represent
202 SV *new_sv_for_xfer_element(struct XferElement *xe);
204 /* Convert an SV to an Xfer. The Xfer's reference count is not
205 * incremented -- this is a "borrowed" reference.
207 * @param sv: the perl value
208 * @returns: pointer to the corresponding transfer, or NULL
210 struct Xfer *xfer_from_sv(SV *sv);
212 /* Convert an SV to an XferElement. The element's reference count is
213 * not incremented -- this is a "borrowed" reference.
215 * @param sv: the perl value
216 * @returns: pointer to the corresponding transfer element, or NULL.
218 struct XferElement *xfer_element_from_sv(SV *sv);
221 * prototypes for source.c
224 typedef enum amglue_Source_state {
226 AMGLUE_SOURCE_ATTACHED,
227 AMGLUE_SOURCE_DESTROYED
228 } amglue_Source_state;
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. */
234 typedef struct amglue_Source {
236 GSourceFunc callback;
238 amglue_Source_state state;
242 /* Get the amglue_Source object associated with this GSource, creating a
243 * new one if necessary, and increment its refcount.
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,
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.
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
260 amglue_Source *amglue_source_get(GSource *gsrc, GSourceFunc callback);
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
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
270 amglue_Source *amglue_source_new(GSource *gsrc, GSourceFunc callback);
272 /* Increment the refcount on an amglue_Source */
273 #define amglue_source_ref(aS) aS->refcount++
275 /* Unref an amglue_Source object, freeing it if its refcount reaches
277 #define amglue_source_unref(aS) if (!--(aS)->refcount) amglue_source_free((aS))
278 void amglue_source_free(amglue_Source *);
280 #endif /* AMANDA_AMGLUE_H */