Things to avoid

Structures with custom memory management

Avoid creating C structures with custom _ref/_unref/_free type functions. You have two general choices; a boxed type (this is a value type, it is copied), or a full GObject. GObject is not significantly more typing, and using it gives infrastructure like toggle references that are critical for garbage-collected language bindings.

Example to avoid:

struct _GstMiniObject {
  GTypeInstance instance;
  /*< public >*/ /* with COW */
  gint refcount;
  guint flags;

Functionality only accessible through a C macro

The scanner does not support C macros as API. Solution - add a function accessor rather than a macro. This also has the side effect of making debugging in C code easier.

Example:

#define GTK_WIDGET_FLAGS(wid)             (GTK_OBJECT_FLAGS (wid))

GtkWidgetFlags gtk_widget_get_flags (GtkWidget *widget); /* Actually, see http://bugzilla.gnome.org/show_bug.cgi?id=69872 */

Direct C structure access for objects

Having GObjects also have fields can be difficult to bind. Create accessor functions.

Example:

struct _SoupMessage {
        GObject parent;

        /*< public >*/
        const char         *method;

        guint               status_code;
...
}

const char * soup_message_get_method (SoupMessage *message);  /*  Or use a GObject property */

va_list

Using varargs can be convenient for C, but they are difficult to bind. Solution: Keep the C function for the convenience of C programmers, but add an another function which takes an array (either zero terminated or with a length parameter).

*Good* example:

GtkListStore *gtk_list_store_new              (gint          n_columns,
                                               ...);
GtkListStore *gtk_list_store_newv             (gint          n_columns,
                                               GType        *types);

Multiple out parameters

Multiple out parameters are supported by introspection, but not all languages have an obvious mapping for multiple out values. A boxed structure could serve as an alternative.

Example to think about (here, there could be a boxed struct GtkCoordinate { gint x; gint y; } structure).

void         gtk_widget_get_pointer     (GtkWidget      *widget,
                                         gint           *x,
                                         gint           *y);

Arrays

For reference types, zero-terminated arrays are the easiest to work with. Arrays of primitive type such as "int" will require length metadata.