1#ifndef PyObjC_STRUCT_WRAPPER
2#define PyObjC_STRUCT_WRAPPER
3/*!
4 * @header struct-wrapper.h
5 * @abstract Creation of mutable struct-like types
6 * @discussion
7 *      This module defines a function that can be used to create
8 *      types for mutable struct-like types.
9 *
10 *      The struct-like type has the following properties:
11 *
12 *      - Fields can be accessed by name or index (e.g. instances can be
13 *        used as mutable tuples)
14 *      - Instances are not hasable
15 *      - Instances can be pickled
16 *      - Instances can be compared with sequences, and will compare equal
17 *        to a tuple with equal values for the fields.
18 *
19 *      This module also defines a pair of functions to integrate this
20 *      functionality in PyObjC, that is to make it possible to translate
21 *      C structs to instances of these struct-like types.
22 */
23
24/*!
25 * @function PyObjC_MakeStructType
26 * @abstract Create a mutable struct-like type
27 * @param name       Name of the type, should include the module name
28 * @param doc        Docstring for the type
29 * @param tpinit     Optional __init__ method for the type
30 * @param numFields  Number of fields in the type
31 * @param fieldnames Field names, there should be exactly numFields names.
32 * @param pack       Value of 'pragma pack', use -1 for default packing
33 * @result Returns a newly allocated type or NULL
34 * @discussion
35 *    The name, doc and fieldnames should be pointers to static strings,
36 *    this function will not copy them.
37 *
38 *    If tpinit is NULL the type will have a default __init__ that initializes
39 *    the fields to None and uses its arguments to optionally initiaze the
40 *    fields.
41 *
42 */
43PyObject* PyObjC_MakeStructType(
44	const char* name,
45	const char* doc,
46	initproc tpinit,
47	Py_ssize_t numFields,
48	const char** fieldnames,
49	const char* typestr,
50	Py_ssize_t pack);
51
52
53/*!
54 * @function PyObjC_RegisterStructType
55 * @abstract Create a new struct-like type and register it with the bridge
56 * @param signature  Objective-C signature for the struct
57 * @param name       Name of the type, should include the module name
58 * @param doc        Docstring for the type
59 * @param tpinit     Optional __init__ method for the type
60 * @param numFields  Number of fields in the type
61 * @param fieldnames Field names, there should be exactly numFields names.
62 * @param pack       Value of 'pragma pack', use -1 for default packing
63 * @result Returns a newly allocated type or NULL
64 * @discussion
65 *    This function calls PyObjC_MakeStructType(name, doc, tpinit, numFields,
66 *    fieldnames) and then adds the created type to an internal lookup table.
67 *
68 *    PyObjC_CreateRegisteredStruct can then be used to create instances of
69 *    the type.
70 */
71PyObject* PyObjC_RegisterStructType(
72	const char* signature,
73	const char* name,
74	const char* doc,
75	initproc tpinit,
76	Py_ssize_t numFields,
77	const char** fieldnames,
78	Py_ssize_t pack);
79
80/*!
81 * @function PyObjC_CreateRegisteredStruct
82 * @param signature  An Objective-C signature for a struct type
83 * @param len        Length of the signature string
84 * @param objc_signature
85 *                If not null this will be set to the signature that
86 *                was used to register the struct type. This might include
87 *                type codes that are private to PyObjC (such as _C_NSBOOL)
88 *
89 * @result A new instance or NULL
90 * @discussion
91 *     This function will not set an error when it cannot find or create
92 *     a wrapper for the specified Objective-C type.
93 *
94 *     The returned instance is uninitialized, all fields are NULL. The
95 *     __init__ method has not been called.
96 */
97PyObject* PyObjC_CreateRegisteredStruct(const char* signature, Py_ssize_t len, const char** objc_signature, Py_ssize_t* pack);
98
99int PyObjC_RegisterStructAlias(const char* signature, PyObject* type);
100
101#endif /* PyObjC_STRUCT_MEMBER */
102