Modules/_ctypes/ctypes.h

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