/* Stuff to export relevant entry points from cElementTree */

/* To use this API, do

   struct cElementTree_CAPI *capi;
   capi = PyCObject_Import("cElementTree", "CAPI");

   Also check that capi->magic and capi->size matches the values from
   this header, e.g:
   
   if (strcmp(capi->magic, cElementTree_CAPI_MAGIC) != 0 ||
       capi->size < sizeof(struct cElementTree_CAPI) ||
       capi->version < cElementTree_CAPI_VERSION)
       ... cannot use this version ...

   See below for a summary of the available API functions.

*/

/* major version */
#define cElementTree_CAPI_MAGIC  "cElementTree.CAPI 1.0"

/* minor version. new minor versions should always be backwards compatible */
#define cElementTree_CAPI_VERSION 1

/* struct to store a snapshot of a given Element */
struct cElementTree_Snapshot
{
    /* filled in by snapshot method.  members may be Py_None if not present
       in the internal structure.  all references are new; use DECREF to clean
       up */
    PyObject* tag;
    PyObject* attrib;
    PyObject* text;
    PyObject* tail;
    PyObject* children; /* only filled in if mode > 0 */

    /* always add new stuff to the end! */
};

struct cElementTree_CAPI 
{
    char* magic; /* set to cElementTree_CAPI_MAGIC */
    int size; /* set to sizeof(struct cElementTree_CAPI) */
    int version; /* set to cElementTree_CAPI_VERSION (API version) */

    /* pointers to selected cElementTree helpers.  add new functions at
       the end, if needed */

    /* Element type (to be used for exact type comparisions) */
    PyObject* type;

    /* Check if object is a cElementTree Element, and raises a TypeError
       if not.  Use this before calling other methods. */
    /* Returns 0 if ok, -1 if error. */
    int (*assert)(PyObject* elem);

    /* Get Element snapshot.  Use mode=1 to get children too. */
    /* The 'elem' argument must point to a cElementTree Element.  Use
       'assert' first when in doubt. */
    /* All references are new, and point to stable versions (that is, 
       changing the original Element won't affect the snapshot). */
    /* Py_None may be used for non-existent/empty fields. */
    /* Returns 0 if ok, -1 if error. */
    int (*snapshot)(
        PyObject* elem, struct cElementTree_Snapshot* snapshot, int mode
        );

    /* Get subelement. */
    /* The 'elem' argument must point to a cElementTree Element.  Use
       'assert' first when in doubt. */
    /* Returns a borrowed reference, or Py_None if the element does not
       exist. */
    PyObject* (*getitem)(PyObject* elem, int index);

    /* always add new stuff to the end! */
};