/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)
 14typedef 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)
 18typedef Py_ssize_t (*readbufferproc)(PyObject *, Py_ssize_t, void **);
 19typedef Py_ssize_t (*writebufferproc)(PyObject *, Py_ssize_t, void **);
 20typedef Py_ssize_t (*segcountproc)(PyObject *, Py_ssize_t *);
 21typedef 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
 51typedef struct tagPyCArgObject PyCArgObject;
 52typedef struct tagCDataObject CDataObject;
 53typedef PyObject *(* GETFUNC)(void *, Py_ssize_t size);
 54typedef PyObject *(* SETFUNC)(void *, PyObject *value, Py_ssize_t size);
 55typedef PyCArgObject *(* PARAMFUNC)(CDataObject *obj);
 56
 57/* A default buffer in CDataObject, which can be used for small C types.  If
 58this buffer is too small, PyMem_Malloc will be called to create a larger one,
 59and this one is not used.
 60
 61Making CDataObject a variable size object would be a better solution, but more
 62difficult in the presence of CFuncPtrObject.  Maybe later.
 63*/
 64union 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
 83struct 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
 96typedef 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;
108extern PyTypeObject CThunk_Type;
109#define CThunk_CheckExact(v)	    ((v)->ob_type == &CThunk_Type)
110
111typedef 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} CFuncPtrObject;
141
142extern PyTypeObject StgDict_Type;
143#define StgDict_CheckExact(v)	    ((v)->ob_type == &StgDict_Type)
144#define StgDict_Check(v)	    PyObject_TypeCheck(v, &StgDict_Type)
145
146extern int StructUnionType_update_stgdict(PyObject *fields, PyObject *type, int isStruct);
147extern int PyType_stginfo(PyTypeObject *self, Py_ssize_t *psize, Py_ssize_t *palign, Py_ssize_t *plength);
148extern int PyObject_stginfo(PyObject *self, Py_ssize_t *psize, Py_ssize_t *palign, Py_ssize_t *plength);
149
150
151
152extern PyTypeObject CData_Type;
153#define CDataObject_CheckExact(v)	((v)->ob_type == &CData_Type)
154#define CDataObject_Check(v)		PyObject_TypeCheck(v, &CData_Type)
155
156extern PyTypeObject SimpleType_Type;
157#define SimpleTypeObject_CheckExact(v)	((v)->ob_type == &SimpleType_Type)
158#define SimpleTypeObject_Check(v)	PyObject_TypeCheck(v, &SimpleType_Type)
159
160extern PyTypeObject CField_Type;
161extern struct fielddesc *getentry(char *fmt);
162
163
164extern PyObject *
165CField_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
170extern PyObject *CData_AtAddress(PyObject *type, void *buf);
171extern PyObject *CData_FromBytes(PyObject *type, char *data, Py_ssize_t length);
172
173extern PyTypeObject ArrayType_Type;
174extern PyTypeObject Array_Type;
175extern PyTypeObject PointerType_Type;
176extern PyTypeObject Pointer_Type;
177extern PyTypeObject CFuncPtr_Type;
178extern PyTypeObject CFuncPtrType_Type;
179extern PyTypeObject StructType_Type;
180
181#define ArrayTypeObject_Check(v)	PyObject_TypeCheck(v, &ArrayType_Type)
182#define ArrayObject_Check(v)		PyObject_TypeCheck(v, &Array_Type)
183#define PointerObject_Check(v)		PyObject_TypeCheck(v, &Pointer_Type)
184#define PointerTypeObject_Check(v)	PyObject_TypeCheck(v, &PointerType_Type)
185#define CFuncPtrObject_Check(v)		PyObject_TypeCheck(v, &CFuncPtr_Type)
186#define CFuncPtrTypeObject_Check(v)	PyObject_TypeCheck(v, &CFuncPtrType_Type)
187#define StructTypeObject_Check(v)	PyObject_TypeCheck(v, &StructType_Type)
188
189extern PyObject *
190CreateArrayType(PyObject *itemtype, Py_ssize_t length);
191
192extern PyMethodDef module_methods[];
193
194extern CThunkObject *AllocFunctionCallback(PyObject *callable,
195					   PyObject *converters,
196					   PyObject *restype,
197					   int flags);
198/* a table entry describing a predefined ctypes type */
199struct 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
208typedef 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 */
222typedef 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 ArrayType_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 CFuncPtrType_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, CFuncPtr 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! */
298extern StgDictObject *PyType_stgdict(PyObject *obj);
299
300/* May return NULL, but does not set an exception! */
301extern StgDictObject *PyObject_stgdict(PyObject *self);
302
303extern int StgDict_clone(StgDictObject *src, StgDictObject *dst);
304
305typedef int(* PPROC)(void);
306
307PyObject *_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
331struct 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
353extern PyTypeObject PyCArg_Type;
354#define PyCArg_CheckExact(v)	    ((v)->ob_type == &PyCArg_Type)
355extern PyCArgObject *new_CArgObject(void);
356
357extern PyObject *
358CData_get(PyObject *type, GETFUNC getfunc, PyObject *src,
359	  Py_ssize_t index, Py_ssize_t size, char *ptr);
360
361extern int
362CData_set(PyObject *dst, PyObject *type, SETFUNC setfunc, PyObject *value,
363	  Py_ssize_t index, Py_ssize_t size, char *ptr);
364
365extern void Extend_Error_Info(PyObject *exc_class, char *fmt, ...);
366
367struct basespec {
368	CDataObject *base;
369	Py_ssize_t index;
370	char *adr;
371};
372
373extern char basespec_string[];
374
375extern ffi_type *GetType(PyObject *obj);
376
377/* exception classes */
378extern PyObject *PyExc_ArgError;
379
380extern char *conversion_mode_encoding;
381extern char *conversion_mode_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#ifdef CTYPES_UNICODE
419#  undef PyUnicode_FromWideChar
420#  define PyUnicode_FromWideChar My_PyUnicode_FromWideChar
421
422#  undef PyUnicode_AsWideChar
423#  define PyUnicode_AsWideChar My_PyUnicode_AsWideChar
424
425extern PyObject *My_PyUnicode_FromWideChar(const wchar_t *, Py_ssize_t);
426extern Py_ssize_t My_PyUnicode_AsWideChar(PyUnicodeObject *, wchar_t *, Py_ssize_t);
427
428#endif
429
430extern void FreeClosure(void *);
431extern void *MallocClosure(void);
432
433extern void _AddTraceback(char *, char *, int);
434
435extern PyObject *CData_FromBaseObj(PyObject *type, PyObject *base, Py_ssize_t index, char *adr);
436extern char *alloc_format_string(const char *prefix, const char *suffix);
437
438/* XXX better name needed! */
439extern int IsSimpleSubType(PyObject *obj);
440
441extern PyObject *_pointer_type_cache;
442PyObject *get_error_object(int **pspace);
443
444#ifdef MS_WIN32
445extern PyObject *ComError;
446#endif
447
448/*
449 Local Variables:
450 compile-command: "python setup.py -q build install --home ~"
451 End:
452*/