Modules/_ctypes/ctypes.h

   1 /*****************************************************************
   2   This file should be kept compatible with Python 2.3, see PEP 291.
   3  *****************************************************************/
   4
   5 #if (PY_VERSION_HEX < 0x02050000)
   6 typedef int Py_ssize_t;
   7 #endif
   8
   9 #ifndef MS_WIN32
  10 #define max(a, b) ((a) > (b) ? (a) : (b))
  11 #define min(a, b) ((a) < (b) ? (a) : (b))
  12
  13 #define PARAMFLAG_FIN 0x1
  14 #define PARAMFLAG_FOUT 0x2
  15 #define PARAMFLAG_FLCID 0x4
  16 #endif
  17
  18 /*
  19   Backwards compatibility:
  20   Python2.2 used LONG_LONG instead of PY_LONG_LONG
  21 */
  22 #if defined(HAVE_LONG_LONG) && !defined(PY_LONG_LONG)
  23 #define PY_LONG_LONG LONG_LONG
  24 #endif
  25
  26 typedef struct tagCDataObject CDataObject;
  27 typedef PyObject *(* GETFUNC)(void *, unsigned size);
  28 typedef PyObject *(* SETFUNC)(void *, PyObject *value, unsigned size);
  29
  30 /* A default buffer in CDataObject, which can be used for small C types.  If
  31 this buffer is too small, PyMem_Malloc will be called to create a larger one,
  32 and this one is not used.
  33
  34 Making CDataObject a variable size object would be a better solution, but more
  35 difficult in the presence of CFuncPtrObject.  Maybe later.
  36 */
  37 union value {
  38                 char c[16];
  39                 short s;
  40                 int i;
  41                 long l;
  42                 float f;
  43                 double d;
  44 #ifdef HAVE_LONG_LONG
  45                 PY_LONG_LONG ll;
  46 #endif
  47 };
  48
  49 /*
  50   Hm. Are there CDataObject's which do not need the b_objects member?  In
  51   this case we probably should introduce b_flags to mark it as present...  If
  52   b_objects is not present/unused b_length is unneeded as well.
  53 */
  54
  55 struct tagCDataObject {
  56         PyObject_HEAD
  57         char *b_ptr;            /* pointer to memory block */
  58         int  b_needsfree;       /* need _we_ free the memory? */
  59         CDataObject *b_base;    /* pointer to base object or NULL */
  60         Py_ssize_t b_size;      /* size of memory block in bytes */
  61         Py_ssize_t b_length;    /* number of references we need */
  62         Py_ssize_t b_index;     /* index of this object into base's
  63                                    b_object list */
  64         PyObject *b_objects;    /* dictionary of references we need to keep, or Py_None */
  65         union value b_value;
  66 };
  67
  68 typedef struct {
  69         ffi_closure *pcl; /* the C callable */
  70         ffi_cif cif;
  71         PyObject *converters;
  72         PyObject *callable;
  73         SETFUNC setfunc;
  74         ffi_type *restype;
  75         ffi_type *atypes[0];
  76 } ffi_info;
  77
  78 typedef struct {
  79         /* First part identical to tagCDataObject */
  80         PyObject_HEAD
  81         char *b_ptr;            /* pointer to memory block */
  82         int  b_needsfree;       /* need _we_ free the memory? */
  83         CDataObject *b_base;    /* pointer to base object or NULL */
  84         Py_ssize_t b_size;      /* size of memory block in bytes */
  85         Py_ssize_t b_length;    /* number of references we need */
  86         Py_ssize_t b_index;     /* index of this object into base's
  87                                    b_object list */
  88         PyObject *b_objects;    /* list of references we need to keep */
  89         union value b_value;
  90         /* end of tagCDataObject, additional fields follow */
  91
  92         ffi_info *thunk;
  93         PyObject *callable;
  94
  95         /* These two fields will override the ones in the type's stgdict if
  96            they are set */
  97         PyObject *converters;
  98         PyObject *argtypes;
  99         PyObject *restype;
 100         PyObject *checker;
 101         PyObject *errcheck;
 102 #ifdef MS_WIN32
 103         int index;
 104         GUID *iid;
 105 #endif
 106         PyObject *paramflags;
 107 } CFuncPtrObject;
 108
 109 extern PyTypeObject StgDict_Type;
 110 #define StgDict_CheckExact(v)       ((v)->ob_type == &StgDict_Type)
 111 #define StgDict_Check(v)            PyObject_TypeCheck(v, &StgDict_Type)
 112
 113 extern int StructUnionType_update_stgdict(PyObject *fields, PyObject *type, int isStruct);
 114 extern int PyType_stginfo(PyTypeObject *self, Py_ssize_t *psize, Py_ssize_t *palign, Py_ssize_t *plength);
 115 extern int PyObject_stginfo(PyObject *self, Py_ssize_t *psize, Py_ssize_t *palign, Py_ssize_t *plength);
 116
 117
 118
 119 extern PyTypeObject CData_Type;
 120 #define CDataObject_CheckExact(v)       ((v)->ob_type == &CData_Type)
 121 #define CDataObject_Check(v)            PyObject_TypeCheck(v, &CData_Type)
 122
 123 extern PyTypeObject SimpleType_Type;
 124 #define SimpleTypeObject_CheckExact(v)  ((v)->ob_type == &SimpleType_Type)
 125 #define SimpleTypeObject_Check(v)       PyObject_TypeCheck(v, &SimpleType_Type)
 126
 127 extern PyTypeObject CField_Type;
 128 extern struct fielddesc *getentry(char *fmt);
 129
 130
 131 extern PyObject *
 132 CField_FromDesc(PyObject *desc, int index,
 133                 int *pfield_size, int bitsize, int *pbitofs,
 134                 int *psize, int *poffset, int *palign,
 135                 int pack, int is_big_endian);
 136
 137 extern PyObject *CData_AtAddress(PyObject *type, void *buf);
 138 extern PyObject *CData_FromBytes(PyObject *type, char *data, Py_ssize_t length);
 139
 140 extern PyTypeObject ArrayType_Type;
 141 extern PyTypeObject Array_Type;
 142 extern PyTypeObject PointerType_Type;
 143 extern PyTypeObject Pointer_Type;
 144 extern PyTypeObject CFuncPtr_Type;
 145 extern PyTypeObject CFuncPtrType_Type;
 146 extern PyTypeObject StructType_Type;
 147
 148 #define ArrayTypeObject_Check(v)        PyObject_TypeCheck(v, &ArrayType_Type)
 149 #define ArrayObject_Check(v)            PyObject_TypeCheck(v, &Array_Type)
 150 #define PointerObject_Check(v)          PyObject_TypeCheck(v, &Pointer_Type)
 151 #define PointerTypeObject_Check(v)      PyObject_TypeCheck(v, &PointerType_Type)
 152 #define CFuncPtrObject_Check(v)         PyObject_TypeCheck(v, &CFuncPtr_Type)
 153 #define CFuncPtrTypeObject_Check(v)     PyObject_TypeCheck(v, &CFuncPtrType_Type)
 154 #define StructTypeObject_Check(v)       PyObject_TypeCheck(v, &StructType_Type)
 155
 156 extern PyObject *
 157 CreateArrayType(PyObject *itemtype, Py_ssize_t length);
 158
 159 extern void init_callbacks_in_module(PyObject *m);
 160
 161 extern PyMethodDef module_methods[];
 162
 163 extern ffi_info *AllocFunctionCallback(PyObject *callable,
 164                                        PyObject *converters,
 165                                        PyObject *restype,
 166                                        int stdcall);
 167 /* a table entry describing a predefined ctypes type */
 168 struct fielddesc {
 169         char code;
 170         SETFUNC setfunc;
 171         GETFUNC getfunc;
 172         ffi_type *pffi_type; /* always statically allocated */
 173         SETFUNC setfunc_swapped;
 174         GETFUNC getfunc_swapped;
 175 };
 176
 177 typedef struct {
 178         PyObject_HEAD
 179         Py_ssize_t offset;
 180         Py_ssize_t size;
 181         Py_ssize_t index;               /* Index into CDataObject's
 182                                            object array */
 183         PyObject *proto;                /* a type or NULL */
 184         GETFUNC getfunc;                /* getter function if proto is NULL */
 185         SETFUNC setfunc;                /* setter function if proto is NULL */
 186         int anonymous;
 187 } CFieldObject;
 188
 189 /* A subclass of PyDictObject, used as the instance dictionary of ctypes
 190    metatypes */
 191 typedef struct {
 192         PyDictObject dict;      /* first part identical to PyDictObject */
 193 /* The size and align fields are unneeded, they are in ffi_type as well.  As
 194    an experiment shows, it's trivial to get rid of them, the only thing to
 195    remember is that in ArrayType_new the ffi_type fields must be filled in -
 196    so far it was unneeded because libffi doesn't support arrays at all
 197    (because they are passed as pointers to function calls anyway).  But it's
 198    too much risk to change that now, and there are other fields which doen't
 199    belong into this structure anyway.  Maybe in ctypes 2.0... (ctypes 2000?)
 200 */
 201         Py_ssize_t size;        /* number of bytes */
 202         Py_ssize_t align;       /* alignment requirements */
 203         Py_ssize_t length;      /* number of fields */
 204         ffi_type ffi_type_pointer;
 205         PyObject *proto;        /* Only for Pointer/ArrayObject */
 206         SETFUNC setfunc;        /* Only for simple objects */
 207         GETFUNC getfunc;        /* Only for simple objects */
 208
 209         /* Following fields only used by CFuncPtrType_Type instances */
 210         PyObject *argtypes;     /* tuple of CDataObjects */
 211         PyObject *converters;   /* tuple([t.from_param for t in argtypes]) */
 212         PyObject *restype;      /* CDataObject or NULL */
 213         PyObject *checker;
 214         int flags;              /* calling convention and such */
 215 } StgDictObject;
 216
 217 /****************************************************************
 218  StgDictObject fields
 219
 220  setfunc and getfunc is only set for simple data types, it is copied from the
 221  corresponding fielddesc entry.  These are functions to set and get the value
 222  in a memory block.
 223  They should probably by used by other types as well.
 224
 225  proto is only used for Pointer and Array types - it points to the item type
 226  object.
 227
 228  Probably all the magic ctypes methods (like from_param) should have C
 229  callable wrappers in the StgDictObject.  For simple data type, for example,
 230  the fielddesc table could have entries for C codec from_param functions or
 231  other methods as well, if a subtype overrides this method in Python at
 232  construction time, or assigns to it later, tp_setattro should update the
 233  StgDictObject function to a generic one.
 234
 235  Currently, CFuncPtr types have 'converters' and 'checker' entries in their
 236  type dict.  They are only used to cache attributes from other entries, whihc
 237  is wrong.
 238
 239  One use case is the .value attribute that all simple types have.  But some
 240  complex structures, like VARIANT, represent a single value also, and should
 241  have this attribute.
 242
 243  Another use case is a _check_retval_ function, which is called when a ctypes
 244  type is used as return type of a function to validate and compute the return
 245  value.
 246
 247  Common ctypes protocol:
 248
 249   - setfunc: store a python value in a memory block
 250   - getfunc: convert data from a memory block into a python value
 251
 252   - checkfunc: validate and convert a return value from a function call
 253   - toparamfunc: convert a python value into a function argument
 254
 255 *****************************************************************/
 256
 257 /* May return NULL, but does not set an exception! */
 258 extern StgDictObject *PyType_stgdict(PyObject *obj);
 259
 260 /* May return NULL, but does not set an exception! */
 261 extern StgDictObject *PyObject_stgdict(PyObject *self);
 262
 263 extern int StgDict_clone(StgDictObject *src, StgDictObject *dst);
 264
 265 typedef int(* PPROC)(void);
 266
 267 PyObject *_CallProc(PPROC pProc,
 268                     PyObject *arguments,
 269 #ifdef MS_WIN32
 270                     IUnknown *pIUnk,
 271                     GUID *iid,
 272 #endif
 273                     int flags,
 274                     PyObject *argtypes,
 275                     PyObject *restype,
 276                     PyObject *checker);
 277
 278
 279 #define FUNCFLAG_STDCALL 0x0
 280 #define FUNCFLAG_CDECL   0x1
 281 #define FUNCFLAG_HRESULT 0x2
 282 #define FUNCFLAG_PYTHONAPI 0x4
 283
 284 #define DICTFLAG_FINAL 0x1000
 285
 286 typedef struct {
 287         PyObject_HEAD
 288         ffi_type *pffi_type;
 289         char tag;
 290         union {
 291                 char c;
 292                 char b;
 293                 short h;
 294                 int i;
 295                 long l;
 296 #ifdef HAVE_LONG_LONG
 297                 PY_LONG_LONG q;
 298 #endif
 299                 double d;
 300                 float f;
 301                 void *p;
 302         } value;
 303         PyObject *obj;
 304         int size; /* for the 'V' tag */
 305 } PyCArgObject;
 306
 307 extern PyTypeObject PyCArg_Type;
 308 extern PyCArgObject *new_CArgObject(void);
 309 #define PyCArg_CheckExact(v)        ((v)->ob_type == &PyCArg_Type)
 310 extern PyCArgObject *new_CArgObject(void);
 311
 312 extern PyObject *
 313 CData_get(PyObject *type, GETFUNC getfunc, PyObject *src,
 314           Py_ssize_t index, Py_ssize_t size, char *ptr);
 315
 316 extern int
 317 CData_set(PyObject *dst, PyObject *type, SETFUNC setfunc, PyObject *value,
 318           Py_ssize_t index, Py_ssize_t size, char *ptr);
 319
 320 extern void Extend_Error_Info(PyObject *exc_class, char *fmt, ...);
 321
 322 struct basespec {
 323         CDataObject *base;
 324         Py_ssize_t index;
 325         char *adr;
 326 };
 327
 328 extern char basespec_string[];
 329
 330 extern ffi_type *GetType(PyObject *obj);
 331
 332 /* exception classes */
 333 extern PyObject *PyExc_ArgError;
 334
 335 extern char *conversion_mode_encoding;
 336 extern char *conversion_mode_errors;
 337
 338 /* Python 2.4 macros, which are not available in Python 2.3 */
 339
 340 #ifndef Py_CLEAR
 341 #define Py_CLEAR(op)                            \
 342         do {                                    \
 343                 if (op) {                       \
 344                         PyObject *tmp = (PyObject *)(op);       \
 345                         (op) = NULL;            \
 346                         Py_DECREF(tmp);         \
 347                 }                               \
 348         } while (0)
 349 #endif
 350
 351 #ifndef Py_VISIT
 352 /* Utility macro to help write tp_traverse functions.
 353  * To use this macro, the tp_traverse function must name its arguments
 354  * "visit" and "arg".  This is intended to keep tp_traverse functions
 355  * looking as much alike as possible.
 356  */
 357 #define Py_VISIT(op)                                    \
 358         do {                                            \
 359                 if (op) {                               \
 360                         int vret = visit((op), arg);    \
 361                         if (vret)                       \
 362                                 return vret;            \
 363                 }                                       \
 364         } while (0)
 365 #endif
 366
 367 /* Python's PyUnicode_*WideChar functions are broken ... */
 368 #if defined(Py_USING_UNICODE) && defined(HAVE_WCHAR_H)
 369 #  define CTYPES_UNICODE
 370 #endif
 371
 372
 373 #ifdef CTYPES_UNICODE
 374 #  undef PyUnicode_FromWideChar
 375 #  define PyUnicode_FromWideChar My_PyUnicode_FromWideChar
 376
 377 #  undef PyUnicode_AsWideChar
 378 #  define PyUnicode_AsWideChar My_PyUnicode_AsWideChar
 379
 380 extern PyObject *My_PyUnicode_FromWideChar(const wchar_t *, Py_ssize_t);
 381 extern int My_PyUnicode_AsWideChar(PyUnicodeObject *, wchar_t *, Py_ssize_t);
 382
 383 #endif
 384
 385 extern void FreeClosure(void *);
 386 extern void *MallocClosure(void);
 387
 388 extern void _AddTraceback(char *, char *, int);
 389
 390 extern PyObject *CData_FromBaseObj(PyObject *type, PyObject *base, Py_ssize_t index, char *adr);
 391
 392 /* XXX better name needed! */
 393 extern int IsSimpleSubType(PyObject *obj);
 394
 395
 396 #ifdef MS_WIN32
 397 extern PyObject *ComError;
 398 #endif
 399
 400 /*
 401  Local Variables:
 402  compile-command: "python setup.py -q build install --home ~"
 403  End:
 404 */